spatie-laravel-php

Spatie Laravel 和 PHP 指南

概述

遵循 Spatie 的 Laravel 和 PHP 指南，保持代码风格一致并符合 Laravel 原生惯例。

何时启用

• 对任何 Laravel 或 PHP 编码工作启用此技能，即使用户没有明确提及 Spatie。
• 在被要求生成、编辑、格式化、重构、审查或调整 Laravel/PHP 代码时启用此技能。
• 在处理 .php 或 .blade.php 文件、路由、控制器、模型、配置、验证、迁移或测试时启用此技能。

适用范围

• 适用范围：.php、.blade.php、Laravel 惯例（路由、控制器、配置、验证、迁移、测试）。
• 不适用范围：JS/TS、CSS、基础设施、数据库架构设计、非 Laravel 框架。

工作流

1. 确定代码对象（控制器、路由、配置、模型、Blade、测试等）。
2. 阅读 references/spatie-laravel-php-guidelines.md，重点关注相关部分。
3. 首先应用 Laravel 核心原则，然后遵循 PHP 标准，最后应用特定部分的规则。
4. 如果规则与现有项目惯例冲突，则遵循 Laravel 惯例，并确保改动保持一致。

核心规则（摘要）

• 优先遵循 Laravel 惯例。
• 遵循 PSR-1、PSR-2 和 PSR-12。
• 优先使用类型化属性和显式返回类型（包括 void）。
• 使用简短的可空类型语法，如 ?string。
• 所有属性都可以提升时，使用构造函数属性提升。
• 每行使用一个 trait，并分别使用 use 语句。
• 方法链一旦换行，后续每个 -> 都必须另起一行；不要混用单行和多行链式调用。
• 优先提前返回，并尽可能避免使用 else。
• 控制结构始终使用花括号。
• 优先使用字符串插值，而非拼接。
• 将正常流程放在最后：先处理错误情况。

应做和不应做

应做：

• URL 使用 kebab-case，路由名称使用 camelCase，路由参数使用 camelCase。
• 路由使用元组表示法：[Controller::class, 'method']。
• 控制器使用复数资源名称（PostsController）。
• 验证规则使用数组表示法。
• 使用 config() 辅助函数，并避免在配置文件之外使用 env()。
• 将服务配置添加到 config/services.php，而不是新建文件。
• 使用 __() 进行翻译，而不是 @lang。
• 枚举值和类常量使用 PascalCase。

不应做：

• 已有完整类型提示时，不要添加文档块。
• 不要在文档块中使用完全限定类名。
• 默认不要使用 final 或 readonly。
• 可以提前返回时，不要使用 else。
• Blade 控制结构后不要添加空格。

示例

// Happy path last with early returns
if (! $user) {
    return null;
}

if (! $user->isActive()) {
    return null;
}

// Process active user...

// Short ternary
$name = $isFoo ? 'foo' : 'bar';

// Constructor property promotion
class MyClass {
    public function __construct(
        protected string $firstArgument,
        protected string $secondArgument,
    ) {}
}

@if($condition)
    Something
@endif

参考资料

• references/spatie-laravel-php-guidelines.md