actions Documentation

If you want to add this action to the header of a table, you may do so like this:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->headerActions([
            ImportAction::make()
                ->importer(ProductImporter::class)
        ]);
}

The "importer" class needs to be created to tell Filament how to import each row of the CSV.

If you have more than one ImportAction in the same place, you should give each a unique name in the make() method:

use Filament\Actions\ImportAction;

ImportAction::make('importProducts')
    ->importer(ProductImporter::class)

ImportAction::make('importBrands')
    ->importer(BrandImporter::class)

Creating an importer Copy Chapter

To create an importer class for a model, you may use the make:filament-importer command, passing the name of a model:

php artisan make:filament-importer Product

This will create a new class in the app/Filament/Imports directory. You now need to define the columns that can be imported.

Automatically generating importer columns Copy Section

If you'd like to save time, Filament can automatically generate the columns for you, based on your model's database columns, using --generate:

php artisan make:filament-importer Product --generate

Defining importer columns Copy Chapter

To define the columns that can be imported, you need to override the getColumns() method on your importer class, returning an array of ImportColumn objects:

use Filament\Actions\Imports\ImportColumn;

public static function getColumns(): array
{
    return [
        ImportColumn::make('name')
            ->requiredMapping()
            ->rules(['required', 'max:255']),
        ImportColumn::make('sku')
            ->label('SKU')
            ->requiredMapping()
            ->rules(['required', 'max:32']),
        ImportColumn::make('price')
            ->numeric()
            ->rules(['numeric', 'min:0']),
    ];
}

Customizing the label of an import column Copy Section

The label for each column will be generated automatically from its name, but you can override it by calling the label() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->label('SKU')

Requiring an importer column to be mapped to a CSV column Copy Section

You can call the requiredMapping() method to make a column required to be mapped to a column in the CSV. Columns that are required in the database should be required to be mapped:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->requiredMapping()

If you require a column in the database, you also need to make sure that it has a rules(['required']) validation rule.

If a column is not mapped, it will not be validated since there is no data to validate.

If you allow an import to create records as well as update existing ones, but only require a column to be mapped when creating records as it's a required field, you can use the requiredMappingForNewRecordsOnly() method instead of requiredMapping():

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->requiredMappingForNewRecordsOnly()

If the resolveRecord() method returns a model instance that is not saved in the database yet, the column will be required to be mapped, just for that row. If the user does not map the column, and one of the rows in the import does not yet exist in the database, just that row will fail and a message will be added to the failed rows CSV after every row has been analyzed.

Validating CSV data Copy Section

You can call the rules() method to add validation rules to a column. These rules will check the data in each row from the CSV before it is saved to the database:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->rules(['required', 'max:32'])

Any rows that do not pass validation will not be imported. Instead, they will be compiled into a new CSV of "failed rows", which the user can download after the import has finished. The user will be shown a list of validation errors for each row that failed.

As well as allowing a static value, the rules() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Validating a column against an enum

If a column maps onto a backed enum, you can pass the enum class to the enum() method. Any row whose value is not a case of the enum will fail validation, instead of reaching the model's cast and throwing a ValueError:

use App\Enums\Status;
use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('status')
    ->enum(Status::class)

Empty cells are not validated against the enum, so users may leave an optional column blank. If you want to reject empty cells, add a required rule to the column.

The backing values of the enum are also used as the example CSV data for the column, so the user can see which values are accepted without you listing them by hand. Passing examples() yourself overrides this, and passing an empty array prevents example rows from being generated for that column.

As well as allowing a static value, the enum() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

When the enum is calculated dynamically, its cases are not automatically used as example CSV data, since the function may depend on the current row being imported. You can pass the example data to examples() yourself if required.

Casting state Copy Section

Before validation, data from the CSV can be cast. This is useful for converting strings into the correct data type, otherwise validation may fail. For example, if you have a price column in your CSV, you may want to cast it to a float:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('price')
    ->castStateUsing(function (string $state): ?float {
        if (blank($state)) {
            return null;
        }
        
        $state = preg_replace('/[^0-9.]/', '', $state);
        $state = floatval($state);
    
        return round($state, precision: 2);
    })

As well as $state, the castStateUsing() method allows you to inject various utilities into the function as parameters.

In this example, we pass in a function that is used to cast the $state. This function removes any non-numeric characters from the string, casts it to a float, and rounds it to two decimal places.

Filament also ships with some built-in casting methods:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('price')
    ->numeric() // Casts the state to a float.

ImportColumn::make('price')
    ->numeric(decimalPlaces: 2) // Casts the state to a float, and rounds it to 2 decimal places.

ImportColumn::make('quantity')
    ->integer() // Casts the state to an integer.

ImportColumn::make('is_visible')
    ->boolean() // Casts the state to a boolean.

Mutating the state after it has been cast

If you're using a built-in casting method or array cast, you can mutate the state after it has been cast by passing a function to the castStateUsing() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('price')
    ->numeric()
    ->castStateUsing(function (float $state): ?float {
        if (blank($state)) {
            return null;
        }
    
        return round($state * 100);
    })

