PHP PSR（PHP Standards Recommendations）介绍

news2025/3/22 16:14:45

PHP PSR（PHP Standards Recommendations）是 PHP 社区制定的一系列标准化规范，旨在统一 PHP 代码的编写方式、接口设计和开发实践，以提高代码的可读性、可维护性和互操作性。以下是核心 PSR 标准的解读和具体使用方法：

一、核心 PSR 标准概览

标准	主题	核心内容
PSR-1	基础编码规范	文件格式、类命名、方法命名、常量命名等基础规则
PSR-12	扩展编码风格	替代 PSR-2，详细规定代码缩进、括号位置、命名空间声明等格式要求
PSR-4	自动加载规范	定义类名与文件路径的映射规则，替代旧的 PSR-0
PSR-7	HTTP 消息接口	定义请求（Request）和响应（Response）的标准化接口
PSR-3	日志接口	日志记录器的通用接口设计
PSR-11	容器接口	依赖注入容器（DI Container）的标准化接口

二、具体使用指南

1. 编码规范（PSR-1 + PSR-12）

应用场景：统一团队代码风格
实现方法：

// ✅ 符合 PSR-1/PSR-12 的代码示例
<?php
declare(strict_types=1);

namespace App\Service;

use Psr\Log\LoggerInterface;

class UserService implements UserServiceInterface
{
    private const MAX_RETRY = 3;
    
    public function __construct(
        private LoggerInterface $logger
    ) {}
    
    public function getUserById(int $userId): ?User
    {
        try {
            // 业务逻辑
        } catch (Exception $e) {
            $this->logger->error($e->getMessage());
        }
        
        return null;
    }
}

工具支持：

PHP_CodeSniffer：自动检查代码规范

# 安装
composer require --dev squizlabs/php_codesniffer

# 检查 PSR-12 合规性
phpcs --standard=PSR12 src/

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

2. 自动加载（PSR-4）

应用场景：类文件的自动加载
配置方法：

// composer.json
{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

目录结构：

project/
├── src/
│   └── Service/UserService.php
├── vendor/
└── composer.json

类文件位置：src/Service/UserService.php → 命名空间 App\Service

3. HTTP 消息接口（PSR-7）

应用场景：框架无关的 HTTP 处理
实现示例：

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

class ApiController
{
    public function handleRequest(
        ServerRequestInterface $request,
        ResponseInterface $response
    ): ResponseInterface {
        $data = $request->getParsedBody();
        $response->getBody()->write(json_encode(['status' => 'success']));
        return $response->withHeader('Content-Type', 'application/json');
    }
}

常用实现库：

composer require guzzlehttp/psr7

4. 日志接口（PSR-3）

应用场景：标准化日志记录
代码示例：

use Psr\Log\LoggerInterface;

class OrderService
{
    public function __construct(
        private LoggerInterface $logger
    ) {}

    public function createOrder(array $data): void
    {
        try {
            // 创建订单逻辑
            $this->logger->info('Order created', ['order_id' => 123]);
        } catch (Exception $e) {
            $this->logger->error('Order creation failed', ['error' => $e->getMessage()]);
        }
    }
}

常用实现库：

composer require monolog/monolog

三、开发流程集成

1. 代码规范检查（CI/CD 集成）

# .gitlab-ci.yml 示例
code_style_check:
  stage: test
  script:
    - composer install
    - vendor/bin/phpcs --standard=PSR12 src/ tests/
  allow_failure: false

2. 自动加载优化

# 生成优化后的自动加载文件
composer dump-autoload -o

四、常见问题解决

问题1：类无法自动加载

解决方案：

检查 composer.json 的 psr-4 配置
运行 composer dump-autoload
确认类名与文件路径匹配

问题2：代码格式冲突

解决方案：

在项目中配置 .php-cs-fixer.php：

<?php
$config = new PhpCsFixer\Config();
return $config->setRules([
    '@PSR12' => true,
    'strict_param' => true,
    'array_syntax' => ['syntax' => 'short'],
]);