php-best-practices

PHP 最佳实践

现代 PHP 8.x 模式、PSR 标准、类型系统最佳实践和 SOLID 原则。包含 51 条规则，助你编写整洁、易维护的 PHP 代码。

步骤 1：检测 PHP 版本

提供任何建议前，务必检查项目的 PHP 版本。 PHP 8.0–8.5 各版本的功能差异显著。切勿建议项目当前版本不支持的语法。

检查 composer.json 中要求的 PHP 版本：

{ "require": { "php": "^8.1" } }   // -> 8.1 rules and below
{ "require": { "php": "^8.3" } }   // -> 8.3 rules and below
{ "require": { "php": ">=8.4" } }  // -> 8.4 rules and below

同时检查运行时版本：

php -v   # e.g. PHP 8.3.12

各版本的功能支持情况

功能	版本	规则前缀
联合类型、match、空安全、命名参数、构造函数属性提升、属性	8.0+	type-, modern-
枚举、只读属性、交叉类型、首类可调用对象、never、纤程	8.1+	modern-
只读类、DNF 类型、独立的 true/false/null 类型	8.2+	modern-
类型化类常量、#[\Override]、json_validate()	8.3+	modern-
属性钩子、不对称可见性、不带括号的 new、#[\Deprecated]	8.4+	modern-
管道运算符 `	>`	8.5+

仅建议使用检测到的版本支持的功能。 如果用户询问升级或较新功能，请说明各版本新增了哪些功能。

适用场景

在以下情况下参考这些指南：

• 编写或审查 PHP 代码
• 实现类和接口
• 使用 PHP 8.x 的现代功能
• 确保类型安全
• 遵循 PSR 标准
• 应用设计模式

按优先级划分的规则类别

优先级	类别	影响	前缀	规则
1	类型系统	严重	type-	9
2	PHP 现代功能	严重	modern-	16
3	PSR 标准	高	psr-	6
4	SOLID 原则	高	solid-	5
5	错误处理	高	error-	5
6	性能	中	perf-	5
7	安全	严重	sec-	5

快速参考

1. 类型系统（严重）— 9 条规则

• type-strict-mode - 在每个文件中声明严格类型
• type-return-types - 始终声明返回类型
• type-parameter-types - 为所有参数指定类型
• type-property-types - 为类属性指定类型
• type-union-types - 有效使用联合类型
• type-intersection-types - 使用交叉类型
• type-nullable-types - 妥善处理可空类型
• type-void-never - 为适当的返回类型使用 void/never
• type-mixed-avoid - 尽可能避免使用 mixed 类型

2. PHP 现代功能（严重）— 16 条规则

8.0+：

• modern-constructor-promotion - 构造函数属性提升
• modern-match-expression - 优先使用 match，而非 switch
• modern-named-arguments - 使用命名参数以提高清晰度
• modern-nullsafe-operator - 空安全运算符（?->）
• modern-attributes - 使用属性提供元数据

8.1+：

• modern-enums - 使用枚举代替常量
• modern-enums-methods - 在枚举中使用方法和接口
• modern-readonly-properties - 使用只读属性保存不可变数据
• modern-first-class-callables - 首类可调用对象语法
• modern-arrow-functions - 箭头函数（7.4+，与 8.1 的功能搭配良好）

8.2+：

• modern-readonly-classes - 只读类

8.3+：

• modern-typed-constants - 类型化类常量（const string NAME = 'foo'）
• modern-override-attribute - 使用 #[\Override] 检查父类方法名是否拼写错误

8.4+：

• modern-property-hooks - 使用属性钩子替代 getter/setter
• modern-asymmetric-visibility - 使用 public private(set) 控制访问权限

8.5+：

• modern-pipe-operator - 使用管道运算符（|>）进行函数式链式调用

3. PSR 标准（高）— 6 条规则

• psr-4-autoloading - 遵循 PSR-4 自动加载标准
• psr-12-coding-style - 遵循 PSR-12 编码风格
• psr-naming-classes - 类命名约定
• psr-naming-methods - 方法命名约定
• psr-file-structure - 每个文件定义一个类
• psr-namespace-usage - 正确使用命名空间

4. SOLID 原则（高）——5 条规则

• solid-srp - 单一职责：只有一个变更理由
• solid-ocp - 开闭原则：通过扩展实现，而非修改
• solid-lsp - 里氏替换原则：子类型必须可替换
• solid-isp - 接口隔离原则：接口应小而专注
• solid-dip - 依赖倒置原则：依赖抽象

5. 错误处理（高）——5 条规则

• error-custom-exceptions - 为不同错误创建特定的异常
• error-exception-hierarchy - 将异常组织成有意义的层级结构
• error-try-catch-specific - 捕获特定异常，而非通用的 \Exception
• error-finally-cleanup - 使用 finally 确保资源得到清理
• error-never-suppress - 切勿使用 @ 错误抑制运算符

6. 性能（中）——5 条规则

• perf-avoid-globals - 避免使用全局变量，改用依赖注入
• perf-lazy-loading - 将开销较大的操作延迟到需要时执行
• perf-array-functions - 优先使用原生数组函数，而非手动循环
• perf-string-functions - 优先使用原生字符串函数，而非正则表达式
• perf-generators - 对大型数据集使用生成器

7. 安全（严重）——5 条规则

• sec-input-validation - 验证并清理所有外部输入
• sec-output-escaping - 根据上下文（HTML、JS、URL）对输出进行转义
• sec-password-hashing - 使用 password_hash/verify，切勿使用 MD5/SHA1
• sec-sql-prepared - 所有 SQL 查询都使用预处理语句
• sec-file-uploads - 验证文件类型、大小和名称；将文件存储在网站根目录之外

核心指南

如需详细示例和说明，请参阅规则文件：

• type-strict-mode.md - 严格类型声明
• modern-constructor-promotion.md - 构造函数属性提升
• modern-enums.md - 带方法的 PHP 8.1+ 枚举
• solid-srp.md - 单一职责原则

关键模式（速查）

<?php
declare(strict_types=1);

// 8.0+ Constructor promotion + readonly (8.1+)
class User
{
    public function __construct(
        public readonly string $id,
        private string $email,
    ) {}
}

// 8.1+ Enums with methods
enum Status: string
{
    case Active = 'active';
    case Inactive = 'inactive';

    public function label(): string
    {
        return match($this) {
            self::Active => 'Active',
            self::Inactive => 'Inactive',
        };
    }
}

// 8.0+ Match expression
$result = match($status) {
    'pending' => 'Waiting',
    'active' => 'Running',
    default => 'Unknown',
};

// 8.0+ Nullsafe operator
$country = $user?->getAddress()?->getCountry();

// 8.3+ Typed class constants + #[\Override]
class PaymentService extends BaseService
{
    public const string GATEWAY = 'stripe';

    #[\Override]
    public function process(): void { /* ... */ }
}

// 8.4+ Property hooks + asymmetric visibility
class Product
{
    public string $name { set => trim($value); }
    public private(set) float $price;
}

// 8.5+ Pipe operator
$result = $input
    |> trim(...)
    |> strtolower(...)
    |> htmlspecialchars(...);

输出格式

审计代码时，请按以下格式输出发现的问题：

file:line - [category] Description of issue

示例：

src/Services/UserService.php:15 - [type] Missing return type declaration
src/Models/Order.php:42 - [modern] Use match expression instead of switch
src/Controllers/ApiController.php:28 - [solid] Class has multiple responsibilities

使用方法

阅读各个规则文件，了解详细说明：

rules/modern-constructor-promotion.md
rules/type-strict-mode.md
rules/solid-srp.md