Excel & CSV Import for Filament

https://github.com/romansulzhyk/filament-import
Admin
Excel & CSV Import for Filament enables importing CSV, TSV, and Excel (.xlsx) files directly into...
Tokens:8,258
Snippets:69
Trust Score:2.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install filament-import with Composer

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Installs the package via Composer. The package registers itself automatically.

```bash
composer require romansulzhyk/filament-import
```

--------------------------------

### Run tests with Composer and Pest

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Install dependencies and run the test suite. The third command runs only the performance tests. CI runs the suite on PHP 8.2 to 8.5 against Filament 4 and 5 and Laravel 11, 12 and 13, with both newest and lowest Composer-installable versions.

```bash
composer install
vendor/bin/pest
vendor/bin/pest tests/Performance --group=performance
```

--------------------------------

### Publish Filament Import config

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Publishes the configuration file to config/filament-import.php. Use this command to customize the package settings.

```bash
php artisan vendor:publish --tag=filament-import-config
```

--------------------------------

### Configure ExcelImportAction with hooks and options

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Shows the full set of hooks and options available on ExcelImportAction. Use beforeImport and afterImport to run logic before/after rows are written; $excelImportAction->halt() stops the import. afterImport receives an ImportResult with created, updated, skipped, failed(), and failures. importerOptions passes options to the importer via $this->options. optionsFormComponents adds form fields, additionalData adds fixed data, templateDownload disables the template link, syncRowLimit sets a row limit, csvEncoding overrides encoding detection, acceptedFileTypes adds extra MIME types, and maxFileSize sets the maximum file size in kilobytes.

```php
ExcelImportAction::make()
    ->beforeImport(function (array $data, $livewire, $excelImportAction) {
        // before any row is written; $excelImportAction->halt() stops
    })
    ->afterImport(function (array $data, $livewire, $excelImportAction, ImportResult $result) {
        // $result->created, $result->updated, $result->skipped, $result->failed(), $result->failures
    })
    ->importerOptions(['send_welcome_email' => false]) // $this->options in an importer
    ->optionsFormComponents([Select::make('source')->options([...])->required()])
    ->additionalData(fn (array $data) => ['source' => $data['source']]) // fixed values, zero-config
    ->templateDownload(false)
    ->syncRowLimit(5000)
    ->csvEncoding('Windows-1250') // only if detection is not enough
    ->acceptedFileTypes([...ExcelImportAction::ACCEPTED_FILE_TYPES, 'application/octet-stream']) // extra MIME types for CSV
    ->maxFileSize(20480); // kilobytes
```

--------------------------------

### Zero Configuration ExcelImportAction with importColumns, exceptColumns, validateUsing, upsertBy

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Use this snippet to set up an import action on a resource list page with zero configuration. Every $fillable attribute that is not $hidden becomes an import field. The importColumns() method is an optional allow-list, exceptColumns() is an optional deny-list, validateUsing() applies validation rules, and upsertBy() updates matching records instead of creating duplicates. Note that anyone who can see the action can write every offered attribute, so narrow columns when sensitive and add ->authorize(...) or ->visible(...). A model with $guarded = [] and no $fillable is refused in zero-config mode; use ->importColumns([...]) with $fillable or an importer class. Zero-config mode refuses relation managers, relation pages, and models other than the resource's own on tenant-scoped resources; use an importer class and assign the tenant in beforeSave().

```php
use RomanSulzhyk\FilamentImport\Actions\ExcelImportAction;

protected function getHeaderActions(): array
{
    return [
        ExcelImportAction::make()
            ->importColumns(['name', 'email', 'phone']) // optional allow-list, only fillable ones
            ->exceptColumns(['role', 'is_admin'])       // optional deny-list
            ->validateUsing([
                'name' => 'required|max:255',
                'email' => ['required', 'email'],
            ])
            ->upsertBy('email'), // update the matching record instead of creating a duplicate
    ];
}
```

--------------------------------

### Assign tenant with an importer class

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Assigns the tenant manually when importing outside the resource's own pages. The importer's beforeSave() associates the tenant, and the action uses that importer class.