You can even access the original state before it was cast, by defining an $originalState argument in the function:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('price')
    ->numeric()
    ->castStateUsing(function (float $state, mixed $originalState): ?float {
        // ...
    })

As well as $state, the castStateUsing() method allows you to inject various utilities into the function as parameters.

Handling multiple values in a single column Copy Section

You may use the multiple() method to cast the values in a column to an array. It accepts a delimiter as its first argument, which is used to split the values in the column into an array. For example, if you have a documentation_urls column in your CSV, you may want to cast it to an array of URLs:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('documentation_urls')
    ->multiple(',')

As well as allowing a static value, the multiple() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

In this example, we pass in a comma as the delimiter, so the values in the column will be split by commas, and cast to an array.

Casting each item in an array

If you want to cast each item in the array to a different data type, you can chain the built-in casting methods:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('customer_ratings')
    ->multiple(',')
    ->integer() // Casts each item in the array to an integer.

Validating each item in an array

If you want to validate each item in the array, you can chain the nestedRecursiveRules() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('customer_ratings')
    ->multiple(',')
    ->integer()
    ->rules(['array'])
    ->nestedRecursiveRules(['integer', 'min:1', 'max:5'])

As well as allowing a static value, the nestedRecursiveRules() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Importing relationships Copy Section

You may use the relationship() method to import a relationship. At the moment, BelongsTo and BelongsToMany relationships are supported. For example, if you have a category column in your CSV, you may want to import the category BelongsTo relationship:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('author')
    ->relationship()

In this example, the author column in the CSV will be mapped to the author_id column in the database. The CSV should contain the primary keys of authors, usually id.

If the column has a value, but the author cannot be found, the import will fail validation. Filament automatically adds validation to all relationship columns, to ensure that the relationship is not empty when it is required.

If you want to import a BelongsToMany relationship, make sure that the column is set to multiple(), with the correct separator between values:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('authors')
    ->relationship()
    ->multiple(',')

You may repeat a value in the same cell. When looking up records by primary key or the column names passed to resolveUsing, missing related values cause the row to fail validation.

Customizing the relationship import resolution

If you want to find a related record using a different column, you can pass the column name as resolveUsing:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('author')
    ->relationship(resolveUsing: 'email')

You can pass in multiple columns to resolveUsing, and they will be used to find the author, in an "or" fashion. For example, if you pass in ['email', 'username'], the record can be found by either their email or username:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('author')
    ->relationship(resolveUsing: ['email', 'username'])

You can also customize the resolution process, by passing in a function to resolveUsing, which should return a record to associate with the relationship:

use App\Models\Author;
use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('author')
    ->relationship(resolveUsing: function (string $state): ?Author {
        return Author::query()
            ->where('email', $state)
            ->orWhere('username', $state)
            ->first();
    })

The function passed to resolveUsing allows you to inject various utilities into the function as parameters.

If you are using a BelongsToMany relationship, the $state will be an array, and you should return a collection of records that you have resolved:

use App\Models\Author;
use Filament\Actions\Imports\ImportColumn;
use Illuminate\Database\Eloquent\Collection;

ImportColumn::make('authors')
    ->relationship(resolveUsing: function (array $state): Collection {
        return Author::query()
            ->whereIn('email', $state)
            ->orWhereIn('username', $state)
            ->get();
    })

When returning a collection, you should validate that your function resolves every requested value, since Filament cannot determine which input value each returned record represents.

You could even use this function to dynamically determine which columns to use to resolve the record:

use App\Models\Author;
use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('author')
    ->relationship(resolveUsing: function (string $state): ?Author {
        if (filter_var($state, FILTER_VALIDATE_EMAIL)) {
            return 'email';
        }
    
        return 'username';
    })

Marking column data as sensitive Copy Section

When import rows fail validation, they are logged to the database, ready for export when the import completes. You may want to exclude certain columns from this logging to avoid storing sensitive data in plain text. To achieve this, you can use the sensitive() method on the ImportColumn to prevent its data from being logged:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('ssn')
    ->label('Social security number')
    ->sensitive()
    ->rules(['required', 'digits:9'])

Customizing how a column is filled into a record Copy Section

If you want to customize how column state is filled into a record, you can pass a function to the fillRecordUsing() method:

use App\Models\Product;
use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->fillRecordUsing(function (Product $record, string $state): void {
        $record->sku = strtoupper($state);
    })

The function passed to the fillRecordUsing() method allows you to inject various utilities into the function as parameters.

Adding helper text below the import column Copy Section

Sometimes, you may wish to provide extra information for the user before validation. You can do this by adding helperText() to a column, which gets displayed below the mapping select:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('skus')
    ->multiple(',')
    ->helperText('A comma-separated list of SKUs.')

Updating existing records when importing Copy Chapter

When generating an importer class, you will see this resolveRecord() method:

use App\Models\Product;

public function resolveRecord(): ?Product
{
    // return Product::firstOrNew([
    //     // Update existing records, matching them by `$this->data['column_name']`
    //     'email' => $this->data['email'],
    // ]);

    return new Product();
}

