php 开发规范

权威指南 · 实战案例 · 持续更新

⚡ PHP 开发规范体系总览

PHP 开发规范由 PHP Framework Interop Group(PHP Framework Interoperability Group,PHP框架互操作性小组)制定并维护,是一套**开源、中立、社区驱动**的编码标准推荐方案,统称为 PSR(PHP Standards Recommendations)。自2009年PSR-0发布以来,该组织持续推动PHP生态走向标准化与现代化,极大提升了跨框架、跨项目的代码互操作性与可维护性。

当前主流标准包括:PSR-1(基本代码规范)、PSR-2(编码风格规范,已弃用)、PSR-12(编码风格规范,PSR-2继任者)、PSR-4(自动加载规范)、PSR-7(HTTP消息接口)、PSR-11(容器接口)、PSR-16(简单缓存接口)、PSR-17(HTTP工厂接口)、PSR-18(HTTP客户端接口)等。它们并非强制性标准,但已被 Symfony、Laravel、Yii、CakePHP、ThinkPHP 等主流框架广泛采纳,成为现代 PHP 项目的“事实标准”。

为何要遵循规范?核心价值在于:

值得注意的是,PSR-2 已于2022年被正式废弃,由 PSR-12 取代。PSR-12 并非完全推翻 PSR-2,而是在保留核心风格原则(如缩进、换行、命名)基础上,更灵活地兼容现代PHP语法(如匿名函数、箭头函数、联合类型等),并明确支持 PSR-4 自动加载规范。主流编辑器(VS Code、PHPStorm)默认集成 PSR-12 检查规则,配置后可自动格式化代码。

本文将逐项解析主流 PSR 标准,结合真实项目场景、常见误区与最佳实践,帮助开发者构建规范、健壮、可扩展的 PHP 应用。

⚙️ PSR-1:基本代码规范

PSR-1 是 PHP 规范体系的基石,定义了最基础的语法与命名约定,确保文件级与类级代码的最小一致性。其核心要求如下:

〔1〕文件编码与结尾要求

  • 文件必须使用 UTF-8 无 BOM 编码;
  • 文件结尾必须省略 PHP 关闭标签 ?(即不以 ? 结尾),避免尾部意外空格/换行导致输出污染(尤其在重定向、Cookie 设置场景下易引发“headers already sent”错误);
  • 单文件仅定义单一职责:要么仅声明类/接口/ traits,要么仅执行逻辑(如入口文件),不得混用。

〔2〕命名空间与类命名

  • 命名空间声明后必须空一行;
  • 类名必须使用 PascalCase(大驼峰),如 UserRepository、PDOConnection;
  • 文件名应与类名严格对应,如 UserRepository.php 对应 class UserRepository;
  • 禁止使用 PHP 关键字作为类名(如 Class、Function);
  • 接口命名建议以 Interface 结尾(非强制),如 CacheInterface。

〔3〕方法与属性命名

  • 方法名必须使用 camelCase(小驼峰),如 getUserById、hasPermission;
  • 私有/受保护方法建议以下划线 _ 开头(如 _validateInput),但非强制;
  • 常量名必须全大写,单词间用下划线分隔,如 MAX_RETRY_COUNT、ENV_PROD;
  • 属性名(含静态)建议与方法命名风格一致(小驼峰),如 $userId、$config。

⚠️ 常见误区:在类中混合使用 snake_case 与 camelCase 命名属性(如 $user_id + $userId),导致代码风格混乱、可读性下降。应统一采用小驼峰。

〔4〕访问控制与文档注释

  • 所有类方法必须显式声明访问级别(public、protected、private),禁止省略;
  • 类、方法、属性应包含 PHPDoc 注释(符合 PHPDoc 标准),如:

class UserRepository
{
    public function getById(int $id): ?array
    {
        // 实现逻辑...
    }
}

⚙️ PSR-2:编码风格规范(已废弃,仅作参考)

PSR-2 曾是 PHP 社区最广泛采用的编码风格规范,但已于2022年正式废弃,由 PSR-12 接替。其核心要求包括:4空格缩进、行宽不超过80字符、方法/类声明格式等。尽管不再更新,但许多旧项目仍在使用,理解其结构有助于维护历史代码。

〔1〕基本格式要求

  • 每行不超过80字符,超过时应换行;
  • 缩进必须使用4个空格,禁止使用 Tab;
  • 每行末尾不得有尾随空格;
  • 每文件仅包含一个类定义(除命名空间声明外);
  • 类体与方法体必须使用新行起始,且用大括号包裹。

