PHP PSR规范实战指南

为什么需要PHP代码规范？

在团队开发中，统一的代码规范是项目长期可维护的基石。PHP-FIG（PHP Framework Interop Group）制定的PSR（PHP Standards Recommendations）系列规范已成为行业事实标准。本文将从PSR-1、PSR-4、PSR-12三个核心规范入手，通过实战案例带你掌握PHP代码规范化的精髓。

PSR-1：基础编码规范

PSR-1定义了PHP代码的基础规则，包括文件编码、命名约定等。核心要点如下：

文件必须使用<?php或<?=标签
文件必须使用UTF-8 without BOM编码
类名必须使用StudlyCaps（大驼峰）命名
常量必须全大写并用下划线分隔
方法名必须使用camelCase（小驼峰）命名

<?php
// 符合PSR-1的类定义
class UserController
{
    const MAX_LOGIN_ATTEMPTS = 5;

    public function getUserProfile($userId)
    {
        // 方法体
    }
}

PSR-4：自动加载规范

PSR-4定义了从文件路径自动加载类的标准，取代了旧的PSR-0。核心规则：命名空间前缀对应目录路径，类名对应文件名（.php后缀）。

// composer.json 配置示例
{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Models\\": "src/Models/"
        }
    }
}

// 对应的目录结构
src/
├── Controllers/
│   └── UserController.php  // namespace App\Controllers;
├── Models/
│   └── User.php            // namespace App\Models;
└── Services/
    └── AuthService.php     // namespace App\Services;

PSR-12：扩展编码风格

PSR-12是PSR-2的升级版，定义了更详细的代码风格规则。以下是一些关键实践：

1. 缩进与空格

// 正确：4个空格缩进，控制结构后加空格
if ($condition) {
    $result = doSomething();
} elseif ($otherCondition) {
    $result = doOther();
} else {
    $result = default();
}

// 错误：使用Tab或混合空格
if($condition){
    $result=doSomething();
}

2. 类型声明与返回值

// 正确：严格类型声明
function calculateTotal(array $items): float
{
    return array_sum($items);
}

// 错误：缺少类型声明
function calculateTotal($items)
{
    return array_sum($items);
}

3. 链式调用

// 正确：每个方法调用独立一行
$query->select('id', 'name')
    ->from('users')
    ->where('status', 'active')
    ->orderBy('created_at', 'DESC');

// 错误：所有调用挤在同一行
$query->select('id', 'name')->from('users')->where('status', 'active');

实战：构建符合PSR规范的项目

让我们通过一个实际项目来演示如何应用这些规范：

// src/Models/User.php
<?php

declare(strict_types=1);

namespace App\Models;

use App\Exceptions\ValidationException;

class User
{
    const TABLE_NAME = 'users';

    private int $id;
    private string $name;
    private string $email;

    public function __construct(int $id, string $name, string $email)
    {
        $this->id = $id;
        $this->name = $name;
        $this->email = $email;
    }

    public function validate(): bool
    {
        if (empty($this->name) || !filter_var($this->email, FILTER_VALIDATE_EMAIL)) {
            throw new ValidationException('Invalid user data');
        }
        return true;
    }

    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

// src/Services/UserService.php
<?php

declare(strict_types=1);

namespace App\Services;

use App\Models\User;
use App\Repositories\UserRepository;

class UserService
{
    private UserRepository $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    public function createUser(string $name, string $email): User
    {
        $user = new User(0, $name, $email);
        $user->validate();
        
        return $this->userRepository->save($user);
    }
}

工具与自动化

使用以下工具自动检查代码规范：

PHP_CodeSniffer：检测PSR-12违规
PHP-CS-Fixer：自动修复代码风格
PHPStan：静态分析类型安全

# 安装工具
composer require --dev squizlabs/php_codesniffer
composer require --dev friendsofphp/php-cs-fixer

# 检查代码
vendor/bin/phpcs --standard=PSR12 src/

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

总结

遵循PSR规范不仅能提升代码质量，还能降低团队沟通成本。建议在项目初期就引入代码规范检查工具，并集成到CI/CD流程中。记住：规范不是束缚，而是团队协作的加速器。