This method is called for each row in the CSV, and is responsible for returning a model instance that will be filled with the data from the CSV, and saved to the database. By default, it will create a new record for each row. However, you can customize this behavior to update existing records instead. For example, you might want to update a product if it already exists, and create a new one if it doesn't. To do this, you can uncomment the firstOrNew() line, and pass the column name that you want to match on. For a product, we might want to match on the sku column:

use App\Models\Product;

public function resolveRecord(): ?Product
{
    return Product::firstOrNew([
        'sku' => $this->data['sku'],
    ]);
}

Updating existing records when importing only Copy Section

If you want to write an importer that only updates existing records, and does not create new ones, you can return null if no record is found:

use App\Models\Product;

public function resolveRecord(): ?Product
{
    return Product::query()
        ->where('sku', $this->data['sku'])
        ->first();
}

If you'd like to fail the import row if no record is found, you can throw a RowImportFailedException with a message:

use App\Models\Product;
use Filament\Actions\Imports\Exceptions\RowImportFailedException;

public function resolveRecord(): ?Product
{
    $product = Product::query()
        ->where('sku', $this->data['sku'])
        ->first();

    if (! $product) {
        throw new RowImportFailedException("No product found with SKU [{$this->data['sku']}].");
    }

    return $product;
}

When the import is completed, the user will be able to download a CSV of failed rows, which will contain the error messages.

Ignoring blank state for an import column Copy Section

By default, if a column in the CSV is blank, and mapped by the user, and it's not required by validation, the column will be imported as null in the database. If you'd like to ignore blank state, and use the existing value in the database instead, you can call the ignoreBlankState() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('price')
    ->ignoreBlankState()

Using import options Copy Chapter

The import action can render extra form components that the user can interact with when importing a CSV. This can be useful to allow the user to customize the behavior of the importer. For instance, you might want a user to be able to choose whether to update existing records when importing, or only create new ones. To do this, you can return options form components from the getOptionsFormComponents() method on your importer class:

use Filament\Forms\Components\Checkbox;

public static function getOptionsFormComponents(): array
{
    return [
        Checkbox::make('updateExisting')
            ->label('Update existing records'),
    ];
}

Alternatively, you can pass a set of static options to the importer through the options() method on the action:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->options([
        'updateExisting' => true,
    ])

Now, you can access the data from these options inside the importer class, by calling $this->options. For example, you might want to use it inside resolveRecord() to update an existing product:

use App\Models\Product;

public function resolveRecord(): ?Product
{
    if ($this->options['updateExisting'] ?? false) {
        return Product::firstOrNew([
            'sku' => $this->data['sku'],
        ]);
    }

    return new Product();
}

Improving import column mapping guesses Copy Chapter

By default, Filament will attempt to "guess" which columns in the CSV match which columns in the database, to save the user time. It does this by attempting to find different combinations of the column name, with spaces, -, _, all cases insensitively. However, if you'd like to improve the guesses, you can call the guess() method with more examples of the column name that could be present in the CSV:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->guess(['id', 'number', 'stock-keeping unit'])

Providing example CSV data Copy Chapter

Before the user uploads a CSV, they have an option to download an example CSV file, containing all the available columns that can be imported. This is useful, as it allows the user to import this file directly into their spreadsheet software, and fill it out.

You can also add an example row to the CSV, to show the user what the data should look like. To fill in this example row, you can pass in an example column value to the example() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->example('ABC123')

Or if you want to add more than one example row, you can pass an array to the examples() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->examples(['ABC123', 'DEF456'])

By default, the name of the column is used in the header of the example CSV. You can customize the header per-column using exampleHeader():

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('sku')
    ->exampleHeader('SKU')

Using a custom user model Copy Chapter

By default, the imports table has a user_id column. That column is constrained to the users table:

$table->foreignId('user_id')->constrained()->cascadeOnDelete();

In the Import model, the user() relationship is defined as a BelongsTo relationship to the App\Models\User model. If the App\Models\User model does not exist, or you want to use a different one, you can bind a new Authenticatable model to the container in a service provider's register() method:

use App\Models\Admin;
use Illuminate\Contracts\Auth\Authenticatable;

$this->app->bind(Authenticatable::class, Admin::class);

If your authenticatable model uses a different table to users, you should pass that table name to constrained():

$table->foreignId('user_id')->constrained('admins')->cascadeOnDelete();

Using a polymorphic user relationship Copy Section

If you want to associate imports with multiple user models, you can use a polymorphic MorphTo relationship instead. To do this, you need to replace the user_id column in the imports table:

$table->morphs('user');

Then, in a service provider's boot() method, you should call Import::polymorphicUserRelationship() to swap the user() relationship on the Import model to a MorphTo relationship:

use Filament\Actions\Imports\Models\Import;

Import::polymorphicUserRelationship();

Limiting the maximum number of rows that can be imported Copy Chapter

To prevent server overload, you may wish to limit the maximum number of rows that can be imported from one CSV file. You can do this by calling the maxRows() method on the action:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->maxRows(100000)

As well as allowing a static value, the maxRows() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Changing the import chunk size Copy Chapter

Filament will chunk the CSV, and process each chunk in a different queued job. By default, chunks are 100 rows at a time. You can change this by calling the chunkSize() method on the action:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->chunkSize(250)

As well as allowing a static value, the chunkSize() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Changing the CSV delimiter Copy Chapter

