laravel-actions

Laravel Actions

lorisleiva/laravel-actionsを使うと、1つの特定のタスクを処理する単一の PHP クラスを作成し、用途に応じてオブジェクト、コントローラー、ジョブ、リスナー、コマンドとして実行できます。

インストール：composer require lorisleiva/laravel-actions 作成：php artisan make:action MyAction

基本構造

すべてのアクションは、AsActionトレイトとhandleメソッドを持つ通常の PHP クラスです。

use Lorisleiva\Actions\Concerns\AsAction;

class PublishNewArticle
{
    use AsAction;

    public function handle(User $author, string $title, string $body): Article
    {
        return $author->articles()->create(compact('title', 'body'));
    }
}

• アクションはトピックごとにグループ化してapp/Actions/に配置します（例：app/Actions/Articles/）
• 短く、動詞から始まる名前を付けます：SendWelcomeEmail、CreateInvoice、SyncContacts
• 依存関係の注入にはコンストラクターインジェクションを使います。アクションは常にコンテナーから解決されます

オブジェクトとして

// Resolve and run
PublishNewArticle::run($author, 'Title', 'Body');

// Resolve only
$action = PublishNewArticle::make();

// Conditional execution
PublishNewArticle::runIf($condition, $author, 'Title', 'Body');
PublishNewArticle::runUnless($condition, $author, 'Title', 'Body');

コントローラーとして

呼び出し可能なコントローラーと同様に、ルートに登録します。

Route::post('/articles', PublishNewArticle::class)->middleware('auth');

asControllerを実装して、リクエストデータをhandleの引数に割り当てます。

public function asController(Request $request): ArticleResource
{
    $article = $this->handle(
        $request->user(),
        $request->input('title'),
        $request->input('body'),
    );
    return new ArticleResource($article);
}

asControllerを省略すると、handleがそのまま呼び出し可能なメソッドとして使われます。

アクション自体のミドルウェア：

public function getControllerMiddleware(): array
{
    return ['auth', 'verified'];
}

JSON と HTML で異なるレスポンスを返す場合：

public function jsonResponse(Article $article, Request $request): ArticleResource
{
    return new ArticleResource($article);
}

public function htmlResponse(Article $article, Request $request): RedirectResponse
{
    return redirect()->route('articles.show', $article);
}

ルートをインラインで登録する（任意）：

public static function routes(Router $router): void
{
    $router->post('/articles', static::class);
}

その後、サービスプロバイダーでActions::registerRoutes(['app/Actions'])を呼び出します。

複数のエンドポイントを持つアクションの明示的なルートメソッド：

Route::get('/articles/create', [PublishNewArticle::class, 'showForm']);
Route::post('/articles', PublishNewArticle::class);

バリデーションと認可（コントローラーとして）

ActionRequestを注入すると、アクション自体に定義されたバリデーションと認可が実行されます。

use Lorisleiva\Actions\ActionRequest;

public function asController(ActionRequest $request): ArticleResource
{
    $article = $this->handle(
        $request->user(),
        $request->validated('title'),
        $request->validated('body'),
    );
    return new ArticleResource($article);
}

public function authorize(ActionRequest $request): bool
{
    return $request->user()->can('create', Article::class);
}

public function rules(): array
{
    return [
        'title' => ['required', 'string', 'max:255'],
        'body'  => ['required', 'string'],
    ];
}

追加のバリデーションフック：

public function prepareForValidation(ActionRequest $request): void { /* mutate input */ }
public function withValidator(Validator $validator): void { /* add callbacks */ }
public function afterValidator(Validator $validator): void { /* after hook */ }
public function getValidator(): Validator { /* full control */ }
public function getValidationData(): array { return $this->all(); }
public function getValidationMessages(): array { return []; }
public function getValidationAttributes(): array { return []; }
public function getValidationRedirect(Request $request): string { return url()->previous(); }
public function getValidationErrorBag(): string { return 'default'; }
public function getValidationFailure(): void { throw new ValidationException(...); }
public function getAuthorizationFailure(): void { throw new AuthorizationException(...); }

ジョブとして

// Async dispatch
PublishNewArticle::dispatch($author, 'Title', 'Body');

// Conditional dispatch
PublishNewArticle::dispatchIf($cond, $author, 'Title', 'Body');
PublishNewArticle::dispatchUnless($cond, $author, 'Title', 'Body');

// Sync dispatch
PublishNewArticle::dispatchSync($author, 'Title', 'Body');

// After response is sent
PublishNewArticle::dispatchAfterResponse($author, 'Title', 'Body');

ジョブ固有の動作がhandleと異なる場合にのみ、asJobを実装します。

public function asJob(Team $team): void
{
    $this->handle($team, fullReport: true);
}

ジョブのデフォルト設定：

public string $queue = 'emails';
public int $tries = 3;
public int $timeout = 60;
public int $maxExceptions = 2;

public function configureJob(JobDecorator $job): void
{
    $job->onQueue('high')->delay(now()->addMinutes(5));
}

