PHPackages                             superbig/craft3-beam - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. superbig/craft3-beam

ActiveCraft-plugin[File & Storage](/categories/file-storage)

superbig/craft3-beam
====================

Generate CSVs and XLS files in your templates

5.0.0(2y ago)1934.2k↓54.9%6[2 issues](https://github.com/sjelfull/craft3-beam/issues)[1 PRs](https://github.com/sjelfull/craft3-beam/pulls)MITPHP

Since Nov 1Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/sjelfull/craft3-beam)[ Packagist](https://packagist.org/packages/superbig/craft3-beam)[ RSS](/packages/superbig-craft3-beam/feed)WikiDiscussions main Synced yesterday

READMEChangelog (9)Dependencies (6)Versions (15)Used By (0)

Beam for Craft CMS
==================

[](#beam-for-craft-cms)

[![Latest Version](https://camo.githubusercontent.com/5f94f49f6d39e855a7a1b83ffee131ec75d88d4d513d99fe035cbbdbc5b62c1f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f736a656c66756c6c2f6372616674332d6265616d2e7376673f7374796c653d666c61742d737175617265)](https://github.com/sjelfull/craft3-beam/releases)[![License](https://camo.githubusercontent.com/1b95e83e2a8cece492a8f14b5494353a93e9f02001215609f6dfa3753a354e8f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736a656c66756c6c2f6372616674332d6265616d2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

> Generate CSV and Excel (XLSX) files directly from your Craft CMS templates

[![Screenshot](resources/img/plugin-logo.png)](resources/img/plugin-logo.png)

Table of contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Usage guide](#usage-guide)
    - [Basic usage](#basic-usage)
    - [Output formats](#output-formats)
    - [Dynamic content](#dynamic-content)
    - [Configuration methods](#configuration-methods)
- [Advanced features](#advanced-features)
    - [Custom cell formatting](#custom-cell-formatting)
    - [Supported format types](#supported-format-types)
    - [Multiple sheets](#multiple-sheets-xlsx-only)
    - [Soft newlines](#soft-newlines-in-xlsx-cells)
- [Common use cases](#common-use-cases)
- [Load-balanced environments](#load-balanced-environments)
- [About](#about)

Requirements
------------

[](#requirements)

- Craft CMS 5.0.0 or later
- PHP 8.2 or later

Legacy version supportFor older Craft CMS versions:

- **Craft 4**: Use Beam 3.x
- **Craft 3**: Use Beam 2.x

Installation
------------

[](#installation)

Install via Composer from your Craft project directory:

```
composer require superbig/craft3-beam
```

> **Note:** The package name is `superbig/craft3-beam` for all Craft CMS versions (3, 4, and 5). The version automatically installed matches your Craft version.

Then install the plugin in the Craft Control Panel:

1. Go to **Settings → Plugins**
2. Find **Beam** and click **Install**

Quick start
-----------

[](#quick-start)

Generate a CSV file with just a few lines:

```
{% set beam = craft.beam.create({
    header: ['Name', 'Email'],
    content: [
        ['John Doe', 'john@example.com'],
        ['Jane Doe', 'jane@example.com']
    ]
}) %}
{% do beam.csv() %}
```

That's it! The file will automatically download in the user's browser.

Usage guide
-----------

[](#usage-guide)

### Basic usage

[](#basic-usage)

Every Beam export starts by creating a Beam instance with `craft.beam.create()`:

```
{% set beam = craft.beam.create({
    header: ['Email', 'Name'],
    content: [
        ['test@example.com', 'John Doe'],
        ['another@example.com', 'Jane Doe'],
        ['third@example.com', 'Trond Johansen']
    ]
}) %}
```

### Output formats

[](#output-formats)

#### Generate CSV

[](#generate-csv)

```
{% do beam.csv() %}
```

#### Generate Excel (XLSX)

[](#generate-excel-xlsx)

```
{% do beam.xlsx() %}
```

### Dynamic content

[](#dynamic-content)

Build your export dynamically using loops and the `append()` method:

```
{# Create beam with headers #}
{% set beam = craft.beam.create({
    header: ['Username', 'Name', 'Email']
}) %}

{# Append data from entries or users #}
{% set users = craft.users().group('authors').all() %}
{% for user in users %}
    {% do beam.append([user.username, user.name, user.email]) %}
{% endfor %}

{# Generate the file #}
{% do beam.csv() %}
```

### Configuration methods

[](#configuration-methods)

Beam provides several methods to customize your export:

**Set Custom Filename**```
{% set currentDate = now|date('Y-m-d') %}
{% do beam.setFilename("user-report-#{currentDate}") %}
```

**Update Headers**```
{% do beam.setHeader(['Username', 'Full Name', 'Email Address']) %}
```

**Replace Content**```
{% do beam.setContent([
    ['test@example.com', 'John Doe'],
    ['another@example.com', 'Jane Doe']
]) %}
```

Advanced features
-----------------

[](#advanced-features)

### Custom cell formatting

[](#custom-cell-formatting)

Excel (XLSX) files support custom cell formatting. Define column types in the header:

```
{% set beam = craft.beam.create({
    header: [
        'Email',
        'Name',
        { text: 'Amount', type: 'price' },
        { text: 'Date', type: 'date' }
    ],
    content: [
        ['john@example.com', 'John Doe', 1500.50, '2024-01-15'],
        ['jane@example.com', 'Jane Doe', 2300.75, '2024-01-16']
    ]
}) %}
{% do beam.xlsx() %}
```

### Supported format types

[](#supported-format-types)

TypeExcel FormatExample Outputstring@Textinteger012345dateYYYY-MM-DD2024-01-15datetimeYYYY-MM-DD HH:MM:SS2024-01-15 14:30:00timeHH:MM:SS14:30:00price\#,##0.001,234.56dollar\[$$-1009\]#,##0.00;\[RED\]-\[$$-1009\]#,##0.00$1,234.56euro\#,##0.00 \[$€-407\];\[RED\]-#,##0.00 \[$€-407\]€1.234,56### Multiple sheets (XLSX only)

[](#multiple-sheets-xlsx-only)

You can create an Excel file with multiple sheets using the fluent `sheet()` method:

```
{% set beam = craft.beam.create() %}
{% do beam.setFilename('users-by-group') %}

{# Create and populate sheets using fluent methods #}
{% for group in craft.users.groups() %}
    {% set users = craft.users().group(group.handle).all() %}

    {# Select/create a sheet and set its header #}
    {% do beam.sheet(group.name).setHeader(['Email', 'Full Name']) %}

    {# Append users to the active sheet #}
    {% for user in users %}
        {% do beam.append([user.email, user.fullName]) %}
    {% endfor %}
{% endfor %}

{% do beam.xlsx() %}
```

You can switch between sheets as needed:

```
{% set beam = craft.beam.create() %}

{# Set 'Summary' as the active sheet #}
{% do beam.setSheet('Summary') %}
{% do beam.setHeader(['Total Users', 'Active', 'Inactive']) %}
{% do beam.append([100, 75, 25]) %}

{# Switch to 'Details' sheet #}
{% do beam.sheet('Details').setHeader(['Email', 'Name', 'Status']) %}
{% do beam.append(['john@example.com', 'John', 'Active']) %}

{% do beam.xlsx() %}
```

**More sheet configuration options**The `sheet()` method also accepts an options array as the second parameter:

```
{% do beam.sheet('Products', {
    header: ['ID', 'Name', 'Price']
}) %}
{% do beam.append(['1', 'Product A', '10.00']) %}
```

#### Alternative: Using array-based configuration

[](#alternative-using-array-based-configuration)

If you need to configure all sheets upfront, you can provide a `sheets` array in the options:

```
{% set options = {
    filename: 'users-report',
    sheets: [
        {
            name: 'Active Users',
            header: ['Email', 'Name', 'Status'],
            content: [
                [ 'john@example.com', 'John Doe', 'Active' ],
                [ 'jane@example.com', 'Jane Doe', 'Active' ],
            ]
        },
        {
            name: 'Inactive Users',
            header: ['Email', 'Name', 'Status'],
            content: [
                [ 'inactive@example.com', 'Bob Smith', 'Inactive' ],
            ]
        }
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

Or build the sheets array dynamically with `setSheets()`:

```
{% set beam = craft.beam.create() %}
{% do beam.setFilename('users-by-group') %}

{% set sheets = [] %}
{% for group in craft.users.groups() %}
    {% set users = craft.users().group(group.handle).all() %}
    {% set sheetContent = [] %}
    {% for user in users %}
        {% set sheetContent = sheetContent|merge([[ user.email, user.fullName ]]) %}
    {% endfor %}

    {% set sheets = sheets|merge([{
        name: group.name,
        header: ['Email', 'Full Name'],
        content: sheetContent
    }]) %}
{% endfor %}

{% do beam.setSheets(sheets) %}
{% do beam.xlsx() %}
```

**Note:** The `sheets` configuration only works with XLSX exports. If you use it with `csv()`, it will be ignored and a standard single-sheet CSV will be generated.

### Soft newlines in XLSX cells

[](#soft-newlines-in-xlsx-cells)

Soft newlines (line breaks within cells) are supported in XLSX files. Simply use `\n` in your cell content:

```
{% set options = {
    header: ['Name', 'Address'],
    content: [
        [ 'John Doe', "123 Main St\nApt 4B\nNew York, NY" ],
        [ 'Jane Smith', "456 Oak Ave\nSuite 200\nLos Angeles, CA" ],
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

You can also join arrays with newlines to create multi-line cells:

```
{% set myArray = ['Item 1', 'Item 2', 'Item 3'] %}
{% set options = {
    header: ['Name', 'Items'],
    content: [
        [ 'Order 1', myArray|join("\n") ],
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

Text wrapping is enabled by default to properly display multi-line content. If you need to disable it:

```
{% do beam.setWrapText(false) %}
```

Common use cases
----------------

[](#common-use-cases)

**Export Entry Data**```
{% set beam = craft.beam.create({
    header: ['Title', 'Author', 'Date Published', 'URL']
}) %}

{% set entries = craft.entries()
    .section('blog')
    .orderBy('postDate DESC')
    .all() %}

{% for entry in entries %}
    {% do beam.append([
        entry.title,
        entry.author.fullName,
        entry.postDate|date('Y-m-d'),
        entry.url
    ]) %}
{% endfor %}

{% do beam.csv() %}
```

**Export Commerce Orders**> **Note:** This example requires [Craft Commerce](https://craftcms.com/commerce) to be installed.

```
{% set beam = craft.beam.create({
    header: ['Order Number', 'Customer', 'Total', 'Date', 'Status']
}) %}

{% set orders = craft.orders()
    .isCompleted(true)
    .orderBy('dateOrdered DESC')
    .all() %}

{% for order in orders %}
    {% do beam.append([
        order.number,
        order.email,
        order.totalPrice,
        order.dateOrdered|date('Y-m-d'),
        order.orderStatus
    ]) %}
{% endfor %}

{% do beam.xlsx() %}
```

**Export with Formatted Numbers**```
{% set beam = craft.beam.create({
    header: [
        'Product',
        { text: 'Price', type: 'dollar' },
        { text: 'Quantity', type: 'integer' },
        { text: 'Total', type: 'dollar' }
    ]
}) %}

{% set products = craft.entries().section('products').all() %}
{% for product in products %}
    {% do beam.append([
        product.title,
        product.price,
        product.stock,
        product.price * product.stock
    ]) %}
{% endfor %}

{% do beam.xlsx() %}
```

Load-balanced environments
--------------------------

[](#load-balanced-environments)

If you're running on a load-balanced environment (like Fortrabbit, Servd, or Craft Cloud), you may experience intermittent download failures when temporary files are stored on the local filesystem.

Configure Craft to use a shared filesystem for temporary files by setting `tempAssetUploadFs` in your `config/general.php`:

```
return [
    '*' => [
        'tempAssetUploadFs' => 's3', // use your filesystem handle
    ],
];
```

Or use the `CRAFT_TEMP_ASSET_UPLOAD_FS` environment variable.

See the [Craft documentation](https://craftcms.com/docs/5.x/reference/config/general.html#tempassetuploadfs) for more details.

About
-----

[](#about)

### Multiple sheets in Excel (XLSX only):

[](#multiple-sheets-in-excel-xlsx-only)

You can create an Excel file with multiple sheets using the fluent `sheet()` method:

```
{% set beam = craft.beam.create() %}
{% do beam.setFilename('users-by-group') %}

{# Create and populate sheets using fluent methods #}
{% for group in craft.users.groups() %}
    {% set users = craft.users().group(group.handle).all() %}

    {# Select/create a sheet and set its header #}
    {% do beam.sheet(group.name).setHeader(['Email', 'Full Name']) %}

    {# Append users to the active sheet #}
    {% for user in users %}
        {% do beam.append([user.email, user.fullName]) %}
    {% endfor %}
{% endfor %}

{% do beam.xlsx() %}
```

You can switch between sheets as needed:

```
{% set beam = craft.beam.create() %}

{# Set 'Summary' as the active sheet #}
{% do beam.setSheet('Summary') %}
{% do beam.setHeader(['Total Users', 'Active', 'Inactive']) %}
{% do beam.append([100, 75, 25]) %}

{# Switch to 'Details' sheet #}
{% do beam.sheet('Details').setHeader(['Email', 'Name', 'Status']) %}
{% do beam.append(['john@example.com', 'John', 'Active']) %}

{% do beam.xlsx() %}
```

The `sheet()` method also accepts an options array as the second parameter:

```
{% do beam.sheet('Products', {
    header: ['ID', 'Name', 'Price']
}) %}
{% do beam.append(['1', 'Product A', '10.00']) %}
```

#### Alternative: Using array-based configuration

[](#alternative-using-array-based-configuration-1)

If you need to configure all sheets upfront, you can provide a `sheets` array in the options:

```
{% set options = {
    filename: 'users-report',
    sheets: [
        {
            name: 'Active Users',
            header: ['Email', 'Name', 'Status'],
            content: [
                [ 'john@example.com', 'John Doe', 'Active' ],
                [ 'jane@example.com', 'Jane Doe', 'Active' ],
            ]
        },
        {
            name: 'Inactive Users',
            header: ['Email', 'Name', 'Status'],
            content: [
                [ 'inactive@example.com', 'Bob Smith', 'Inactive' ],
            ]
        }
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

Or build the sheets array dynamically with `setSheets()`:

```
{% set beam = craft.beam.create() %}
{% do beam.setFilename('users-by-group') %}

{% set sheets = [] %}
{% for group in craft.users.groups() %}
    {% set users = craft.users().group(group.handle).all() %}
    {% set sheetContent = [] %}
    {% for user in users %}
        {% set sheetContent = sheetContent|merge([[ user.email, user.fullName ]]) %}
    {% endfor %}

    {% set sheets = sheets|merge([{
        name: group.name,
        header: ['Email', 'Full Name'],
        content: sheetContent
    }]) %}
{% endfor %}

{% do beam.setSheets(sheets) %}
{% do beam.xlsx() %}
```

**Note:** The `sheets` configuration only works with XLSX exports. If you use it with `csv()`, it will be ignored and a standard single-sheet CSV will be generated.

### Soft newlines in XLSX cells:

[](#soft-newlines-in-xlsx-cells-1)

Soft newlines (line breaks within cells) are supported in XLSX files. Simply use `\n` in your cell content:

```
{% set options = {
    header: ['Name', 'Address'],
    content: [
        [ 'John Doe', "123 Main St\nApt 4B\nNew York, NY" ],
        [ 'Jane Smith', "456 Oak Ave\nSuite 200\nLos Angeles, CA" ],
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

You can also join arrays with newlines to create multi-line cells:

```
{% set myArray = ['Item 1', 'Item 2', 'Item 3'] %}
{% set options = {
    header: ['Name', 'Items'],
    content: [
        [ 'Order 1', myArray|join("\n") ],
    ]
} %}
{% set beam = craft.beam.create(options) %}
{% do beam.xlsx() %}
```

Text wrapping is enabled by default to properly display multi-line content. If you need to disable it:

```
{% do beam.setWrapText(false) %}
```

Load-balanced environments
--------------------------

[](#load-balanced-environments-1)

If you're running on a load-balanced environment (like Fortrabbit, Servd, or Craft Cloud), you may experience intermittent download failures when temporary files are stored on the local filesystem.

Configure Craft to use a shared filesystem for temporary files by setting `tempAssetUploadFs` in your `config/general.php`:

```
return [
    '*' => [
        'tempAssetUploadFs' => 's3', // use your filesystem handle
    ],
];
```

Or use the `CRAFT_TEMP_ASSET_UPLOAD_FS` environment variable.

See the [Craft documentation](https://craftcms.com/docs/5.x/reference/config/general.html#tempassetuploadfs) for more details.

Brought to you by [Superbig](https://superbig.co)

**Useful Resources:**

- [Report Issues](https://github.com/sjelfull/craft3-beam/issues)
- [View Changelog](https://github.com/sjelfull/craft3-beam/blob/main/CHANGELOG.md)
- [Superbig Website](https://superbig.co)

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance46

Moderate activity, may be stable

Popularity36

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 78.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~295 days

Recently: every ~477 days

Total

9

Last Release

800d ago

Major Versions

2.1.5 → 3.0.02022-10-03

3.0.0 → 5.0.02024-04-24

### Community

Maintainers

![](https://www.gravatar.com/avatar/800b029eac606eb58930bcdf0d887e14aa63c31a203744c30befca8a58aa79b4?d=identicon)[superbig](/maintainers/superbig)

---

Top Contributors

[![sjelfull](https://avatars.githubusercontent.com/u/10508?v=4)](https://github.com/sjelfull "sjelfull (25 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (4 commits)")[![alexmglover](https://avatars.githubusercontent.com/u/375765?v=4)](https://github.com/alexmglover "alexmglover (1 commits)")[![brandonkelly](https://avatars.githubusercontent.com/u/47792?v=4)](https://github.com/brandonkelly "brandonkelly (1 commits)")[![wbrowar](https://avatars.githubusercontent.com/u/2158662?v=4)](https://github.com/wbrowar "wbrowar (1 commits)")

---

Tags

craftcraft3craftcmscraftcms-plugincmsCraftcraftcmscraft-pluginbeam

### Embed Badge

![Health badge](/badges/superbig-craft3-beam/health.svg)

```
[![Health](https://phpackages.com/badges/superbig-craft3-beam/health.svg)](https://phpackages.com/packages/superbig-craft3-beam)
```

###  Alternatives

[craftcms/feed-me

Import content from XML, RSS, CSV or JSON feeds into entries, categories, Craft Commerce products, and more.

293952.6k33](/packages/craftcms-feed-me)[verbb/formie

The most user-friendly forms plugin for Craft.

102393.6k69](/packages/verbb-formie)[verbb/vizy

A flexible visual editor field for Craft.

4250.4k](/packages/verbb-vizy)[verbb/hyper

A user-friendly links field for Craft.

24147.8k12](/packages/verbb-hyper)[verbb/events

A full-featured plugin for event management and ticketing.

2311.9k](/packages/verbb-events)[nystudio107/craft-webperf

Webperf helps you build & maintain high quality websites through Real User Measurement of your website's performance

2441.0k1](/packages/nystudio107-craft-webperf)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)