The default delimiter for CSVs is the comma (,). If your import uses a different delimiter, you may call the csvDelimiter() method on the action, passing a new one:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->csvDelimiter(';')

As well as allowing a static value, the csvDelimiter() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

You can only specify a single character, otherwise an exception will be thrown.

Changing the column header offset Copy Chapter

If your column headers are not on the first row of the CSV, you can call the headerOffset() method on the action, passing the number of rows to skip:

use App\Filament\Imports\ProductImporter;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->headerOffset(5)

As well as allowing a static value, the headerOffset() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Customizing the completion notification Copy Chapter

When an import finishes, Filament sends a notification to the user who started it. You can customize the title and body of that notification by overriding getCompletedNotificationTitle() and getCompletedNotificationBody() on your importer:

use Filament\Actions\Imports\Models\Import;

public static function getCompletedNotificationTitle(Import $import): string
{
    return 'Your product import has finished';
}

public static function getCompletedNotificationBody(Import $import): string
{
    return $import->successful_rows . ' products were imported.';
}

For anything beyond the title and body — for example, changing the notification color, adding extra actions, or replacing the icon — override modifyCompletedNotification(). You can either mutate the Notification passed in and return it, or build and return a completely new one:

use Filament\Actions\Action;
use Filament\Actions\Imports\Models\Import;
use Filament\Notifications\Notification;

public static function modifyCompletedNotification(Notification $notification, Import $import): Notification
{
    $notification->icon('heroicon-o-shopping-bag');

    if ($import->getOptions()['sendWelcomeEmails'] ?? false) {
        $notification->actions([
            ...$notification->getActions(),
            Action::make('viewWelcomeEmails')
                ->url(route('emails.sent')),
        ]);
    }

    return $notification;
}

The Import model exposes the column mapping and options the user selected via $import->getColumnMap() and $import->getOptions(), so you can tailor the notification based on what the user imported.

Customizing how failed rows are downloaded Copy Chapter

By default, failed rows are compiled into a CSV and returned as a streamed response. You may customize how they are downloaded for an importer by overriding the getFailedRowsDownloader() method:

use App\Filament\Imports\Downloaders\CustomFailedRowsDownloader;
use Filament\Actions\Imports\Downloaders\Contracts\Downloader;

public static function getFailedRowsDownloader(): Downloader
{
    return app(CustomFailedRowsDownloader::class);
}

A downloader is an invokable class that accepts the Import model and returns a Symfony Response. This response may stream a download, return a file, or redirect the user to a temporary URL on a remote filesystem.

If your custom downloader only changes how the generated content is delivered, you may use CsvImportFailureContentGenerator to write the failed rows to a League CSV Writer. Filament resolves this class from the container so that you can reuse the built-in content generation without duplicating it.

Customizing the import job Copy Chapter

The default job for processing imports is Filament\Actions\Imports\Jobs\ImportCsv. If you want to extend this class and override any of its methods, you may replace the original class in the register() method of a service provider:

use App\Jobs\ImportCsv;
use Filament\Actions\Imports\Jobs\ImportCsv as BaseImportCsv;

$this->app->bind(BaseImportCsv::class, ImportCsv::class);

Or, you can pass the new job class to the job() method on the action, to customize the job for a specific import:

use App\Filament\Imports\ProductImporter;
use App\Jobs\ImportCsv;
use Filament\Actions\ImportAction;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->job(ImportCsv::class)

Customizing the import queue and connection Copy Section

By default, the import system will use the default queue and connection. If you'd like to customize the queue used for jobs of a certain importer, you may override the getJobQueue() method in your importer class:

public function getJobQueue(): ?string
{
    return 'imports';
}

You can also customize the connection used for jobs of a certain importer, by overriding the getJobConnection() method in your importer class:

public function getJobConnection(): ?string
{
    return 'sqs';
}

Customizing the import job middleware Copy Section

By default, the import system will only process one job at a time from each import. This is to prevent the server from being overloaded, and other jobs from being delayed by large imports. That functionality is defined in the WithoutOverlapping middleware on the importer class:

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function getJobMiddleware(): array
{
    return [
        (new WithoutOverlapping("filament:imports:{$this->import->getKey()}"))->expireAfter(600),
    ];
}

If you'd like to customize the middleware that is applied to jobs of a certain importer, you may override this method in your importer class. You can read more about job middleware in the Laravel docs.

Customizing the import job retries Copy Section

By default, the import system will retry a job for 24 hours, or until it fails 5 times with unhandled exceptions, whichever happens first. This is to allow for temporary issues, such as the database being unavailable, to be resolved. You may change the time period for the job to retry, which is defined in the getJobRetryUntil() method on the importer class:

use Carbon\CarbonInterface;

public function getJobRetryUntil(): ?CarbonInterface
{
    return now()->addHours(12);
}

You can read more about job retries in the Laravel docs.

Customizing the import job backoff strategy

By default, the import system will wait 1 minute, then 2 minutes, then 5 minutes, then 10 minutes thereafter, before retrying a job. This is to prevent the server from being overloaded by a job that is failing repeatedly. That functionality is defined in the getJobBackoff() method on the importer class:

