Filament Translations Laravel Package

Getting Started

• Install with Composer: composer require <vendor>/<package>:"^3.0". v3 requires Filament 5 and Laravel 13, so confirm your app is already on those majors (and PHP 8.3+) before upgrading — Composer will otherwise resolve back to the 2.x line.
• If you are coming from 2.x, the import/export surface has moved. Add the new dependency explicitly: composer require cube-agency/filament-excel. Anything you previously imported from this package's own export/import namespaces must be rewritten to the CubeAgency\FilamentExcel\... equivalents.
• Register the plugin (or ->plugin(...) entry) in your panel provider, then run php artisan filament:upgrade followed by php artisan vendor:publish --tag="<package>-config" to pull a fresh config file that matches the 3.0 schema — the old published config will be missing new keys.
• Look first at the package's README upgrade section and the cube-agency/filament-excel docs side by side; this package now owns the Filament integration (actions, bulk actions, resource wiring), while the Excel package owns readers, writers, and export classes.
• First use case: attach an export bulk action to an existing resource table, hit it with a filtered list, and confirm the file lands on the configured disk. That single flow exercises the most integration points (action registration, query passing, queue config, disk config) and surfaces most upgrade breakage.

Implementation Patterns

• Table bulk actions for export. Add the package's bulk action to a ->bulkActions([...]) array on the table. Pass the current table filters/query through so the export respects what the user sees rather than dumping the full table — this is the most common day-to-day pattern and the one most likely to need adjusting after the cube-agency/filament-excel migration.
• Header actions for whole-resource exports. Use a header action when the export should ignore selection and respect only the filtered query. Pair with ->visible() or authorization checks so non-admin users can't pull the entire dataset.
• Queued exports for anything large. Configure the queue connection in the published config and dispatch exports as jobs. Model the job around cube-agency/filament-excel's export class rather than the package's former implementation; the notification-on-completion behaviour now comes from the Excel package and is configured there.
• Custom export classes. Extend the Excel package's base export class and reference it from the action. Keep column mapping, formatting, and ShouldQueue implementation in your own class so the package doesn't dictate your output shape — this also makes the 2.x → 3.x migration mostly a namespace swap in one or two files.
• Imports alongside exports. Since import now lives in the same dependency, standardise on one import flow: the Excel package's import action plus an Importer class implementing row validation. Wire Filament notifications to the importer's failure callbacks so users see row-level errors in the panel rather than in logs.
• Panel-level defaults. Put disk, queue, and default writer type in config/<package>.php and override per-action only when needed. Multi-panel apps should override via ->plugin() configuration rather than editing the shared config file.
• Wrapping in your own action class. If several resources export, create a shared ExportRecordsAction in your app that pre-configures columns and queue settings, then reference it everywhere. This insulates you from the next upstream dependency change.

Gotchas and Tips

• This is a breaking release. The import/export migration to cube-agency/filament-excel changes class namespaces, and possibly action class names and config keys. Grep your codebase for the old namespaces before upgrading; static analysis (phpstan/larastan) catches most of these quickly because the old classes simply won't exist.
• Filament 5 asset pipeline. Run php artisan filament:assets (and clear cached views/components) after upgrading. A stale manifest produces blank table actions or missing JS with no error in the logs — check the browser console before debugging PHP.
• Laravel 13 minimums. PHP 8.3+, and check that any other Filament plugins in your panel also support Filament 5. Mixed major versions in one panel fail at boot with an unhelpful container error; resolve by upgrading all plugins in one commit.
• Config file drift. A published 2.x config will silently miss new 3.x keys (disk, queue connection, writer type), and the package falls back to defaults. Republish and diff, or better, delete the published config and rely on defaults until you actually need overrides.
• Disk and permissions. Exports written to local/private disks need a signed-URL or download action to be reachable from the panel. If downloads 404, verify the disk's url config and that storage:link has run.
• Memory on synchronous exports. Large tables exported without a queue will exhaust memory and time out with Allowed memory size exhausted from the spreadsheet writer. The fix is queueing, not raising memory_limit — but also cap the row count in the action as a safety valve.
• Timezone and date formatting. Excel writers serialise dates differently from Filament's display formatting. Pass explicit DateTimeInterface handling or format strings in the export class; otherwise users report dates shifted by their panel timezone.
• Testing. Use Livewire::test() on the resource list page and call the action, asserting the export job was dispatched (Queue::assertPushed) rather than asserting the file contents. This keeps tests fast and avoids filesystem fakes tangled with the Excel package's internals.
• Extension point to prefer. Wrap the action in your own class rather than subclassing the package's action. It keeps the blast radius of the next dependency migration to a single file.