Filament Excel Laravel Package

Getting Started

The package is a Filament plugin that wires Excel export/import into panel resources, so the fastest path to value is to attach it to one existing Resource rather than building a new one.

1. composer require 3x1io/filament-excel (v1.0.1 or later — the plural-name fix in this release affects generated headings, so don't pin v1.0.0).
2. Publish/merge the config if you need to change disk, queue, chunk size, or default column mapping: php artisan vendor:publish --tag=filament-excel-config.
3. Register the plugin in your panel provider (->plugin(FilamentExcelPlugin::make())) if the version you installed exposes one; otherwise skip straight to step 4 — many builds of this package are action-based and need no provider registration.
4. Look first at the package's src/Actions (or src/Exports / src/Imports) directory to see which Filament action classes are exposed, and at the config file for the export/import defaults. Those two things tell you more about real capability than the README.
5. First use case: add an export action to a ListRecords/ManageRecords page or a table header action for a simple model, download the file, and confirm column headings and date/number formatting match expectations. Then repeat the exercise for an import on a staging database before touching production.

Implementation Patterns

Table header export as the default. Attach the export action to the table rather than to a page action so it inherits current filters, search, and sort. Verify explicitly whether the action exports the filtered query or the raw model query — the two behave very differently for large tables and for user trust.

Queued exports for anything non-trivial. For large datasets, wire the export to a queued job and notify the user (database notification + Filament notification) when the file is ready on the configured disk. Keep the disk configurable per environment: local/S3 for dev, private S3 with signed URLs in production.

Import as a two-step flow. Don't let users import straight into the model. Pattern that holds up: upload → validate & preview the first N rows against your column mapping → confirm → dispatch an import job that writes row-by-row with per-row error collection, then surface a summary (created/updated/failed) as a notification or a small report page. This is where most of your integration work will go; the package gives you the file handling, not your business rules.

Column mapping as config, not code. Define export columns and import mappings in a dedicated class or array keyed by field name, with label, formatter, and validation rules. This keeps the mapping in one place when the schema drifts and makes it easy to reuse the same map between export and import (round-trip: export → edit → re-import).

Model-aware imports. Resolve rows to models via an explicit unique key (not the primary key), apply updateOrCreate semantics you control, cast dates and booleans yourself, and normalise headers (trim, lowercase, snake_case) before matching — real spreadsheets arrive with stray spaces and inconsistent casing.

Test the round trip in CI. A small fixture workbook plus a feature test that runs import → assert counts → export → assert headers is cheap and catches most regressions, including the kind of heading/pluralisation bug fixed in v1.0.1.

Gotchas and Tips

• Pluralisation changed in v1.0.1. Irregular plurals (people, children, etc.) now produce correct headings/labels. If you wrote workarounds or hardcoded heading overrides in v1.0.0 to compensate, revisit them — you may now get double-correction or mismatched labels. Pin ^1.0.1 in composer.json to avoid the old behaviour on fresh installs.
• Memory and timeouts. In-process exports over a few thousand rows will hit PHP memory limits before they hit Excel's limits. Set memory_limit, prefer chunked/queued exports, and be aware that PhpSpreadsheet-style writers hold the whole sheet in memory unless using a streaming writer.
• Formula injection. Sanitise cells beginning with =, +, -, or @ on export; spreadsheets execute them. On import, never eval or trust formula cells.
• Date and locale ambiguity. 01/02/2024 is two different dates depending on who made the file. Force a date format in your mapping, or require ISO strings, and document it for users.
• Header drift on import. Users rename columns. Match on normalised header names with a fuzzy fallback, and fail loudly with a clear mapping error rather than silently importing nulls.
• Queues in dev. QUEUE_CONNECTION=sync masks failures — exports appear instantly locally and silently break in production. Run a real worker (redis/database) locally at least once.
• Storage permissions. Queued jobs run outside the web request; ensure the configured disk is writable by the queue worker user, and that download URLs are generated at read time (signed, expiring) rather than stored.
• Filament version coupling. Filament's action/table APIs move between v2/v3/v4. Check the package's composer.json constraints against your Filament version before upgrading either; action signature changes are the usual breakage point.
• Extension points to lean on. The config file (disk, queue, chunk size, default mappings) and the package's export/import classes are the intended seams — subclass or bind your own implementations via the container rather than editing vendor files, so patch releases like v1.0.1 remain painless to apply.