/**
* @return int | array<int> | null
 */
public function getJobBackoff(): int | array | null
{
    return [60, 120, 300, 600];
}

You can read more about job backoff, including how to configure exponential backoffs, in the Laravel docs.

Customizing the import job tags Copy Section

By default, the import system will tag each job with the ID of the import. This is to allow you to easily find all jobs related to a certain import. That functionality is defined in the getJobTags() method on the importer class:

public function getJobTags(): array
{
    return ["import{$this->import->getKey()}"];
}

If you'd like to customize the tags that are applied to jobs of a certain importer, you may override this method in your importer class.

Customizing the import job batch name Copy Section

By default, the import system doesn't define any name for the job batches. If you'd like to customize the name that is applied to job batches of a certain importer, you may override the getJobBatchName() method in your importer class:

public function getJobBatchName(): ?string
{
    return 'product-import';
}

Customizing import validation messages Copy Chapter

The import system will automatically validate the CSV file before it is imported. If there are any errors, the user will be shown a list of them, and the import will not be processed. If you'd like to override any default validation messages, you may do so by overriding the getValidationMessages() method on your importer class:

public function getValidationMessages(): array
{
    return [
        'name.required' => 'The name column must not be empty.',
    ];
}

To learn more about customizing validation messages, read the Laravel docs.

Customizing import validation attributes Copy Section

When columns fail validation, their label is used in the error message. To customize the label used in field error messages, use the validationAttribute() method:

use Filament\Actions\Imports\ImportColumn;

ImportColumn::make('name')
    ->validationAttribute('full name')

Customizing import file validation Copy Chapter

You can add new Laravel validation rules for the import file using the fileRules() method:

use Filament\Actions\ImportAction;
use Illuminate\Validation\Rules\File;

ImportAction::make()
    ->importer(ProductImporter::class)
    ->fileRules([
        'max:1024',
        // or
        File::types(['csv', 'txt'])->max(1024),
    ]),

As well as allowing a static value, the fileRules() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Lifecycle hooks Copy Chapter

Hooks may be used to execute code at various points within an importer's lifecycle, like before a record is saved. To set up a hook, create a protected method on the importer class with the name of the hook:

protected function beforeSave(): void
{
    // ...
}

In this example, the code in the beforeSave() method will be called before the validated data from the CSV is saved to the database.

There are several available hooks for importers:

use Filament\Actions\Imports\Importer;

class ProductImporter extends Importer
{
    // ...

    protected function beforeValidate(): void
    {
        // Runs before the CSV data for a row is validated.
    }

    protected function afterValidate(): void
    {
        // Runs after the CSV data for a row is validated.
    }

    protected function beforeFill(): void
    {
        // Runs before the validated CSV data for a row is filled into a model instance.
    }

    protected function afterFill(): void
    {
        // Runs after the validated CSV data for a row is filled into a model instance.
    }

    protected function beforeSave(): void
    {
        // Runs before a record is saved to the database.
    }

    protected function beforeCreate(): void
    {
        // Similar to `beforeSave()`, but only runs when creating a new record.
    }

    protected function beforeUpdate(): void
    {
        // Similar to `beforeSave()`, but only runs when updating an existing record.
    }

    protected function afterSave(): void
    {
        // Runs after a record is saved to the database.
    }
    
    protected function afterCreate(): void
    {
        // Similar to `afterSave()`, but only runs when creating a new record.
    }
    
    protected function afterUpdate(): void
    {
        // Similar to `afterSave()`, but only runs when updating an existing record.
    }
}

Defining lifecycle hooks in traits Copy Section

To define a lifecycle hook in a trait, suffix the hook name with the trait's name. This follows the boot{TraitName}() convention used by Eloquent and the mount{TraitName}() convention used by Livewire, allowing reusable traits to hook into an importer's lifecycle without colliding with hooks defined on the importer itself:

use Filament\Actions\Imports\Importer;

trait LogsImports
{
    protected function afterSaveLogsImports(): void
    {
        // Runs after a record is saved to the database, in addition to the
        // hook on the importer.
    }
}

class ProductImporter extends Importer
{
    use LogsImports;

    protected function afterSave(): void
    {
        // Both lifecycle hooks are called.
    }
}

The importer's own hook is called first, followed by each trait hook. Hooks from traits used by other traits are also called. Trait hooks are called automatically, so you should not also call them from the importer's own hook.

Inside these hooks, you can access the current row's data using $this->data. You can also access the original row of data from the CSV, before it was cast or mapped, using $this->originalData.

The current record (if it exists yet) is accessible in $this->record, and the import form options using $this->options.

Testing Copy Chapter

To test importer rows and import action submissions, see the Testing imports guide.

Authorization Copy Chapter

By default, only the user who started the import may access the failure CSV file that gets generated if part of an import fails. If you'd like to customize the authorization logic, you may create an ImportPolicy class, and register it in your AuthServiceProvider:

use App\Policies\ImportPolicy;
use Filament\Actions\Imports\Models\Import;

protected $policies = [
    Import::class => ImportPolicy::class,
];

The view() method of the policy will be used to authorize access to the failure CSV file.

