Statamic Export Laravel Package

Getting Started

• Install with composer require doefom/statamic-export and let Statamic's addon auto-discovery register the service provider; run php artisan vendor:publish --tag=statamic-export-config (or check the README for the exact tag) to get config/statamic-export.php into your app, then php artisan config:clear.
• Look first at three places: the published config file (format, delimiter, storage disk/path, default columns), the README's programmatic examples, and the Actions dropdown in a collection's entry listing in the Control Panel — that's where the export action surfaces for editors without any code.
• First use case: give a client a one-click CSV of a collection. Open the collection in the CP, select entries (or all), run the export action, and confirm a file lands on the configured disk under storage/app/.... Once that round-trip works, move the same export into an Artisan command so it can be scheduled.

Implementation Patterns

Ad-hoc exports for editors. Use the CP bulk action when the request is "can I get this list in Excel?" — no deploy needed. Scope it by selecting a subset of entries, and keep column selection in the config so non-developers get a consistent shape.

Programmatic exports. Wrap the package's export class in an Artisan command or a controller endpoint and drive it from your own query/filter logic. This is the pattern for recurring deliverables (nightly stock list, monthly report) and for anything triggered by a webhook:

// Console command
public function handle()
{
    Export::collection('orders')
        ->site('default')
        ->export(storage_path('exports/orders-' . now()->format('Y-m-d') . '.csv'));
}

Then $schedule->command('export:orders')->dailyAt('02:00') in routes/console.php / the scheduler.

Column mapping as configuration. Define the field handles you want exported once, in config or in a dedicated export class, rather than hand-rolling ->map() on every call site. Blueprint field handles change; keeping the mapping in one place means a single diff when a client renames a field.

Format and delivery. CSV for machine consumption and re-import; XLSX when the file goes to a human. Standardise filenames with a timestamp/version suffix so overwrites don't silently eat history, and push large files to S3 or a mail attachment rather than leaving them on local disk.

Big exports. Anything over a few thousand entries should be queued (ShouldQueue on your wrapper command or a job) and written to a temp path, then moved. Chunk your own query if you're pre-filtering, so the package isn't asked to hold the whole collection in memory.

Testing. Storage::fake('exports') plus an assertion on the generated file's contents is a cheap regression test. Assert on the header row and a couple of known cells; that's exactly where a normalisation change like the one in v0.8.1 will bite you.

Gotchas and Tips

• v0.8.1 normalises all cell values to strings. This is a correctness fix (no more 1/true/null leaking into spreadsheets as mixed types), but it is observable: numbers, booleans and dates now arrive as text. Excel will treat "0123" as a string (good), but it also won't auto-sum a numeric column, and booleans may render as 1/0/"" rather than TRUE/FALSE. If a downstream importer or pivot table expects typed cells, cast explicitly on the consuming side — don't assume the file preserved types.
• Complex fieldtypes don't flatten themselves. Bard, Grid, Replicator, Assets and Entries relation fields typically serialise to JSON or bare IDs. If the client wants "the body text" or "author name", post-process the row (augment the value or resolve the relation) instead of shipping raw JSON.
• Augmented vs. raw values. Statamic distinguishes stored values from augmented/rendered ones; know which the export gives you before promising a client that dates will be formatted or Markdown rendered.
• Multi-site. Always pass the site explicitly. An export scoped to the wrong site is the most common "the file is empty / half empty" bug report.
• CSV + Excel + UTF-8. Excel on Windows will mangle accents and non-Latin scripts without a BOM or the right delimiter. Set the delimiter in config for locales that use ; instead of , — otherwise the whole file lands in one column.
• Permissions. The CP action is only as safe as the role permissions around the collection. Gate programmatic export routes behind the same policies; an export endpoint is a data-exfiltration endpoint.
• Debugging order: confirm the disk in config actually exists and is writable (storage/app/private vs storage/app/public trips people up), check php artisan config:clear after any config edit, then check storage/logs/laravel.log for the underlying exception — the CP action fails quietly-ish.
• Extension points: custom export classes and a config-level column list are the sanctioned way to bend behaviour. Prefer subclassing/wrapping over editing vendor files, so patch releases like this one stay painless. v0.8.1 is a minor patch with no API changes — safe to take, but if you have tests asserting on cell types, run them before deploying.