Search by

solution-forest / filament-import-wizard

solutionforest

Import and export CSV and Excel in Filament v5: a four-step upload, map, review, import wizard with live preview, row-by-row validation before import, huge-file support, round-trip export, audit/approval and a headless API.

Package info

github.com/solutionforest/filament-import-wizard

Documentation

pkg:composer/solution-forest/filament-import-wizard

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.13.0 2026-11-19 11:23 UTC

This package is auto-updated.

Last update: 2026-11-19 11:27:57 UTC


README

Filament Import Wizard: import and export CSV and Excel with a map, review, import wizard

Filament Import Wizard

Import and export CSV and Excel in Filament: map the columns, check every row, then import.

PHP 8.2–8.4 Laravel 12–13 Filament 5 PHPStan level 10 CI Release 0.13.0 License: MIT

Your users have a spreadsheet; your Filament app needs the rows. This package gives you a four-step Upload → Map → Review → Import wizard for Filament v5 that accepts CSV and Excel files, shows every row checked before anything is written, and imports files of any size. It also exports a list back to Excel / CSV in the layout the importer reads, so files round-trip, and the same engine is available as a plain API class when you need no screen. It sits on top of Filament's own Importer classes, so your existing importers work unchanged.

Upload a file → map the columns → review every row → import (queued) → export it back whenever you like

You provide: a Filament Importer (columns and rules), and where to put the button or page. The package provides: the wizard, the live preview, the validation (with a verified fast path), chunked uploads, export and templates, an optional audit trail and approval flow, and a headless API.

Filament Import Wizard: the Review step checks every row and highlights the problems before anything is imported

What you get

Feature What it does
Four-step import wizard Upload → Map → Review → Import, as a page or in a slide-over opened from a button on any list page, with optional start / done Filament notifications
Quick start from a model ImportWizardAction::make()->forModel(Product::class) builds the importer from the table (types, nullability, lengths become casts and rules) — quick start
Translatable fields One column per language (title_en, title_ar) becomes one translated attribute, with auto-mapping and per-language validation — translatable
CSV, XLSX, XLS, ODS Multi-sheet workbooks, odd encodings (UTF-16, Windows-1252) and delimiters handled; typed cells (dates, booleans, formula results) read right — file formats
Works with your spreadsheet library Files from maatwebsite/excel, spatie/simple-excel, rap2hpoutre/fast-excel, the box/spout engine of nikazooz/laravel-simplesheet and xlswriter-format files import cleanly, and our exports read back in them — tested with the real libraries — interop
Smart column mapping Matched by name, label, aliases and fuzzy similarity; sample values under each field; required columns enforced
Live preview tables See how the first rows will be imported while you map, and the first rows with ✓ / ✕ and highlighted problem cells in Review
Check before you import Every row validated with your importer's own rules, with exact messages, error counts per column and the first failing rows — how it works
One rules class for forms and imports Define a record's rules once (FieldRules) and use them in the Filament form, the importer and an API — rules
File-level checks e.g. duplicates inside the file, in constant memory (UniqueInFile) — rules
Fast A verified fast path validates 50,000 rows in under a second (fuzz-, exhaustive- and mutation-tested against Laravel) — performance
Huge files Streamed, never loaded into memory; resumable chunked upload with no PHP size limit; a console command for multi-GB files — large files
Export that round-trips (互通) Excel / CSV download of any list (filters and sorting applied) in the importer's own layout, a blank import template, and verify() to prove the file would import cleanly — export
Headless API HeadlessImport runs the same upload → map → review → import pipeline from an API endpoint, a job or a command — headless API
Audit trail (optional) Who imported what (file SHA-256, mapping, review result, outcome) with an immutable event history and an Import audit page — audit
Approval flow (optional) Maker–checker: hold an import for a second person, by rule (e.g. over 1,000 rows) — audit & approval
Multi-panel, multi-server Per-panel disk, directory and limits; shared-disk / database-backed state so any server can take any request; Horizon and Octane notes — scaling
Translated English, 简体中文, 繁體中文 (TW / HK); plural-aware, locale-aware numbers and dates, RTL-safe — localization
Secure by default Locked wizard state, escaped output, confined uploads, allow-listed importer options, CSV formula guard on export; dedicated security tests and composer audit in CI
Quality gates PHPStan level 10, 130 Pest tests, security group, differential fuzz, mutation test, 50k–200k-row stress tests, CI matrix (PHP 8.2–8.4 × Laravel 12/13) — testing

Video tutorial

Watch the tutorial

▶ Watch the tutorial (mp4, 115 s) — the slide-over import from a list page with Filament notifications; then upload an Excel file, map columns with a live preview, review every row, submit for approval, approve and read the audit trail; then a 50,000-row file (chunked upload, reviewed in about two seconds) and the interface in Hong Kong Traditional Chinese. Chapters and how it was recorded: docs/video-tutorial.md.

Supported versions

Package PHP Laravel Filament Livewire Status
0.10 – 0.13 8.2 – 8.4 ¹ 12 ✅ · 13 ✅ · 11.28+ ² 5.x (tested on 5.11) 4.x (via Filament 5) Current
0.2 – 0.9 8.2 – 8.4 ¹ 12 · 13 5.x 4.x Superseded — upgrade to 0.13
— — — 3.x · 4.x — Not supported (built on Filament 5's importer and schema APIs)

✅ = the full test suite (Pest, 130 tests + fuzz, mutation and stress suites) passes on it · ¹ run on PHP 8.4; 8.2 and 8.3 are allowed by the constraints but were not run · ² allowed by Filament 5, not run — every Laravel 11.x release is currently flagged by Composer security advisories, so upgrade to 12+.

Environment Status
Queue sync (tested), database / redis / sqs via Filament batches · Horizon: supported — see Scaling
Octane Code-reviewed for state leaks; not run under a live Octane server — see Scaling
Database SQLite (tested). MySQL / PostgreSQL use only standard Laravel query-builder calls but were not run here
File storage local (tested). Any Flysystem disk (S3, NFS…) is supported by design; S3 was not run here
Browsers Chromium (tested)

Release notes: CHANGELOG.md.

Install

composer config repositories.filament-import-wizard vcs https://github.com/solutionforest/filament-import-wizard.git
composer require solution-forest/filament-import-wizard:^0.13
php artisan migrate

You also need Filament's import tables and a queue worker — see Installation.

Quick start

1. Make a page for an importer you already have

use SolutionForest\FilamentImportWizard\Pages\ImportWizardPage;

class ImportContacts extends ImportWizardPage
{
    protected static ?string $importer = ContactImporter::class;
}

2. Register it on a panel

use SolutionForest\FilamentImportWizard\ImportWizardPlugin;

$panel->plugin(ImportWizardPlugin::make()->pages([ImportContacts::class]));

3. Open the page — upload, map, review, import. That's it.

Prefer a button on a list page? The same wizard opens in a slide-over with Filament notifications:

protected function getHeaderActions(): array
{
    return [ImportWizardAction::make()->importer(ContactImporter::class)];
}

And the matching export button, plus the same pipeline as an API with no screen:

ExportFileAction::make()->importer(ContactImporter::class)      // Excel / CSV / blank template, re-importable

$review = HeadlessImport::for(ContactImporter::class)->upload($request->file('file'))->autoMap()->review();
$review->isValid() && $import->user($user)->start();            // queued, like the wizard
Button on the list page Map, in the slide-over Review, in the slide-over Done, with notifications
List Map Review Done

Documentation

Installation Composer, migrations, queue
Usage The page, the plugin, several panels
How it works The four steps, mapping, preview
Export Excel / CSV export and templates that round-trip with the importer
Headless API Import from an API / job / command, no screen
Slide-over action Open the wizard from a button, with start / done notifications
Rules One rules class for forms and imports; file-level checks
File formats CSV, Excel, encodings, sheets
Quick start from a model No importer class yet: generate one from the table
Translatable fields One column per language into one translated attribute
Other spreadsheet libraries maatwebsite/excel, spatie/simple-excel, fast-excel, simplesheet, xlswriter
Large files Chunked upload, console import
Audit & approval Optional trail and maker–checker
Scaling Several servers, Horizon, Octane
Configuration Every option in one place
Localization Languages, overriding texts, adding a locale
Performance Stress test results (50k–200k rows) and how to run them
Testing How the fast validation path is verified (fuzz, exhaustive, mutation)
Video tutorial Chapters and how it was recorded

Try the demo

git clone https://github.com/solutionforest/filament-import-wizard.git && cd filament-import-wizard
composer install && composer serve      # http://127.0.0.1:8765/admin

Upload workbench/samples/contacts.xlsx. The demo README explains what to click and where each piece lives.

Development

composer check     # Pint + PHPStan level 10 + Pest + security tests + composer audit
composer stress    # 50,000-row stress test (flat memory, exact counts)
composer security  # security tests (XSS, traversal, tampering, authorisation, uploads) + dependency audit
composer fuzz      # 300,000-case differential fuzz of the fast validation path vs Laravel
composer mutate    # mutation test of the fast path

MIT — see LICENSE.