public function getJobBackoff(): array { return [10, 30, 60]; }
public function getJobRetryUntil(): DateTime { return now()->addHour(); }
public function getJobMiddleware(): array { return [new WithoutOverlapping($this->team->id)]; }

ユニークジョブ：

use Illuminate\Contracts\Queue\ShouldBeUnique;

class SendTeamReport implements ShouldBeUnique
{
    use AsAction;

    public function getJobUniqueId(Team $team): int { return $team->id; }
    public function getJobUniqueFor(): int { return 3600; }
}

ジョブのチェーン：

SendWelcomeEmail::withChain([
    VerifyEmailAddress::makeJob($user),
    AssignDefaultRole::makeJob($user),
])->dispatch($user);

バッチ処理：

use Illuminate\Support\Facades\Bus;

Bus::batch([
    ProcessInvoice::makeJob($invoiceA),
    ProcessInvoice::makeJob($invoiceB),
])->dispatch();

Horizon タグと表示名：

public function getJobTags(Team $team): array { return ["team:{$team->id}"]; }
public function getJobDisplayName(): string { return 'Send Team Report'; }

リスナーとして

EventServiceProviderに登録します。

protected $listen = [
    UserRegistered::class => [SendWelcomeEmail::class],
];

または、Event ファサードを使います。

Event::listen(UserRegistered::class, SendWelcomeEmail::class);

キューに登録可能なリスナーにするには、アクションにimplements ShouldQueueを追加します。

asListenerを使って、イベントデータをhandleの引数に割り当てます。

public function asListener(UserRegistered $event): void
{
    $this->handle($event->user);
}

コマンドとして

Kernel::$commandsに登録するか、自動登録します。

Actions::registerCommands(['app/Actions']);

use Illuminate\Console\Command;

class SendTeamReport
{
    use AsAction;

    public string $commandSignature = 'teams:report {team_id}';
    public string $commandDescription = 'Send the weekly report to a team.';

    public function asCommand(Command $command): void
    {
        $team = Team::findOrFail($command->argument('team_id'));
        $this->handle($team);
        $command->info('Report sent!');
    }

    // Dynamic signature/description/help:
    public function getCommandSignature(): string { return '...'; }
    public function getCommandDescription(): string { return '...'; }
    public function getCommandHelp(): string { return '...'; }
    public function isCommandHidden(): bool { return false; }
}

テストとモック

// Mock — set expectations before running
PublishNewArticle::mock()
    ->shouldReceive('handle')
    ->once()
    ->andReturn($fakeArticle);

// Shorthand
PublishNewArticle::mock()->shouldRun()->once()->andReturn($fakeArticle);
PublishNewArticle::mock()->shouldNotRun();

// Partial mock (only mocked methods get expectations)
PublishNewArticle::partialMock()->shouldReceive('fetch')->andReturn([...]);

// Spy — run first, assert after
PublishNewArticle::spy()->shouldHaveReceived('handle')->once();
PublishNewArticle::spy()->allowToRun();

// Lifecycle helpers
PublishNewArticle::isFake();   // bool — is currently mocked?
PublishNewArticle::clearFake(); // reset to real implementation

ジョブがディスパッチされたことをアサートする：

Queue::fake();

// ...trigger code...

PublishNewArticle::assertPushed();
PublishNewArticle::assertPushed(2); // dispatched exactly N times
PublishNewArticle::assertPushed(fn ($action, $args) => $args[0]->is($team));
PublishNewArticle::assertNotPushed();
PublishNewArticle::assertPushedOn('high', fn ($action, $args) => true);

WithAttributes（任意、v2.1+）

検証済みの統一された属性バッグが役立つアクション（v1 のコードを移行する場合や、オブジェクトとコントローラーの両方で同じバリデーションを適用する場合など）：

use Lorisleiva\Actions\Concerns\AsAction;
use Lorisleiva\Actions\Concerns\WithAttributes;

class PublishNewArticle
{
    use AsAction;
    use WithAttributes;

    public function handle(User $author, array $data = []): Article
    {
        $this->fill($data);
        $this->validateAttributes(); // triggers authorize + rules
        return $author->articles()->create($this->validated());
    }

    public function asController(ActionRequest $request): Article
    {
        $this->fillFromRequest($request);
        return $this->handle($request->user());
    }
}

WithAttributesのメソッド：fill、set、get、has、all、only、except、fillFromRequest、validateAttributes。

注：WithAttributesを使う場合、ActionRequestは自動でバリデーションを実行しません。必要に応じて$request->validate()を手動で呼び出してください。

より細かなトレイト

AsActionの代わりに、必要なトレイトだけを選んで使えます。

• AsObject — run、make、runIf、runUnless
• AsController — コントローラーデコレーターのサポート
• AsJob — ジョブデコレーターのサポート
• AsListener — リスナーデコレーターのサポート
• AsCommand — コマンドデコレーターのサポート
• AsFake — モック／スパイのサポート

リファレンスドキュメント

API の詳細については、以下を参照してください。

• references/api.md — トレイトごとのメソッド一覧