Please note that if you define a policy, the existing logic of ensuring only the user who started the import can access the failure CSV file will be removed. You will need to add that logic to your policy if you want to keep it:

use App\Models\User;
use Filament\Actions\Imports\Models\Import;

public function view(User $user, Import $import): bool
{
    return $import->user()->is($user);
}

Security Copy Chapter

Per-record authorization Copy Section

The import system does not perform per-record authorization checks when creating or updating records. Each row from the CSV is processed by the importer's resolveRecord(), fillRecord(), and saveRecord() methods without consulting your application's Laravel policies. This means that if a user is allowed to trigger an import, they can create or update any record that the importer supports, regardless of whether they would normally be authorized to do so through your application's UI.

If you need per-record authorization during import, you should add checks in your importer's lifecycle hooks, such as beforeCreate() or beforeUpdate(), to authorize the current user against the record.

Importing tenant-aware records Copy Section

When you start an import using ImportAction in a tenant-aware panel with a current tenant, Filament restores that panel and tenant for each import chunk. This applies the resources' tenant global scopes and new-record association. Each chunk checks that the tenant still exists and the importing user can still access it.

This does not apply custom Resource::getEloquentQuery() restrictions or replace per-record authorization. Models without a tenant-scoped resource in the panel, queries that remove tenant scopes, and imports started outside this context need your own tenant constraints and associations.

The restored context covers row processing and importer lifecycle hooks, not custom job middleware or batch completion callbacks.

CSV formula injection Copy Section

When rows fail validation during import, Filament compiles them into a downloadable CSV for the user to review. This failure CSV contains the original data from the uploaded file exactly as it was submitted, without any transformation. If the uploaded CSV contains values beginning with characters like =, +, -, or @, they will appear unchanged in the failure CSV. When opened in spreadsheet software such as Microsoft Excel or Google Sheets, these values may be interpreted as formulas, which could pose a security risk if the original CSV was provided by an untrusted source. You should ensure that your users are aware of this risk when reviewing failure CSVs, or implement sanitization in your importer's lifecycle hooks to neutralize potentially dangerous values before they are stored as failed rows.

Alternatively, you may opt in to Filament's built-in protection for the failure CSV. When enabled, any cell that begins with a formula-triggering character (=, +, -, @, a tab, or a carriage return) is prefixed with a single quote (') so that spreadsheet software treats it as plain text. Because the failure CSV includes every column from the uploaded file — even columns that are not mapped to an ImportColumn — this protection is applied to the whole file rather than to individual columns.

To enable it for a single importer, set the $shouldPreventFormulaInjection property on your importer class:

use Filament\Actions\Imports\Importer;

class ProductImporter extends Importer
{
    protected static bool $shouldPreventFormulaInjection = true;
}

To enable it for every importer across your application, call the preventFormulaInjection() method inside the boot() method of a service provider:

use Filament\Actions\Imports\Importer;

Importer::preventFormulaInjection();

12 Export (`docs/12-export.md`) Copy Section

title: Export action Copy Chapter

Introduction Copy Chapter

Filament includes an action that is able to export rows to a CSV or XLSX file. When the trigger button is clicked, a modal asks for the columns that they want to export, and what they should be labeled. This feature uses job batches and database notifications, so you need to publish those migrations from Laravel. Also, you need to publish the migrations for tables that Filament uses to store information about exports:

php artisan make:queue-batches-table
php artisan make:notifications-table
php artisan vendor:publish --tag=filament-actions-migrations
php artisan migrate

If you'd like to receive export notifications in a panel, you can enable them in the panel configuration.

You may use the ExportAction like so:

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->headerActions([
            ExportAction::make()
                ->exporter(ProductExporter::class),
        ]);
}

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportBulkAction;
use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->toolbarActions([
            ExportBulkAction::make()
                ->exporter(ProductExporter::class),
        ]);
}

php artisan make:filament-exporter Product

php artisan make:filament-exporter Product --generate

use Filament\Actions\Exports\ExportColumn;

public static function getColumns(): array
{
    return [
        ExportColumn::make('name'),
        ExportColumn::make('sku')
            ->label('SKU'),
        ExportColumn::make('price'),
    ];
}

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('sku')
    ->label('SKU')

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->enabledByDefault(false)

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->enableVisibleTableColumnsByDefault()

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('sku')
    ->hidden()

ExportColumn::make('sku')
    ->visible()

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('cost_price')
    ->hidden(fn (): bool => ! auth()->user()->isAdmin())

ExportColumn::make('cost_price')
    ->visible(fn (): bool => auth()->user()->isAdmin())

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->columnMappingColumns(3)

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->columnMapping(false)

use App\Models\Order;
use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('amount_including_vat')
    ->state(function (Order $record): float {
        return $record->amount * (1 + $record->vat_rate);
    })

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('status')
    ->formatStateUsing(fn (string $state): string => __("statuses.{$state}"))

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->limit(50)

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->words(10)

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('domain')
    ->prefix('https://')
    ->suffix('.com')

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('tags')
    ->listAsJson()

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('author.name')

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('users_count')
    ->counts('users')

use Filament\Actions\Exports\ExportColumn;
use Illuminate\Database\Eloquent\Builder;