〔2〕类与方法声明示例

<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use Some\Other\Class;
class ExampleClass
{
    public function exampleMethod($param = '')
    {
        if ($param === '') {
            echo 'Empty';
        } else {
            echo 'Not empty';
        }
    }
}

ℹ️ 为何废弃?PSR-2 未适配 PHP7+ 新特性(如标量类型声明、返回类型、联合类型、匿名类、箭头函数),而 PSR-12 显著增强了对现代语法的支持,并允许更灵活的换行策略(如长参数列表的对齐)。

⚡ PSR-12:扩展编码风格规范(当前推荐)

PSR-12 是 PSR-2 的继任者,于2019年发布,全面兼容 PHP7+ 语法,并保留 PSR-2 的核心精神。其关键改进包括:

  • 行宽建议不超过120字符(非强制);
  • 允许使用缩进空格对齐参数/属性;
  • 明确支持标量类型声明(int、string等)、联合类型(int|string)、匿名类、箭头函数(fn());
  • 增强对长语句换行的指导(如链式调用、多参数函数)。

〔1〕类型声明格式

// ✅ 正确:类型与变量名之间有空格
public function process(string $data, int $limit = 10): array
{
    return [];
}
// ❌ 错误:类型与变量名无空格
public function process(string$data, int$limit = 10):array
{
    return [];
}

〔2〕箭头函数与匿名函数

// 箭头函数(PHP 7.4+)
$users = array_map(fn($u) => $u->getId(), $userList);
// 匿名类(PHP 7.0+)
$service = new class implements LoggerInterface {
    public function log($level, $message): void
    {
        error_log("[$level] $message");
    }
};

〔3〕长参数列表换行

当函数/方法参数过长时,应每行一个参数,并对齐缩进:

$logger->info(
    'User login attempt',
    [
        'user_id' => $userId,
        'ip' => $ip,
        'timestamp' => time(),
        'user_agent' => $_SERVER['HTTP_USER_AGENT'],
    ]
);

ℹ️ 实战建议:使用 PHP-CS-Fixer 工具自动格式化代码。配置文件 .php-cs-fixer.php 可指定规则集为 @PSR12,命令:php-cs-fixer fix src/ --rules=@PSR12。

⚡ PSR-4:自动加载规范

PSR-4 定义了如何通过命名空间与文件路径映射实现类的自动加载,是 Composer 依赖管理的核心基础。它解决了 PSR-0 的冗余(如要求命名空间与目录结构完全一致),允许更灵活的目录组织。

〔1〕核心规则

  • 命名空间根前缀(如 App\)必须映射到一个物理目录(如 src/);
  • 命名空间分隔符 \ 对应目录分隔符 /;
  • 类名必须与文件名完全一致(含大小写);
  • 文件扩展名为 .php;
  • 禁止在文件路径中使用下划线 _ 表示命名空间层级(如 App_Model_User 是 PSR-0 风格)。

〔2〕示例映射关系

命名空间 物理路径 类文件
App\Controller\UserController src/Controller/UserController.php <?php namespace App\Controller;
class UserController {}
Vendor\Package\Service\AuthService vendor/package/src/Service/AuthService.php <?php namespace Vendor\Package\Service;
class AuthService {}

〔3〕Composer 配置示例

在 composer.json 中配置自动加载规则:

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

执行 composer dump-autoload 后,即可通过 use App\Controller\UserController; 自动加载。

⚠️ 注意:PSR-4 要求命名空间根前缀后必须跟一个反斜杠(如 App\),若写成 App(无尾部反斜杠),Composer 将忽略该规则!

〔4〕常见问题排查

  • 问题:类未找到(Class not found)
    → 检查命名空间是否匹配文件路径;
  • 问题:大小写敏感错误(如 Linux 服务器)
    → 确保文件名大小写与类名完全一致;
  • 问题:Composer 未生成自动加载文件
    → 运行 composer dump-autoload -o(优化自动加载)。

⚡ PSR-7:HTTP 消息接口

PSR-7 定义了 HTTP 请求(Psr\Http\Message\RequestInterface)与响应(Psr\Http\Message\ResponseInterface)的接口规范,是现代 PHP Web 框架(如 Slim、Laminas、Symfony 5+)的基石。其核心设计原则是:**消息对象不可变(immutable)**——任何修改操作均返回新对象,而非原地修改。

〔1〕关键接口与方法

