PHP代码规范怎么写_PSR标准与命名约定【说明】-php教程-PHP中文网

psr-4是php自动加载规范，通过命名空间与文件路径映射实现类自动加载，取代已废弃的psr-0；需严格对齐大小写和目录结构，如apphttpcontrollersusercontroller必须对应src/http/controllers/usercontroller.php。

php代码规范怎么写_psr标准与命名约定【说明】

PSR 不是强制标准，但不遵守它，你写的代码大概率会在 Composer 自动加载、团队协作、CI 检查、或接入主流组件（比如 monolog、guzzlehttp/psr7）时出问题。直接按最新有效规范落地，比“怎么写”更重要。

PSR-4 自动加载必须对齐命名空间和文件路径

类名 AppHttpControllersUserController 必须对应 src/Http/Controllers/UserController.php，不能是 src/controllers/UserController.php 或 app/Http/Controller/User.php。Composer 依赖这个映射关系做自动加载，错一个层级或大小写，Class not found 就会立刻报出来。

常见错误现象：

本地开发不报错（Windows/macOS 文件系统不区分大小写），上线 Linux 直接 Class 'AppHttpControllersusercontroller' not found
命名空间里用了下划线，比如 AppModelsUser_Info，但 PSR-4 不再把 _ 当路径分隔符（那是已废弃的 PSR-0 行为）
composer.json 中的 autoload 配置路径没加尾部斜杠，或没用 ** 匹配子目录

实操建议：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

在 composer.json 里用标准 PSR-4 块：

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

所有目录名、文件名、类名严格保持大小写一致；Linux 下 Usercontroller.php ≠ UserController.php
避免在类名中使用下划线，除非是常量（如 STATUS_PENDING）

PSR-12 是当前唯一该用的代码风格规范

PSR-2 已被官方标记为废弃，php-cs-fixer 和 phpcs 默认都不再支持它。现在只认 PSR12 —— 它兼容 PHP 7.4+ 的语法（比如属性类型、构造函数属性提升），也明确处理了 trait、enum、match 等新特性。

容易踩的坑：

方法声明的大括号必须换行：public function handle(): void {，不是 public function handle(): void {
if 后面必须有空格，但函数调用不能有：if ($user->isActive()) ✅，if( $user->isActive() ) ❌
单行 return 后面不能跟空行，但方法之间必须空一行

实操建议：

用 php-cs-fixer 配置 .php-cs-fixer.php：

$config = new PhpCsFixerConfig();
return $config->setRules([
    '@PSR12' => true,
    'declare_strict_types' => true,
])->setFinder(PhpCsFixerFinder::create()->in('src'));

别手动调格式，每次提交前跑 php-cs-fixer fix；IDE 插件（如 PHPStorm 的 “PHP CS Fixer”）可设保存时自动执行

命名约定不是风格偏好，而是接口契约的一部分

PSR-1 规定的命名不是“建议好看”，而是影响实际行为。比如 LoggerInterface::emergency() 方法名写成 emergence()，你就无法对接任何符合 PSR-3 的日志实现（monolog、slim/php-view 等）。

关键约束点：

类名必须 StudlyCaps（UserRepository，不是 user_repository 或 userRepository）
方法名必须 camelCase（findActiveUsers()，不是 FindActiveUsers() 或 find_active_users()）
常量全大写 + 下划线（MAX_RETRY_ATTEMPTS），且必须定义在 class 或 interface 内部，不能是全局 define()
变量名、参数名用 camelCase，但不要和内置函数冲突（比如别叫 array、string）

性能与兼容性影响：

命名不合规 → IDE 无法正确跳转、补全失效 → 开发效率断崖下跌
违反 PSR-1 的类，在静态分析工具（如 phpstan）中会被标为 “unknown class”，导致类型推导失败

PSR-7/PSR-18 接口名必须原样实现，不能缩写或改义

如果你自己写 HTTP 客户端，又想兼容 guzzlehttp/psr7 或 nyholm/psr7，那 RequestInterface、ResponseInterface、StreamInterface 这些类名、方法签名、甚至参数顺序都必须一字不差。少一个 getProtocolVersion()，或把 withStatus() 改成 setStatus()，就彻底破坏互操作性。

实操建议：

不要手写 PSR 接口实现，优先用现成包：composer require nyholm/psr7 + composer require php-http/curl-client
自定义中间件或装饰器时，确保类型提示用的是 PsrHttpMessageRequestInterface，而不是某个具体实现类
检查 vendor/composer/autoload_psr4.php 是否真加载了 PSR-7 相关命名空间（有时因 autoload 配置遗漏导致接口找不到）

PSR 规范真正的复杂点不在“记不住规则”，而在于：它是一套环环相扣的契约体系。改一个命名空间路径，可能让自动加载崩；漏一个接口方法，会让整个 HTTP 层无法替换；省掉一个空格，CI 流水线就卡住。这些不是“风格问题”，是运行时依赖。