ExportColumn::make('users_count')
    ->counts([
        'users' => fn (Builder $query) => $query->where('is_active', true),
    ])

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('users_exists')
    ->exists('users')

use Filament\Actions\Exports\ExportColumn;
use Illuminate\Database\Eloquent\Builder;

ExportColumn::make('users_exists')
    ->exists([
        'users' => fn (Builder $query) => $query->where('is_active', true),
    ])

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('users_avg_age')
    ->avg('users', 'age')

use Filament\Actions\Exports\ExportColumn;
use Illuminate\Database\Eloquent\Builder;

ExportColumn::make('users_avg_age')
    ->avg([
        'users' => fn (Builder $query) => $query->where('is_active', true),
    ], 'age')

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;
use Filament\Actions\Exports\Enums\ExportFormat;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->formats([
        ExportFormat::Csv,
    ])
    // or
    ->formats([
        ExportFormat::Xlsx,
    ])
    // or
    ->formats([
        ExportFormat::Xlsx,
        ExportFormat::Csv,
    ])

use Filament\Actions\Exports\Enums\ExportFormat;

public function getFormats(): array
{
    return [
        ExportFormat::Csv,
    ];
}

use App\Filament\Exports\Downloaders\CustomCsvDownloader;
use App\Filament\Exports\Downloaders\CustomXlsxDownloader;
use Filament\Actions\Exports\Downloaders\Contracts\Downloader;
use Filament\Actions\Exports\Enums\Contracts\ExportFormat as ExportFormatInterface;
use Filament\Actions\Exports\Enums\ExportFormat;

public static function getDownloader(ExportFormatInterface $format): Downloader
{
    return match ($format) {
        ExportFormat::Csv => app(CustomCsvDownloader::class),
        ExportFormat::Xlsx => app(CustomXlsxDownloader::class),
        default => $format->getDownloader(),
    };
}

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;
use Illuminate\Database\Eloquent\Builder;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->modifyQueryUsing(fn (Builder $query) => $query->where('is_active', true))

use App\Filament\Exports\ProductExporter;
use Illuminate\Database\Eloquent\Builder;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->modifyQueryUsing(fn (Builder $query, array $options) => $query->where('is_active', $options['isActive'] ?? true))

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\MorphTo;

public static function modifyQuery(Builder $query): Builder
{
    return $query->with([
        'purchasable' => fn (MorphTo $morphTo) => $morphTo->morphWith([
            ProductPurchase::class => ['product'],
            ServicePurchase::class => ['service'],
            Subscription::class => ['plan'],
        ]),
    ]);
}

use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->fileDisk('s3')

use Filament\Actions\ExportAction;

ExportAction::configureUsing(fn (ExportAction $action) => $action->fileDisk('s3'));

public function getFileDisk(): string
{
    return 's3';
}

use Filament\Actions\ExportAction;
use Filament\Actions\Exports\Models\Export;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->fileName(fn (Export $export): string => "products-{$export->getKey()}")

use Filament\Actions\Exports\Models\Export;

public function getFileName(Export $export): string
{
    return "products-{$export->getKey()}";
}

use Filament\Forms\Components\TextInput;

public static function getOptionsFormComponents(): array
{
    return [
        TextInput::make('descriptionLimit')
            ->label('Limit the length of the description column content')
            ->integer(),
    ];
}

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->options([
        'descriptionLimit' => 250,
    ])

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->formatStateUsing(function (string $state, array $options): string {
        return (string) str($state)->limit($options['descriptionLimit'] ?? 100);
    })

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->limit(fn (array $options): int => $options['descriptionLimit'] ?? 100)

$table->foreignId('user_id')->constrained()->cascadeOnDelete();

use App\Models\Admin;
use Illuminate\Contracts\Auth\Authenticatable;

$this->app->bind(Authenticatable::class, Admin::class);

$table->foreignId('user_id')->constrained('admins')->cascadeOnDelete();

$table->morphs('user');

use Filament\Actions\Exports\Models\Export;

Export::polymorphicUserRelationship();

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->maxRows(100000)

use App\Filament\Exports\ProductExporter;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->chunkSize(250)

public static function getCsvDelimiter(): string
{
    return ';';
}

use OpenSpout\Common\Entity\Style\Style;

public function getXlsxCellStyle(): ?Style
{
    return (new Style())
        ->setFontSize(12)
        ->setFontName('Consolas');
}

use OpenSpout\Common\Entity\Style\CellAlignment;
use OpenSpout\Common\Entity\Style\CellVerticalAlignment;
use OpenSpout\Common\Entity\Style\Color;
use OpenSpout\Common\Entity\Style\Style;

public function getXlsxHeaderCellStyle(): ?Style
{
    return (new Style())
        ->setFontBold()
        ->setFontItalic()
        ->setFontSize(14)
        ->setFontName('Consolas')
        ->setFontColor(Color::rgb(255, 255, 77))
        ->setBackgroundColor(Color::rgb(0, 0, 0))
        ->setCellAlignment(CellAlignment::CENTER)
        ->setCellVerticalAlignment(CellVerticalAlignment::CENTER);
}

use OpenSpout\Common\Entity\Row;
use OpenSpout\Common\Entity\Style\Style;