接口 核心方法 说明
RequestInterface getMethod(), getUri(), getHeader('Content-Type') 获取请求方法、URI、头部
ResponseInterface getStatusCode(), getHeaderLine('Set-Cookie') 获取状态码、头部
StreamInterface getContents(), write($data) 读写请求/响应体

〔2〕请求处理示例

// 创建请求(需依赖工厂接口 PSR-17)
$requestFactory = new RequestFactory();
$request = $requestFactory
    ->createRequest('POST', '/api/users')
    ->withHeader('Content-Type', 'application/json')
    ->withBody($stream); // 包含 JSON 数据的 Stream
// 读取请求
$method = $request->getMethod(); // 'POST'
$contentType = $request->getHeaderLine('Content-Type'); // 'application/json'
$body = json_decode($request->getBody()->getContents(), true); // ['name' => 'Alice']

〔3〕响应构建示例

$responseFactory = new ResponseFactory();
$response = $responseFactory
    ->createResponse(201, 'Created')
    ->withHeader('Content-Type', 'application/json')
    ->withBody($stream); // 包含 JSON 数据的 Stream
// 输出响应
echo $response->getStatusCode(); // 201
echo $response->getHeaderLine('Content-Type'); // 'application/json'
echo $response->getBody()->getContents(); // '{"id":123}'

ℹ️ 为何重要?PSR-7 统一了 HTTP 消息处理方式,使中间件(Middleware)可跨框架复用。例如:认证中间件可同时用于 Slim 与 Symfony 项目。

⚡ PSR-11:容器接口(服务容器)

PSR-11 定义了服务容器(Container)的标准接口,用于管理依赖注入(DI)。其核心接口为 Psr\Container\ContainerInterface,仅包含两个方法:get() 和 has(),极大简化了容器实现与集成。

〔1〕接口定义

interface ContainerInterface
{
    public function get($id);
    public function has($id);
}

〔2〕典型实现与使用

以 Symfony DependencyInjection 组件为例:

$container = new ContainerBuilder();
$container->register('logger', Logger::class);
$container->register('db', PDO::class, [
    'dsn' => 'mysql:host=localhost;dbname=test',
    'user' => 'root',
    'password' => '',
]);
$container->compile();
// 使用容器
$logger = $container->get('logger'); // 返回 Logger 实例
if ($container->has('db')) {
    $db = $container->get('db'); // 返回 PDO 实例
}

〔3〕与 PSR-17/18 协作

现代应用中,容器常用于注入 PSR-7/18 组件:

$container->register('http.client', CurlHttpClient::class);
$container->register('request.factory', ServerRequestFactory::class);
// 控制器中注入
public function __construct(private ContainerInterface $container) {}
public function index(): Response
{
    $client = $this->container->get('http.client');
    $request = $this->container->get('request.factory')
        ->createRequest('GET', 'https://api.example.com');
    $response = $client->sendRequest($request);
    // ...
}

⚠️ 注意:PSR-11 仅定义容器行为,不涉及容器构建方式(如注解、配置文件)。实际项目中需结合具体实现(如 Symfony、PHP-DI)。

⚡ PSR-16:简单缓存接口

PSR-16 提供了比 PSR-6 更轻量级的缓存接口(Psr\SimpleCache\CacheInterface),适用于简单缓存场景(如配置缓存、数据库结果缓存)。其设计原则是:**简洁、易用、无状态**。

〔1〕核心方法

方法 说明
get($key, $default = null) 获取缓存值,不存在则返回默认值
set($key, $value, $ttl = null) 设置缓存,$ttl 为过期时间(秒)
delete($key) 删除单个缓存项
clear() 清空所有缓存
getMultiple($keys, $default = null) 批量获取
setMultiple($values, $ttl = null) 批量设置

〔2〕使用示例

// 初始化缓存(以 Redis 为例)
$cache = new PredisCacheClient(new Predis\Client());
// 设置缓存(10分钟)
$cache->set('user_profile_123', $userData, 600);
// 获取缓存
$user = $cache->get('user_profile_123');
if ($user === null) {
    $user = $db->getUser(123);
    $cache->set('user_profile_123', $user, 600);
}
// 批量操作
$keys = ['user_1', 'user_2', 'user_3'];
$values = $cache->getMultiple($keys, []);
foreach ($values as $key => $value) {
    echo "Key: $key, Value: " . json_encode($value) . "\n";
}

