• 将动作放在 app/Actions/ 中，按主题分组（例如 app/Actions/Articles/）
• 使用简短的动词优先的句子命名：SendWelcomeEmail、CreateInvoice、SyncContacts
• 使用构造函数注入依赖项——动作总是从容器中解析

作为对象

// 解析并运行
PublishNewArticle::run($author, 'Title', 'Body');

// 仅解析
$action = PublishNewArticle::make();

// 条件执行
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 { /* 修改输入 */ }
public function withValidator(Validator $validator): void { /* 添加回调 */ }
public function afterValidator(Validator $validator): void { /* 后置钩子 */ }
public function getValidator(): Validator { /* 完全控制 */ }
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(...); }

作为任务

// 异步分发
PublishNewArticle::dispatch($author, 'Title', 'Body');

// 条件分发
PublishNewArticle::dispatchIf($cond, $author, 'Title', 'Body');
PublishNewArticle::dispatchUnless($cond, $author, 'Title', 'Body');

// 同步分发
PublishNewArticle::dispatchSync($author, 'Title', 'Body');

// 响应发送后分发
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!');
    }

    // 动态签名/描述/帮助：
    public function getCommandSignature(): string { return '...'; }
    public function getCommandDescription(): string { return '...'; }
    public function getCommandHelp(): string { return '...'; }
    public function isCommandHidden(): bool { return false; }
}

测试与模拟

// 模拟 — 在运行前设置期望
PublishNewArticle::mock()
    ->shouldReceive('handle')
    ->once()
    ->andReturn($fakeArticle);

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

// 部分模拟（只有被模拟的方法获得期望）
PublishNewArticle::partialMock()->shouldReceive('fetch')->andReturn([...]);

// 间谍 — 先运行，后断言
PublishNewArticle::spy()->shouldHaveReceived('handle')->once();
PublishNewArticle::spy()->allowToRun();

// 生命周期助手
PublishNewArticle::isFake();   // bool — 当前是否被模拟？
PublishNewArticle::clearFake(); // 重置为真实实现

断言任务已分发：

Queue::fake();

// ...触发代码...

PublishNewArticle::assertPushed();
PublishNewArticle::assertPushed(2); // 恰好分发 N 次
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(); // 触发 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 — 每个特质的完整方法列表

每周安装次数

1

仓库

aaronflorey/agent-skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装在

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

• Place actions in app/Actions/ grouped by topic (e.g. app/Actions/Articles/)
• Name them as short verb-first sentences: SendWelcomeEmail, CreateInvoice, SyncContacts
• Use constructor injection for dependencies — actions are always resolved from the container

As an Object

// 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');

As a Controller

Register in routes just like an invokable controller:

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

Implement asController to map request data to handle args:

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

If asController is omitted, handle is used directly as the invokable.

Middleware on the action itself:

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

Different responses for JSON vs 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);
}

Register routes inline (optional):

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

Then call Actions::registerRoutes(['app/Actions']) in a service provider.

Explicit route methods for multi-endpoint actions:

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

Validation & Authorization (as Controller)

Inject ActionRequest to trigger validation/authorization defined on the action itself:

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'],
    ];
}

Additional validation hooks:

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(...); }

As a Job

// 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');

Implement asJob only when the job-specific behaviour differs from handle:

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

Configure job defaults:

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)]; }

Unique jobs:

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; }
}

Job chaining:

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

Batching:

use Illuminate\Support\Facades\Bus;

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

Horizon tags & display name:

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

As a Listener

Register in EventServiceProvider:

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

Or with the Event facade:

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

For a queueable listener , add implements ShouldQueue to the action.

Use asListener to map event data to handle args:

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

As a Command

Register in Kernel::$commands or auto-register:

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; }
}

Testing & Mocking

// 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

Assert jobs were dispatched:

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 (optional, v2.1+)

For actions that benefit from validated, unified attribute bags (useful when porting v1 code or when the same validation should apply across object and controller usage):

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 methods: fill, set, get, has, all, only, except, fillFromRequest, validateAttributes.

Note: when WithAttributes is used, the ActionRequest will not auto-validate — call $request->validate() manually if needed.

More granular traits

Instead of AsAction you can cherry-pick:

• AsObject — run, make, runIf, runUnless
• AsController — controller decorator support
• AsJob — job decorator support
• AsListener — listener decorator support
• AsCommand — command decorator support
• AsFake — mock/spy support

Reference docs

For full API details, see:

• references/api.md — complete method list per trait

Weekly Installs

1

Repository

aaronflorey/agent-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1