npx skills add https://github.com/aaronflorey/agent-skills --skill laravel-actionslorisleiva/laravel-actions 允许你编写一个单一的 PHP 类来处理一项特定任务,并将其作为对象、控制器、任务、监听器或命令运行——视情况而定。
安装:composer require lorisleiva/laravel-actions 创建:php artisan make:action MyAction
每个动作都是一个普通的 PHP 类,包含 AsAction 特质和一个 handle 方法:
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'));
}
}
lorisleiva/laravel-actions lets you write a single PHP class that handles one specific task and run it as an object , controller , job , listener , or command — whichever is appropriate.
Install: composer require lorisleiva/laravel-actions Create: php artisan make:action MyAction
Every action is a plain PHP class with the AsAction trait and a handle method:
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'));
}
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
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);
适用于受益于已验证的统一属性包的动作(在移植 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, runUnlessAsController — 控制器装饰器支持AsJob — 任务装饰器支持AsListener — 监听器装饰器支持AsCommand — 命令装饰器支持AsFake — 模拟/间谍支持完整的 API 详情,请参阅:
每周安装次数
1
仓库
首次出现
1 天前
安全审计
安装在
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
app/Actions/ grouped by topic (e.g. 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');
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);
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(...); }
// 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'; }
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);
}
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; }
}
// 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);
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.
Instead of AsAction you can cherry-pick:
AsObject — run, make, runIf, runUnlessAsController — controller decorator supportAsJob — job decorator supportAsListener — listener decorator supportAsCommand — command decorator supportAsFake — mock/spy supportFor full API details, see:
Weekly Installs
1
Repository
First Seen
1 day ago
Security Audits
Installed on
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
109,600 周安装