/**
 * @param array<mixed> $values
 */
public function makeXlsxRow(array $values, ?Style $style = null): Row
{
    return Row::fromValues($values, $style);
}

use OpenSpout\Common\Entity\Cell;
use OpenSpout\Common\Entity\Row;
use OpenSpout\Common\Entity\Style\Style;
use OpenSpout\Writer\Common\Manager\Style\StyleMerger;

/**
 * @param array<mixed> $values
 */
public function makeXlsxRow(array $values, ?Style $style = null): Row
{
    $styleMerger = new StyleMerger();

    $cells = [];
    
    foreach (array_keys($this->columnMap) as $columnIndex => $column) {
        $cells[] = match ($column) {
            'name' => Cell::fromValue(
                $values[$columnIndex],
                $styleMerger->merge(
                    (new Style())->setFontUnderline(),
                    $style,
                ),
            ),
            'price' => Cell::fromValue(
                $values[$columnIndex],
                (new Style())->setFontSize(12),
            ),
            default => Cell::fromValue($values[$columnIndex]),
        };
    }
    
    return new Row($cells, $style);
}

use OpenSpout\Writer\XLSX\Options;

public function getXlsxWriterOptions(): ?Options
{
    $options = new Options();
    $options->setColumnWidth(10, 1);
    $options->setColumnWidthForRange(12, 2, 3);
    
    return $options;
}

use OpenSpout\Common\Entity\Row;
use OpenSpout\Common\Entity\Style\Style;
use OpenSpout\Writer\XLSX\Writer;

public function configureXlsxWriterAfterOpen(Writer $writer): Writer
{
    $writer->addRow(Row::fromValues(
        ['This is a custom header added after opening the XLSX writer.'],
        (new Style())->setShouldWrapText(false),
    ));

    return $writer;
}

use OpenSpout\Writer\XLSX\Entity\SheetView;
use OpenSpout\Writer\XLSX\Writer;

public function configureXlsxWriterBeforeClose(Writer $writer): Writer
{
    $sheetView = new SheetView();
    $sheetView->setFreezeRow(2);
    $sheetView->setFreezeColumn('B');
    
    $sheet = $writer->getCurrentSheet();
    $sheet->setSheetView($sheetView);
    $sheet->setName('export');
    
    return $writer;
}

use Filament\Actions\Exports\Models\Export;

public static function getCompletedNotificationTitle(Export $export): string
{
    return 'Your product export is ready';
}

public static function getCompletedNotificationBody(Export $export): string
{
    return $export->successful_rows . ' products were exported.';
}

use Filament\Actions\Action;
use Filament\Actions\Exports\Models\Export;
use Filament\Notifications\Notification;

public static function modifyCompletedNotification(Notification $notification, Export $export): Notification
{
    $notification->icon('heroicon-o-shopping-bag');

    if ($export->getOptions()['notifyTeam'] ?? false) {
        $notification->actions([
            ...$notification->getActions(),
            Action::make('shareWithTeam')
                ->url(route('exports.share', $export)),
        ]);
    }

    return $notification;
}

use App\Jobs\PrepareCsvExport;
use Filament\Actions\Exports\Jobs\PrepareCsvExport as BasePrepareCsvExport;

$this->app->bind(BasePrepareCsvExport::class, PrepareCsvExport::class);

use App\Filament\Exports\ProductExporter;
use App\Jobs\PrepareCsvExport;
use Filament\Actions\ExportAction;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->job(PrepareCsvExport::class)

public function getJobQueue(): ?string
{
    return 'exports';
}

public function getJobConnection(): ?string
{
    return 'sqs';
}

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function getJobMiddleware(): array
{
    return [
        (new WithoutOverlapping("filament:exports:{$this->export->getKey()}"))->expireAfter(600),
    ];
}

use Carbon\CarbonInterface;

public function getJobRetryUntil(): ?CarbonInterface
{
    return now()->addHours(12);
}

/**
* @return int | array<int> | null
 */
public function getJobBackoff(): int | array | null
{
    return [60, 120, 300, 600];
}

public function getJobTags(): array
{
    return ["export{$this->export->getKey()}"];
}

public function getJobBatchName(): ?string
{
    return 'product-export';
}

use App\Policies\ExportPolicy;
use Filament\Actions\Exports\Models\Export;

protected $policies = [
    Export::class => ExportPolicy::class,
];

use App\Models\User;
use Filament\Actions\Exports\Models\Export;

public function view(User $user, Export $export): bool
{
    return $export->user()->is($user);
}

use Illuminate\Database\Eloquent\Builder;

ExportAction::make()
    ->exporter(ProductExporter::class)
    ->modifyQueryUsing(fn (Builder $query) => $query->whereBelongsTo(auth()->user()))

use Filament\Actions\Exports\ExportColumn;

ExportColumn::make('description')
    ->preventFormulaInjection()

use Filament\Actions\Exports\ExportColumn;

ExportColumn::configureUsing(function (ExportColumn $column): void {
    $column->preventFormulaInjection();
});

// Opt a specific column back out:
ExportColumn::make('temperature')
    ->preventFormulaInjection(false)