From 378906e8331aac77f2e6488055b0f8b158e0073b Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Wed, 30 Apr 2025 10:53:05 +0100 Subject: [PATCH] docs --- .../03-resources/07-managing-relationships.md | 54 +++++++++++++++++++ packages/actions/docs/07-delete.md | 27 ++++++++++ packages/actions/docs/09-force-delete.md | 27 ++++++++++ packages/actions/docs/10-restore.md | 27 ++++++++++ packages/tables/docs/04-actions.md | 32 +++++++++++ 5 files changed, 167 insertions(+) diff --git a/docs/03-resources/07-managing-relationships.md b/docs/03-resources/07-managing-relationships.md index 9b46f7612e..06760e8574 100644 --- a/docs/03-resources/07-managing-relationships.md +++ b/docs/03-resources/07-managing-relationships.md @@ -378,6 +378,33 @@ public function table(Table $table): Table } ``` +### Improving the performance of detach bulk actions + +By default, the `DetachBulkAction` will load all Eloquent records into memory, before looping over them and detaching them one by one. + +If you are detaching a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\DetachBulkAction; + +DetachBulkAction::make() + ->chunkSelectedRecords(250) +``` + +Filament loads Eloquent records into memory before detaching them for two reasons: + +- To allow individual records in the collection to be authorized with a model policy before detaching (using `authorizeIndividualRecords('delete')`, for example). +- To ensure that model events are run when detaching records, such as the `deleting` and `deleted` events in a model observer. + +If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before detaching them, and instead will detach them in a single query: + +```php +use Filament\Actions\DetachBulkAction; + +DetachBulkAction::make() + ->fetchSelectedRecords(false) +``` + ## Associating and dissociating records Filament is able to associate and dissociate records for `HasMany` and `MorphMany` relationships. @@ -475,6 +502,33 @@ AssociateAction::make() ) ``` +### Improving the performance of dissociate bulk actions + +By default, the `DissociateBulkAction` will load all Eloquent records into memory, before looping over them and dissociating them one by one. + +If you are dissociating a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\DissociateBulkAction; + +DissociateBulkAction::make() + ->chunkSelectedRecords(250) +``` + +Filament loads Eloquent records into memory before dissociating them for two reasons: + +- To allow individual records in the collection to be authorized with a model policy before dissociation (using `authorizeIndividualRecords('update')`, for example). +- To ensure that model events are run when dissociating records, such as the `updating` and `updated` events in a model observer. + +If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before dissociating them, and instead will dissociate them in a single query: + +```php +use Filament\Actions\DissociateBulkAction; + +DissociateBulkAction::make() + ->fetchSelectedRecords(false) +``` + ## Viewing related records When generating your relation manager, you may pass the `--view` flag to also add a `ViewAction` to the table: diff --git a/packages/actions/docs/07-delete.md b/packages/actions/docs/07-delete.md index b7f4877f8b..2cff7be00e 100644 --- a/packages/actions/docs/07-delete.md +++ b/packages/actions/docs/07-delete.md @@ -99,3 +99,30 @@ DeleteAction::make() ``` These hook functions can inject various utilities as parameters. + +## Improving the performance of delete bulk actions + +By default, the `DeleteBulkAction` will load all Eloquent records into memory, before looping over them and deleting them one by one. + +If you are deleting a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\DeleteBulkAction; + +DeleteBulkAction::make() + ->chunkSelectedRecords(250) +``` + +Filament loads Eloquent records into memory before deleting them for two reasons: + +- To allow individual records in the collection to be authorized with a model policy before deletion (using `authorizeIndividualRecords('delete')`, for example). +- To ensure that model events are run when deleting records, such as the `deleting` and `deleted` events in a model observer. + +If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before deleting them, and instead will delete them in a single query: + +```php +use Filament\Actions\DeleteBulkAction; + +DeleteBulkAction::make() + ->fetchSelectedRecords(false) +``` diff --git a/packages/actions/docs/09-force-delete.md b/packages/actions/docs/09-force-delete.md index 64256c3591..797fd55f3f 100644 --- a/packages/actions/docs/09-force-delete.md +++ b/packages/actions/docs/09-force-delete.md @@ -99,3 +99,30 @@ ForceDeleteAction::make() ``` These hook functions can inject various utilities as parameters. + +## Improving the performance of force delete bulk actions + +By default, the `ForceDeleteBulkAction` will load all Eloquent records into memory, before looping over them and deleting them one by one. + +If you are deleting a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\ForceDeleteBulkAction; + +ForceDeleteBulkAction::make() + ->chunkSelectedRecords(250) +``` + +Filament loads Eloquent records into memory before deleting them for two reasons: + +- To allow individual records in the collection to be authorized with a model policy before deletion (using `authorizeIndividualRecords('forceDelete')`, for example). +- To ensure that model events are run when deleting records, such as the `forceDeleting` and `forceDeleted` events in a model observer. + +If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before deleting them, and instead will delete them in a single query: + +```php +use Filament\Actions\ForceDeleteBulkAction; + +ForceDeleteBulkAction::make() + ->fetchSelectedRecords(false) +``` diff --git a/packages/actions/docs/10-restore.md b/packages/actions/docs/10-restore.md index f5cb4f4504..fa476df16e 100644 --- a/packages/actions/docs/10-restore.md +++ b/packages/actions/docs/10-restore.md @@ -99,3 +99,30 @@ RestoreAction::make() ``` These hook functions can inject various utilities as parameters. + +## Improving the performance of restore bulk actions + +By default, the `RestoreBulkAction` will load all Eloquent records into memory, before looping over them and restoring them one by one. + +If you are restoring a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\RestoreBulkAction; + +RestoreBulkAction::make() + ->chunkSelectedRecords(250) +``` + +Filament loads Eloquent records into memory before restoring them for two reasons: + +- To allow individual records in the collection to be authorized with a model policy before restoration (using `authorizeIndividualRecords('restore')`, for example). +- To ensure that model events are run when restoring records, such as the `restoring` and `restored` events in a model observer. + +If you do not require individual record policy authorization and model events, you can use the `fetchSelectedRecords(false)` method, which will not fetch the records into memory before restoring them, and instead will restore them in a single query: + +```php +use Filament\Actions\RestoreBulkAction; + +RestoreBulkAction::make() + ->fetchSelectedRecords(false) +``` diff --git a/packages/tables/docs/04-actions.md b/packages/tables/docs/04-actions.md index ef5c6938f3..ea4db66164 100644 --- a/packages/tables/docs/04-actions.md +++ b/packages/tables/docs/04-actions.md @@ -367,6 +367,38 @@ public function table(Table $table): Table } ``` +### Improving the performance of bulk actions + +By default, a bulk action will load all Eloquent records into memory before passing them to the `action()` function. + +If you are processing a large number of records, you may want to use the `chunkSelectedRecords()` method to fetch a smaller number of records at a time. This will reduce the memory usage of your application: + +```php +use Filament\Actions\BulkAction; +use Illuminate\Support\LazyCollection; + +BulkAction::make() + ->chunkSelectedRecords(250) + ->action(function (LazyCollection $records) { + // Process the records... + }) +``` + +You can still loop through the `$records` collection as normal, but the collection will be a `LazyCollection` instead of a normal collection. + +You can also prevent Filament from fetching the Eloquent models in the first place, and instead just pass the IDs of the selected records to the `action()` function. This is useful if you are processing a large number of records, and you don't need to load them into memory: + +```php +use Filament\Actions\BulkAction; +use Illuminate\Support\Collection; + +BulkAction::make() + ->fetchSelectedRecords(false) + ->action(function (Collection $records) { + // Process the records... + }) +``` + ## Header actions Both [row actions](#row-actions) and [bulk actions](#bulk-actions) can be rendered in the header of the table. You can put them in the `$table->headerActions()` method: