PHP代码规范：从PSR到团队落地

为什么需要代码规范？

在多人协作的PHP项目中，代码风格不一致会导致阅读困难、合并冲突频繁，甚至隐藏bug。代码规范不仅提升可读性，还能通过自动化工具提前发现潜在问题。PHP社区最广泛接受的规范是PSR（PHP Standard Recommendations），其中PSR-1和PSR-12是基础。

PSR-1：基础编码规范

PSR-1定义了最基本的规则：

文件必须使用<?php或<?=标签。
文件必须使用UTF-8 without BOM编码。
一个文件只定义一个类（或接口、trait），且与命名空间对应。
类名采用StudlyCaps（大驼峰），方法名采用camelCase（小驼峰），常量全大写加下划线。

<?php
namespace App\Models;

class UserProfile
{
    const MAX_AGE = 120;

    public function getDisplayName(): string
    {
        return $this->firstName . ' ' . $this->lastName;
    }
}

PSR-12：扩展编码风格

PSR-12在PSR-2基础上更新，兼容PHP 8+特性。关键点包括：

缩进使用4个空格，不用Tab。
大括号换行规则：类、方法、控制结构的大括号另起一行。
关键字（如if、else）后必须跟一个空格。
参数列表中的逗号前不能有空格，逗号后必须有一个空格。

<?php

namespace App\Services;

use App\Models\User;

class UserService
{
    public function create(array $data): User
    {
        if (empty($data['email'])) {
            throw new \InvalidArgumentException('Email is required');
        }

        $user = new User();
        $user->email = $data['email'];
        $user->name = $data['name'] ?? '';
        $user->save();

        return $user;
    }
}

自动化工具实战

1. PHP_CodeSniffer

安装：composer require --dev squizlabs/php_codesniffer

检查：./vendor/bin/phpcs --standard=PSR12 src/

自动修复：./vendor/bin/phpcbf --standard=PSR12 src/

2. PHP-CS-Fixer

安装：composer require --dev friendsofphp/php-cs-fixer

配置示例（.php-cs-fixer.dist.php）：

<?php

$finder = PhpCsFixer\Finder::create()
    ->in(__DIR__ . '/src')
    ->exclude('vendor');

return (new PhpCsFixer\Config())
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
        'no_unused_imports' => true,
    ])
    ->setFinder($finder);

运行：./vendor/bin/php-cs-fixer fix

团队落地最佳实践

统一规范文档：在项目README或CONTRIBUTING.md中明确引用PSR标准。
CI/CD集成：在GitHub Actions或GitLab CI中加入代码检查步骤。
编辑器配置：提供.editorconfig文件，自动处理缩进和编码。
代码审查：将规范检查作为PR合并的前置条件。

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

常见问题与陷阱

命名空间与目录不匹配：确保PSR-4自动加载配置正确。
过度自动化：不要盲目修改第三方库代码，使用--path-mode限定范围。
忽略注释规范：推荐使用PHPDoc，但保持简洁，避免冗余。

/**
 * 计算两个数的和
 *
 * @param int $a 第一个数
 * @param int $b 第二个数
 * @return int 和
 */
function add(int $a, int $b): int
{
    return $a + $b;
}

总结

代码规范不是束缚，而是团队协作的加速器。通过PSR标准+自动化工具，可以大幅减少代码审查中的风格争论，让开发者专注于业务逻辑。从今天开始，为你的项目配置PHP_CodeSniffer，并逐步统一团队规范吧！