〔3〕与 PSR-6 的区别

  • PSR-16:简单、直接、无对象包装,适合快速集成;
  • PSR-6:功能更丰富(标签、缓存项对象),但复杂度高;
  • 建议:简单场景用 PSR-16,复杂场景(如缓存标签、版本控制)用 PSR-6。

⚡ 实用工具与最佳实践

代码检查
自动格式化
静态分析

〔1〕PHP_CodeSniffer(PHPCS)

用于检测代码是否符合 PSR 标准,支持自定义规则集。

  • 安装:composer require --dev squizlabs/php_codesniffer
  • 运行:./vendor/bin/phpcs src/ --standard=PSR12
  • 输出:每行违规位置 + 错误描述

〔2〕PHP CS Fixer

自动修复代码风格问题,支持 PSR-12 规则集。

  • 安装:composer require --dev friendsofphp/php-cs-fixer
  • 运行:./vendor/bin/php-cs-fixer fix src/ --rules=@PSR12
  • 配置:.php-cs-fixer.php 可自定义规则

〔3〕PHPStan

高级静态分析工具,检测类型错误、未使用变量、死代码等。

  • 安装:composer require --dev phpstan/phpstan
  • 运行:./vendor/bin/phpstan analyse src/ --level=max
  • 优势:比 PHP_CodeSniffer 更深入,可发现运行时错误

〔4〕编辑器集成

  • VS Code:安装 PHP Intelephense + PHP CS Fixer 插件;
  • PHPStorm:内置 PSR 检查(Settings → Editor → Inspections → PHP → Code Style),可配置自动格式化;
  • 配置保存时自动格式化:settings.json 中添加:
    "editor.codeActionsOnSave": { "source.fixAll.phpcs": true }

⚡ 网友们还关心的 7 个高频问题

⑴ PSR-12 与 PSR-1/2/4 是否冲突?

不冲突!PSR-12 专注于编码风格(如缩进、换行),PSR-1 定义基本规范(命名、命名空间),PSR-4 定义自动加载。它们是分层的,共同构成完整规范体系。例如:一个 PSR-4 自动加载的类,其文件格式需符合 PSR-12,类定义需符合 PSR-1。

⑵ 旧项目如何迁移至 PSR-12?

分三步:① 备份代码;② 用 PHP-CS-Fixer 一键修复:php-cs-fixer fix . --rules=@PSR12;③ 修复因大小写敏感导致的类名问题(Linux 服务器)。建议在 CI/CD 中集成 PSR-12 检查,防止新代码偏离规范。

⑶ 命名空间前缀是否必须与目录结构对应?

PSR-4 允许灵活映射。例如:App\ 可对应 src/,但 App\Controller\ 不必严格对应 src/Controller/,可通过 Composer 配置任意映射:
"App\\Controller\\": ["src/Handlers/", "lib/Controllers/"]

⑷ PSR-7 请求体如何读取 JSON 数据?

PSR-7 的 getBody() 返回 StreamInterface,需手动解码:
$data = json_decode($request->getBody()->getContents(), true);
⚠️ 注意:若请求体为空,getContents() 返回空字符串,需加判断:
$body = $request->getBody()->getContents(); $data = $body ? json_decode($body, true) : [];

⑸ 缓存服务如何同时支持 Redis/Memcached?

使用 PSR-16 的实现(如 php-cache/redis-adapter、php-cache/memcached-adapter),统一接口即可切换后端:
$cache = new RedisCacheClient(new Predis\Client());
或
$cache = new MemcachedCacheClient(new Memcached());

⑹ PSR-11 容器与 DI 容器(如 Symfony)的关系?

PSR-11 是接口规范,Symfony DI 组件实现了该接口。可通过 $container->get(ContainerInterface::class) 获取容器本身,实现服务注入。现代框架(如 Symfony 5+)默认支持 PSR-11 容器。

⑺ 如何编写符合 PSR 的文档注释?

遵循 PHPDoc 标准:
• @param:参数类型+名称+描述;
• @return:返回类型;
• @throws:可能抛出的异常;
• @see:相关方法/类;
• @deprecated:标记废弃。
示例:

〔7〕持续演进:未来规范方向

  • PSR-20(安全规范):加密实践、输入验证;
  • PSR-21(枚举):PHP 8.1+ 原生枚举的扩展规范;
  • PSR-22(WebAssembly):PHP-Wasm 的互操作标准;
  • PHP 8.2+ 新特性:只读属性(readonly)、联合类型改进、nullsafe 运算符(?->)均需纳入规范考量。