```php
class ContactImporter extends Importer
{
    // ...columns...

    protected function beforeSave(): void
    {
        $this->record->team()->associate(Filament::getTenant());
    }
}

ExcelImportAction::make()->importer(ContactImporter::class);
```

--------------------------------

### Pest test for importing customers

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Tests the import action by mounting 'excelImport', filling the file field with a fake CSV, and asserting no form errors and a notification. The suggested mapping is in columnMap and can be overridden with fillForm(['columnMap' => [...]]) before callMountedAction(). Fields with required rules and every upsertBy() key must be mapped.

```php
use Illuminate\Http\UploadedFile;
use function Pest\Livewire\livewire;

it('imports customers from a file', function () {
    $file = UploadedFile::fake()->createWithContent('customers.csv', "name,email\nAda,ada@example.com\n");

    livewire(ListCustomers::class)
        ->mountAction('excelImport')
        ->fillForm(['file' => $file])
        ->callMountedAction()
        ->assertHasNoFormErrors()
        ->assertNotified();

    expect(Customer::where('email', 'ada@example.com')->exists())->toBeTrue();
});
```

--------------------------------

### Import ExcelImportAction from romansulzhyk/filament-import

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Use this import statement to access the ExcelImportAction class. The default action name is 'excelImport', so it can sit next to the core 'import' action.

```php
use RomanSulzhyk\FilamentImport\Actions\ExcelImportAction;
```

--------------------------------

### Schedule filament-import:prune command

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Schedule this command when imports are rare or the disk cannot list files. It prunes failed import rows.

```bash
php artisan filament-import:prune
```

--------------------------------

### ExcelImportAction with Existing Filament Importer Class

Source: https://github.com/romansulzhyk/filament-import/blob/main/resources/boost/skills/filament-import/SKILL.md

Use this snippet to run an import action using an existing Filament Importer class. The importer's columns, rules, casting, ImportColumn::relationship(), resolveRecord(), lifecycle hooks, and getOptionsFormComponents() run as in the core ImportAction, but in-process. The Import model the importer receives is not saved: it has no id, no import history entry, and no ImportStarted/ImportCompleted events. Keep importers that need a saved Import record on the core ImportAction. Note that validateUsing(), upsertBy(), importColumns(), and exceptColumns() are zero-config only; combining them with ->importer() throws.

```php
ExcelImportAction::make()
    ->importer(CustomerImporter::class);
```

--------------------------------

### Publish translations with vendor:publish

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Publish the translation files to change wording or add a language. The interface is translated into 63 locales, following Filament's locale names such as pt_BR, zh_CN, and sr_Latn.

```bash
php artisan vendor:publish --tag=filament-import-translations
```

--------------------------------

### Restrict import columns with importColumns and exceptColumns

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Restricts the importable columns. Only the listed columns are offered, and only if they are fillable; the excepted columns are never offered.

```php
ExcelImportAction::make()
    ->importColumns(['name', 'email', 'phone'])   // only these, and only if fillable
    ->exceptColumns(['role', 'is_admin']);         // never these
```

--------------------------------

### Add ExcelImportAction to a list page

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Adds the ExcelImportAction to a resource's list page with zero configuration. Every $fillable attribute that is not $hidden becomes an import field.

```php
use RomanSulzhyk\FilamentImport\Actions\ExcelImportAction;

class ListCustomers extends ListRecords
{
    protected function getHeaderActions(): array
    {
        return [
            ExcelImportAction::make(),
        ];
    }
}
```

--------------------------------

### Validate and upsert with validateUsing and upsertBy

Source: https://github.com/romansulzhyk/filament-import/blob/main/README.md

Adds validation rules and updates existing records instead of duplicating them. upsertBy() updates the record whose values in those columns match the row, and creates one otherwise. A row with a blank key is always created, never matched.

```php
ExcelImportAction::make()
    ->validateUsing([
        'name' => 'required|max:255',
        'email' => ['required', 'email'],
    ])
    ->upsertBy('email');
```
Tokens:
Raw