spatie-laravel-php

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spatie Laravel & PHP Guidelines

Spatie Laravel & PHP 编码指南

Overview

概述

Apply Spatie's Laravel and PHP guidelines to keep code style consistent and Laravel-native.

遵循Spatie的Laravel和PHP编码指南，保持代码风格一致且符合Laravel原生规范。

When to Activate

启用场景

Activate this skill for any Laravel or PHP coding work, even if the user does not explicitly mention Spatie.
Activate this skill when asked to generate, edit, format, refactor, review, or align Laravel/PHP code.
Activate this skill when working on
```
.php
```
or
```
.blade.php
```
files, routes, controllers, models, config, validation, migrations, or tests.

任何Laravel或PHP编码工作都应启用该规则，即使用户未明确提及Spatie。
当需要生成、编辑、格式化、重构、审核或对齐Laravel/PHP代码时，启用该规则。
处理
```
.php
```
或
```
.blade.php
```
文件、路由、控制器、模型、配置、验证、迁移或测试时，启用该规则。

Scope

适用范围

In scope:
```
.php
```
,
```
.blade.php
```
, Laravel conventions (routes, controllers, config, validation, migrations, tests).
Out of scope: JS/TS, CSS, infrastructure, database schema design, non-Laravel frameworks.

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

Workflow

工作流程

Identify the artifact (controller, route, config, model, Blade, test, etc.).

Read

references/spatie-laravel-php-guidelines.md

and focus on the relevant sections.

Apply the core Laravel principle first, then PHP standards, then section-specific rules.
If a rule conflicts with existing project conventions, follow Laravel conventions and keep changes consistent.

确定目标文件类型（控制器、路由、配置、模型、Blade、测试等）。

阅读

references/spatie-laravel-php-guidelines.md

并关注相关章节。

首先遵循Laravel核心原则，其次是PHP标准，最后是特定章节的规则。
如果规则与现有项目约定冲突，优先遵循Laravel约定并保持修改一致性。

Core Rules (Summary)

核心规则（摘要）

Follow Laravel conventions first.
Follow PSR-1, PSR-2, and PSR-12.
Prefer typed properties and explicit return types (including
```
void
```
).
Use short nullable syntax like
```
?string
```
.
Use constructor property promotion when all properties can be promoted.
One trait per line with separate
```
use
```
statements.
Prefer early returns and avoid
```
else
```
when possible.
Always use curly braces for control structures.
Use string interpolation over concatenation.
Happy path last: handle error conditions first.

优先遵循Laravel约定。
遵循PSR-1、PSR-2和PSR-12标准。
优先使用类型化属性和显式返回类型（包括
```
void
```
）。
使用
```
?string
```
这类简短可空语法。
当所有属性都可提升时，使用构造函数属性提升。
每个
```
trait
```
单独一行，使用独立的
```
use
```
语句。
优先提前返回，尽可能避免使用
```
else
```
。
控制结构始终使用大括号。
使用字符串插值而非字符串拼接。
正常路径后置：先处理错误条件。

Do and Don't

注意事项（Do和Don't）

Do:

Use kebab-case URLs, camelCase route names, and camelCase route parameters.
Use tuple notation for routes:
```
[Controller::class, 'method']
```
.
Use plural resource names for controllers (
```
PostsController
```
).
Use array notation for validation rules.
Use
```
config()
```
helper and avoid
```
env()
```
outside config files.
Add service configs to
```
config/services.php
```
, not new files.
Use
```
__()
```
for translations instead of
```
@lang
```
.
Use PascalCase for enum values.

Don't:

Add docblocks when full type hints already exist.
Use fully qualified classnames in docblocks.
Use
```
final
```
or
```
readonly
```
by default.
Use
```
else
```
when early returns work.
Add spaces after Blade control structures.
Write down methods in migrations, only up methods.

Do：

URL使用短横线命名法（kebab-case），路由名称和路由参数使用驼峰命名法（camelCase）。
路由使用元组表示法：
```
[Controller::class, 'method']
```
。
控制器使用复数资源名称（如
```
PostsController
```
）。
验证规则使用数组表示法。
使用
```
config()
```
助手函数，避免在配置文件外使用
```
env()
```
。
将服务配置添加到
```
config/services.php
```
，不要新建文件。
使用
```
__()
```
进行翻译，而非
```
@lang
```
。
枚举值使用帕斯卡命名法（PascalCase）。

Don't：

当已有完整类型提示时，不要添加文档块（docblocks）。
不要在文档块中使用完全限定类名。
默认不要使用
```
final
```
或
```
readonly
```
。
当可以提前返回时，不要使用
```
else
```
。
Blade控制结构后不要添加空格。
迁移文件中不要编写down方法，只保留up方法。

Examples

示例

php

// 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,
    ) {}
}

blade

@if($condition)
    Something
@endif

php

// 正常路径后置，提前返回
if (! $user) {
    return null;
}

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

// 处理活跃用户...

// 简短三元运算符
$name = $isFoo ? 'foo' : 'bar';

// 构造函数属性提升
class MyClass {
    public function __construct(
        protected string $firstArgument,
        protected string $secondArgument,
    ) {}
}

blade

@if($condition)
    Something
@endif

References

参考资料

references/spatie-laravel-php-guidelines.md

references/spatie-laravel-php-guidelines.md