Skip to content
bulk-actions / 1

Defining actions

Last updated:

On this page

A BulkActions holds the actions of one index page. Define it as a class (the usual way, and required for queued runs), or inline for a one-off.

A bulk actions class

namespace App\BulkActions;

use App\Models\Article;
use Illuminate\Support\Collection;
use Javaabu\BulkActions\Actions\Action;
use Javaabu\BulkActions\Actions\DeleteAction;
use Javaabu\BulkActions\Actions\ForceDeleteAction;
use Javaabu\BulkActions\Actions\RestoreAction;
use Javaabu\BulkActions\BulkActions;

class ArticleBulkActions extends BulkActions
{
    protected ?string $model = Article::class;

    protected function actions(): array
    {
        return [
            DeleteAction::make(),
            RestoreAction::make(),
            ForceDeleteAction::make(),

            Action::make('publish')
                ->label(__('Publish'))
                ->icon('check')
                ->color('success')
                ->requiresConfirmation(__('Publish the selected articles?'))
                ->successMessage(__(':count articles published.'))
                ->can('publish_articles')
                ->canEach('update')
                ->handle(fn (Collection $articles) => $articles->each->publish()),
        ];
    }
}

Create it with ArticleBulkActions::make(). Override setUp() to configure it further:

protected function setUp(): void
{
    $this->queueAfter(1000)->chunkSize(200);
}

Inline

$bulk_actions = BulkActions::make([
    DeleteAction::make(),
    Action::make('archive')->each(fn (Article $article) => $article->archive()),
])->model(Article::class)->url(route('articles.bulk'));

Inline bulk actions run during the request only: a queued run rebuilds the actions in the job, which needs a class. A class configured at runtime (PostBulkActions::for($post_type)) keeps what it needs in its context. An inline action that would be queued throws a BulkActionsException; set ->queue(false) on it, or move it to a class.

The records

model() (or the $model property) is the model the actions run on. Every record of it may be selected, unless you narrow the query:

// in a class
public function newQuery(): Builder
{
    return Article::query()->whereBelongsTo(request()->user()->organization);
}

// inline
BulkActions::make([...])->query(fn () => Article::query()->whereBelongsTo($organization));

Ids that aren't in the query are ignored, so a tampered request can't reach other records. Use this to scope by tenant or owner, as well as authorizing the action.

name() is the name of the row checkboxes, the model of javaabu/forms' table (articles for articles[]). It defaults to the model's plural in snake case (Article → articles, BlogPost → blog_posts).

Actions

Action::make('publish')                    // the name, sent as `action`
    ->label(__('Publish'))                 // default: the name as a headline, through __()
    ->icon('check')                        // a javaabu/forms icon name
    ->color('success')                     // the confirm button's color: primary, danger, warning, success, …
    ->requiresConfirmation()               // ask before running; pass a string for the question
    ->confirmationHeading(__('Publish'))   // default: the label
    ->confirmationText(__('Publish the selected articles?'))
    ->confirmButtonLabel(__('Yes, publish'))
    ->successMessage(__(':count articles published.'))
    ->visible(fn () => request()->routeIs('articles.index'))
    ->meta(['shortcut' => 'p']);           // extra data for custom views and components

Every option takes a closure. Closures get arguments by name ($action, $bulkActions, $model, $user) or by type.

What it does

Give each action a handler. handle() gets each chunk of records the user may act on; each() gets one record at a time.

Action::make('publish')
    ->handle(fn (Collection $articles, array $data, User $user) => $articles->each->publish());

Action::make('archive')
    ->each(fn (Article $article, array $data) => $article->archive($data['reason']));
  • $data is the action form's validated values (see Actions with forms), or [].
  • handle() may return how many records succeeded; the rest count as failed. Return nothing when all did.
  • With each(), a record that throws is counted as failed and the exception is reported; the others carry on. With handle(), an exception fails the whole chunk.
  • Records are loaded chunkSize() at a time (bulk-actions.chunk_size, 100), in key order, so a handler that deletes or changes records is safe.

modifyQueryUsing() changes the query the records come from, for this action:

Action::make('purge')->modifyQueryUsing(fn (Builder $query) => $query->onlyTrashed());

The success message

The message shown afterwards. :count is the records that succeeded, :skipped, :failed and :total the others, :action the label. Pass a closure to build it from the $result:

->successMessage(fn (ActionResult $result) => trans_choice('{1} One article published|[2,*] :count articles published', $result->succeeded))

Without one, it's "Publish: 3 records done." When records were skipped or failed, a sentence about them is added.

Built-in actions

Action Name Does Checks each record with Confirms
DeleteAction delete $record->delete() (soft deletes when the model uses SoftDeletes) delete yes
RestoreAction restore $record->restore(), on trashed records only restore no
ForceDeleteAction force_delete $record->forceDelete(), trashed or not forceDelete yes

Records are handled one at a time, so model events and observers run. RestoreAction and ForceDeleteAction are hidden and refused for models without SoftDeletes. Everything is configurable as on any action:

DeleteAction::make()->can('delete_articles')->label(__('Move to trash'));
RestoreAction::make()->visible(fn () => request()->routeIs('articles.trash'));

To write your own reusable action, extend Action, return its name from getDefaultName() and configure it in setUp():

class PublishAction extends Action
{
    public static function getDefaultName(): ?string
    {
        return 'publish';
    }

    protected function setUp(): void
    {
        $this->label(fn () => __('Publish'))
            ->canEach('update')
            ->each(fn (Model $record) => $record->publish());
    }
}
Documentation
All packages

javaabu/bulk-actions

Source on GitHub