spatie-laravel-php-standards

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
```
.
Prefer early returns and avoid
```
else
```
when possible.
Always use curly braces for control structures.
Use string interpolation over concatenation.

优先遵循Laravel惯例。
遵循PSR-1、PSR-2和PSR-12标准。
优先使用类型化属性和显式返回类型（包括
```
void
```
）。
使用
```
?string
```
这类简短的可空类型语法。
优先提前返回，尽可能避免使用
```
else
```
。
控制结构始终使用大括号。
使用字符串插值而非字符串拼接。

Do and Don't

注意事项

Do:

Use kebab-case URLs, camelCase route names, and camelCase route parameters.
Use array notation for validation rules.
Use
```
config()
```
and avoid
```
env()
```
outside config files.

Don't:

Add docblocks when full type hints already exist.
Use fully qualified classnames in docblocks.
Use
```
@lang
```
instead of
```
__()
```
.

推荐做法：

URL使用短横线命名（kebab-case），路由名称和路由参数使用驼峰命名（camelCase）。
验证规则使用数组语法。
使用
```
config()
```
函数，避免在配置文件外使用
```
env()
```
。

不推荐做法：

已有完整类型提示时，无需添加文档块（docblocks）。
文档块中不使用完全限定类名。
避免使用
```
@lang
```
，改用
```
__()
```
。

Examples

示例

php

if (! $user) {
    return null;
}

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

$name = $isFoo ? 'foo' : 'bar';

blade

@if($condition)
    Something
@endif

php

if (! $user) {
    return null;
}

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

$name = $isFoo ? 'foo' : 'bar';

blade

@if($condition)
    Something
@endif

References

参考资料

references/spatie-laravel-php-guidelines.md

references/spatie-laravel-php-guidelines.md