Getting Started

This package is a presentation adapter — it wires Filament UI (actions, modals, upload fields, progress notifications) onto a separate import/export core. Expect to install and configure two things: the underlying engine and this Filament layer.

Minimal path:

Install the pair, not just this one.
```
composer require liberusoftware/import-export-filament
```
Then check composer.json of the installed package for its require block — it will pull in the core import/export module it adapts. If it doesn't auto-install, add it explicitly; the adapter alone is inert.
Publish config and migrations.
```
php artisan vendor:publish --tag=import-export-config
php artisan vendor:publish --tag=import-export-migrations
php artisan migrate
```
Tag names are the first thing to verify — run php artisan vendor:publish with no arguments and read the provider list rather than guessing.
Register the plugin on your panel in app/Providers/Filament/AdminPanelProvider.php:
```
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(ImportExportFilamentPlugin::make())
        // ...
}
```
The plugin class name is the single most important symbol to confirm first — open src/ and read the service provider's register()/boot() to see what it binds and which Filament extension points it hooks.
Where to look first, in order: the plugin class → the package's config/*.php → any src/Actions/ or src/Filament/ directory → the README's screenshots. With 0 stars there is no community trail to follow, so the source is the documentation.

First use case — the one worth validating before anything else: attach an import action to a single small Resource table and run a 10-row CSV through it end to end.

// In your Resource's table() method
->headerActions([
    ImportAction::make()->importer(ContactsImporter::class),
    ExportAction::make()->exporter(ContactsExporter::class),
])

Confirm: the modal opens, the file lands on the configured disk, the job (or synchronous handler) runs, and rows appear with correct types. That single loop exercises disk config, queue config, column mapping, and Filament version compatibility — the four things most likely to be broken.

Implementation Patterns

Resource-level vs global actions. Most adapters expose both a table header action (scoped to a Resource, authorization inherited) and a standalone page or global action. Prefer the Resource-scoped form: you get policy checks and tenant scoping for free. Reserve global/page-level imports for admin-only bulk loads where the target model isn't tied to one Resource.

Define the importer/exporter as a dedicated class, not an inline closure. Even when the package allows closures, a named class gives you a testable unit, a place for rules(), and a stable target for ->importer():

class ContactsImporter extends Importer
{
    public function columns(): array
    {
        return [
            'full_name' => ['name', 'full name'],   // aliases for header drift
            'email'     => ['email', 'e-mail'],
            'company'   => ['company', 'organisation'],
        ];
    }

    public function rules(): array
    {
        return ['email' => ['required', 'email', 'unique:contacts,email']];
    }
}

Column aliasing is the single highest-value configuration: real-world spreadsheets never match your schema, and a mapping table in config beats a mapping UI for repeat imports.

Two-phase imports for anything user-facing. Separate upload + validate from commit. Show a preview/count step ("142 of 150 rows valid, 8 will be skipped") before writing. If the package ships a preview or dry-run mode, use it; if not, run the importer against a transaction you roll back.

Queue anything above ~500 rows. Synchronous imports inside a Filament action will hit max_execution_time and give the user a white screen with no feedback. Configure the queue connection explicitly and make sure the worker is running in every environment, including staging:

// config/import-export.php (verify key names against the published file)
'queue' => env('IMPORT_EXPORT_QUEUE', 'default'),
'chunk_size' => 500,
'disk' => env('IMPORT_EXPORT_DISK', 'local'),

Exports: scope the query, don't filter after. The exporter should receive the already-constrained Builder (including any Filament table filters), not the full model. If the adapter offers ->modifyQueryUsing(), use it to enforce tenancy:

ExportAction::make()
    ->exporter(ContactsExporter::class)
    ->modifyQueryUsing(fn ($query) => $query->where('tenant_id', filament()->getTenant()->id));

Integration with existing Filament features. Wrap the actions in your usual ->visible(fn () => auth()->user()->can('import', Contact::class)). If the package registers policies or gates, check them — a bulk import is a mass-write primitive and deserves its own permission, separate from create.

Gotchas and Tips

License is NOASSERTION. This is not "MIT with a typo" — it means the license file is missing, unrecognised, or contradictory. Get a human to read LICENSE in the repo before this touches a commercial codebase. This is a hard blocker for many orgs and worth checking before you invest integration time.
Zero stars, zero dependents means zero field-testing. Treat the package as first-party code you now own. Pin the exact version in composer.json (no ^), commit composer.lock, and read src/ before upgrading. Expect breaking changes between minor versions and no deprecation path.
Filament major-version mismatch is the most likely install failure. Filament v3 and v4 plugin contracts differ in panel registration and action APIs. Check the package's composer.json constraint against your installed Filament before debugging anything else.
The "last release 2026-10-26" date is in the future. Either the metadata is wrong, the version tag is a placeholder, or the repository state is inconsistent. Run composer show liberusoftware/import-export-filament after install to see what you actually got, and check whether the tag exists on GitHub.
Disk and temp-file lifecycle. Default to a private disk, not public. Uploaded files and generated exports are PII. Confirm the package cleans up temp files — if it doesn't, schedule a prune command, because orphaned CSVs in storage/app are a compliance finding waiting to happen.
Header normalisation bites on real files. BOM markers, trailing spaces, non-breaking spaces, and mixed case in headers are extremely common from Excel exports. Normalise headers (trim, Str::slug, strip \xEF\xBB\xBF) before mapping. If the package does this already, verify with a genuinely messy file — don't assume.
Debugging silent failures. When an import "does nothing," check in this order: (1) queue worker running? (2) job in failed_jobs? (3) file actually written to the configured disk? (4) validation failures silently swallowed — most importers collect row errors into a result object rather than throwing, so log the returned error collection explicitly. Add a temporary Log::info() in the importer's handle() to confirm it's reached at all.
Extension points to prefer. Rather than forking, look for: a config-driven importer/exporter map, Macroable traits on the action classes, overridable Blade views (publishable), and ->before() / ->after() hooks on the Filament action. Filament actions are macroable by default, so ImportAction::macro(...) is often the cleanest seam. Forking a 0-star package you can't upstream to is a maintenance dead end.
Write your own tests around the seam. Don't test the package's modals. Test that your importer class maps a fixture CSV to the expected models, and use Storage::fake() plus Queue::fake() so the suite never touches real files or workers. That gives you a regression net when you eventually replace this dependency — which, given the signals above, you should plan for.

Import Export Filament Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips