Download the PHP package martin6363/filament-smart-import without Composer

Filament Smart Import

A premium Filament plugin for Laravel that imports CSV and XLSX spreadsheets with staging, inline validation, relationship resolution, upsert, and background batch processing.

Built for production admin panels where imports must be reviewed before records are written to the database.

Requirements

• PHP 8.2 or higher
• Laravel 11, 12, or 13
• Filament 4 or 5
• OpenSpout 4.x (installed automatically)
• A configured queue worker for background imports

Optional integrations:

• Spatie Translatable for locale-specific columns
• Any Eloquent model with a $fillable definition

Installation

Demo Video

Watch the walkthrough to see Filament Smart Import in action, including Spatie Translatable support, relationship lookups, and real-time staging table editing:

💡 Watch on Demo: Filament Smart Import - Complete Walkthrough & Feature Overview

Purchase License

Filament Smart Import is a commercial package. You can purchase a valid license key from our official checkout:

Buy License Key ($39 – $139)
(Single Domain: $39 | Unlimited Agency: $139)

1. Require the package

2. Add your license key

After purchasing from Lemon Squeezy, add your license key to .env:

3. Run migrations

4. Register the plugin

5. Publish plugin assets

Note: Do not commit license keys or auth.json credentials to version control.

Queue Setup

Imports are processed asynchronously after the user confirms the staged data. Configure a queue connection and run a worker:

The default queue connection is read from config/filament-smart-import.php (queue_connection). The database driver is used by default.

Basic Usage

Add SmartImportAction to any Filament resource page, typically on a list page header action.

With Spatie Translatable

Use translatable() and locales() when the model stores translations in JSON via Spatie Translatable:

Spreadsheet columns are expanded per locale: title_en, title_ru, content_en, content_ru.

Validation rules use dot notation: title.en, not title_en.

Without Spatie Translatable (Flat Columns)

When locale-specific values are stored as separate database columns, do not call translatable() or locales(). Map spreadsheet headers directly to $fillable attributes:

Example model:

Example CSV headers:

Validation rules match the column names exactly: name_en, not name.en.

Import Flow

1. The admin opens the Smart Import modal and optionally downloads a sample template.
2. A CSV or XLSX file is uploaded and parsed into staging rows.
3. The admin reviews, searches, filters, and edits invalid cells in the staging table.
4. On confirmation, valid rows are queued for background import.
5. Progress is shown on the action button until the batch completes.
6. A Filament notification is sent when the import finishes or fails.

Action Configuration

SmartImportAction exposes a fluent API:

All methods accept closures for dynamic configuration.

Relationship Lookups

Map foreign key columns to human-readable lookup values in the spreadsheet:

In the spreadsheet, use the column category with values such as news or tutorials. The plugin resolves the value to category_id before persistence.

Multiple lookup columns are supported:

Update Existing Records (Upsert)

When you need to update existing database records instead of always inserting new ones, configure a unique identifier with uniqueBy(). This enables upsert matching during import.

The upload step shows a toggle "Update existing records if match found" when uniqueBy() is configured. The admin chooses per import whether matching rows should update existing records or be treated as duplicates.

Multiple match columns are supported:

For Spatie Translatable models, match by a regular model attribute such as id:

Include the id column in the spreadsheet when updating existing articles by primary key. Sample templates exclude id by default, so add it manually to the CSV or XLSX when using uniqueBy('id').

Toggle behavior

When update mode is enabled:

• unique validation rules on the configured match columns are skipped during staging.
• Existing records are located using the configured uniqueBy columns.
• Spatie translatable fields are merged on update (existing locale values are preserved when not provided in the spreadsheet).

Staging row badges

During review, each staged row displays one of these status badges:

Batch options

The selected toggle value and unique columns are stored in the import batch options:

These options are read by the staging processor, validator, and background import job.

Spreadsheet Format

Standard Columns

Column headers should match importable model attributes from $fillable. These columns are excluded automatically from templates and processing:

• id
• created_at
• updated_at
• deleted_at

Translatable Columns (Spatie Translatable)

When translatable() is configured, each logical field is expanded into one column per locale:

If the model uses Spatie Translatable and no fields are configured manually, the model's $translatable array is detected automatically.

Validation rules use dot notation for locales:

Flat Locale Columns (Without Spatie Translatable)

When each locale is a dedicated database column, define them in $fillable and use the same names as spreadsheet headers. No translatable() configuration is required.

Validation rules reference the flat column names:

Sample templates include all $fillable columns as-is without locale expansion.

Supported File Types

• CSV
• XLSX

Maximum upload size is controlled by max_upload_size_kb in the config file.

Sample Templates

When sampleTemplate() is enabled, the upload step provides download links for:

• .xlsx sample template
• .csv sample template

Templates are generated from the configured model structure, including translatable and relationship columns, with one example row per column.

Configuration

Publish the config file:

Available options:

With Laravel's default local disk, uploaded files are stored under:

Admin Panel

The plugin registers an Import Batches resource in the Filament navigation under the Smart Import group.

From this page you can:

• Review all import batches and their status
• Inspect staging rows for a specific batch
• Browse uploaded files stored on disk
• Download or delete individual upload files
• Bulk delete selected upload files
• Delete all stored upload files

Developer Commands

Purge import data

For local development and testing, reset all import batch records:

Options:

Examples:

This command truncates import_staging_rows and import_batches. It is intended for development environments.

Publishing

Architecture Overview

Batch Statuses

Troubleshooting

Import button stays on "Importing"

Ensure a queue worker is running and the configured queue connection is correct.

Validation errors after upload

Check column headers against the sample template.

• Spatie Translatable models: use expanded columns such as title_en, and validation rules with dot notation (title.en).
• Flat column models: use the exact database column names such as name_en, and validation rules without dots (name_en).

Relationship values not resolved

Confirm the lookup column exists in the spreadsheet and the related record already exists in the database.

Upload fails due to file size

Increase FILAMENT_SMART_IMPORT_MAX_UPLOAD_SIZE_KB and verify PHP upload limits (upload_max_filesize, post_max_size).

Update existing toggle is not visible

The toggle appears only when uniqueBy() is configured on the action. Without a unique identifier, the plugin cannot determine which column(s) to match against existing records.

Duplicate errors during import

If update mode is disabled, rows that match an existing record by the configured uniqueBy column(s) are flagged as duplicate errors. Enable the toggle or remove conflicting rows from the spreadsheet.

License

Copyright (c) 2026 Martin Khachatryan. All rights reserved.

This is proprietary commercial software. See LICENSE.md for the full license agreement.

Unauthorized copying, redistribution, or use without a valid license is prohibited.