Filament Excel Laravel Package

Getting Started

v0.1.0 is the first tagged release of YemenOpenSource/filament-excel, and the release notes contain nothing but a changelog link — no feature list, no migration notes, no compatibility matrix. Treat this as an unproven package: read the README and the source tree before you commit to it, and pin the exact version ("yemenopensource/filament-excel": "0.1.0") rather than using a caret constraint.

Minimal path to first value:

1. Install and inspect. composer require yemenopensource/filament-excel:0.1.0 (confirm the exact vendor/package string from the README — forks frequently diverge from the upstream name). Before writing any code, check composer.json for the filament/filament constraint to confirm it targets your Filament major (v3 vs v4), and check whether it pulls maatwebsite/excel, openspout, or raw phpoffice/phpspreadsheet — that dependency dictates most of the API surface and all of the memory behaviour.
2. Publish assets. Run php artisan vendor:publish --provider="YemenOpenSource\FilamentExcel\FilamentExcelServiceProvider" (verify the provider FQCN in the package source; --tag=filament-excel-config if tags are registered). Do this before registering the plugin so you can see the default disk, queue, and file-naming settings.
3. Register the plugin on the panel in your PanelProvider:

->plugin(\YemenOpenSource\FilamentExcel\FilamentExcelPlugin::make())

4. First use case: export one resource's table. Add a header action to a Resource's table() method and export the users list to XLSX. This is the lowest-risk entry point — it is read-only, needs no schema mapping, and immediately shows you whether the package's column-type handling matches your models.

If step 4 fails, stop. A v0.1.0 that cannot export a simple table is not worth debugging; file an issue and move to pxlrbt/filament-excel or alperenersoy/filament-export, both of which have longer track records.

Implementation Patterns

Scope every export to the table's current query. The single most common production bug with Filament export plugins is exporting the entire table while the user believes they exported the filtered view. Wire the export to $this->getFilteredTableQuery() (or the package's equivalent modifyQueryUsing hook) explicitly, and add a feature test that applies a filter and asserts the row count in the generated file.

Separate "export visible columns" from "export the dataset." Users want the table view; finance wants 40 columns including soft-deleted relations. Implement the narrow case as a header action, and the wide case as a dedicated Exporter class with an explicit column definition, so schema changes in the table don't silently break a downstream report consumer.

Push anything over a few thousand rows onto the queue. If the package exposes a ->queue() / ->shouldQueue() modifier, use it and make sure a worker is actually running in every environment that can trigger an export — a stored export that was never generated is a confusing support ticket. Give the export a disk (config('filament-excel.disk')) that is not your public disk, and generate short-lived signed URLs for downloads.

Handle heavy columns before they hit the writer. Wrap relation access with eager loading in the export query. An export of 5,000 rows that lazy-loads user.department per row will do 5,000+ queries and look like a package performance problem when it is a query-shape problem.

For imports, treat the spreadsheet as untrusted input. Map headers to attributes explicitly rather than by string similarity, validate every row before persisting any of them, wrap the batch in a transaction (or import in chunks with a resumable status column), and surface a row-numbered error report back to the user. A silent partial import is worse than a hard failure.

Pin the format contract. If downstream systems consume your exports, snapshot-test the header row and a sample data row. Column renaming is a schema migration for whoever reads those files.

Gotchas and Dependencies

Pre-1.0 semver is doing a lot of work here. 0.1.0 means every subsequent minor release may break you. Do not float the constraint in composer.json, and do not build a client deliverable on it without a fork or a version lock written into the project README.

Version compatibility is unverified. With no release notes, the Filament v3/v4 question is unanswered and the PHP constraint is unknown. Check composer.json and the CI matrix before assuming it installs into your existing panel. Filament plugin APIs moved substantially between majors; a package built for v3 will not load cleanly on v4.

Formula and CSV injection. Any cell value beginning with =, +, -, or @ is interpreted as a formula when the file opens in Excel or Sheets. User-supplied strings (names, notes, free-text fields) flow straight into your export. Confirm whether the package sanitises; if not, prefix with a single quote or escape before writing.

Casts are where exports lie. datetime casts export as raw UTC strings or as Excel serial numbers depending on the writer; enum casts export as the backing value not the label; array/json casts export as Array or blow up; boolean exports as 1/0. Audit every column type against the export output before handing the file to a non-technical user.

Authorization is not automatic. Exports frequently bypass the policies that guard the table UI, especially bulk actions on selected records and any programmatic exporter invocation from a custom page. Verify that a user who cannot viewAny a model cannot export it, and that row-level scoping is applied — this is the finding most likely to appear in a security review.

Queue, disk, and cleanup. Queued exports leave files behind. Check whether the package prunes; if not, schedule a cleanup command. Also confirm the configured disk exists in each environment — a missing storage/app/private/exports directory produces an error that reads like a permissions problem.

Localisation and number formats. Decimal separators, date formats, and currency symbols differ per locale; spreadsheet writers usually emit raw values and let the client format them. If users in multiple locales consume the same export, decide deliberately whether to emit typed values or pre-formatted strings.

Extension points to look for first. The modifyQueryUsing / modifyExportQuery hook (scoping), a custom exporter or column-formatting class (type handling), and a beforeExporting/afterExporting event pair (audit logging). If none of these exist in v0.1.0, the package is a demo rather than a tool — the audit-log hook in particular has no workaround short of forking.

Debugging tip. When an export produces an empty or truncated file, check storage/logs/laravel.log for a swallowed exception before touching the package — these writers routinely catch and log rather than throw, so a silent failure in the UI usually has a stack trace one file away.