很多PHP开发者，尤其是初学者，不重视代码规范。觉得代码能跑就行，规范不规范无所谓。写代码随心所欲，命名随意，缩进混乱，注释没有，格式乱七八糟。

但这样的代码，可读性很差，维护起来非常痛苦。过一段时间，自己都看不懂自己写的代码了。如果是团队协作，别人看你的代码更是一头雾水，改你的代码简直是噩梦。

代码规范，是写出优雅可维护代码的基础。规范的代码，可读性好，易于理解，易于维护，易于协作。它能让代码看起来整洁、专业、优雅，也能减少很多低级错误。

PHP FIG（Framework Interoperability Group）组织制定了PSR（PHP Standards Recommendations）标准，旨在统一PHP的编码规范，提高代码的可维护性和可协作性。目前PSR标准已经被大多数主流PHP框架和项目采用，成为了PHP社区的事实标准。

今天分享PHP代码规范与PSR标准，帮你写出优雅、一致、可维护的PHP代码。

PSR标准概述

PSR是PHP FIG组织制定的PHP标准建议，主要包括：

  • PSR-1：基础编码规范（Basic Coding Standard）
  • PSR-2：编码风格规范（Coding Style Guide）——已被PSR-12取代
  • PSR-4：自动加载规范（Autoloader）
  • PSR-12：编码风格规范（Extended Coding Style Guide）——PSR-2的扩展和替代
  • PSR-3：日志接口（Logger Interface）
  • PSR-7：HTTP消息接口（HTTP Message Interface）
  • PSR-11：容器接口（Container Interface）
  • PSR-15：HTTP中间件（HTTP Handlers）
  • PSR-16：简单缓存接口（SimpleCache）
  • PSR-17：HTTP工厂接口（HTTP Factories）
  • PSR-18：HTTP客户端接口（HTTP Client）

今天主要讲和代码规范最相关的PSR-1、PSR-4、PSR-12。

PSR-1：基础编码规范

PSR-1规定了PHP代码的基础规范，确保代码的互操作性。

1. PHP标签

  • 必须使用<?php ?>或<?= ?>标签，不允许使用其他标签（如短标签<?）
  • 文件末尾的?>可以省略（推荐省略，避免输出多余空白）

2. 编码

  • PHP文件必须使用UTF-8无BOM编码
  • 不要在PHP文件中使用其他编码

3. 命名空间和类名

  • 命名空间和类名必须符合PSR-4自动加载规范
  • 类名必须使用大驼峰命名法（StudlyCaps/PascalCase）

4. 类常量、属性和方法

  • 类常量必须全部大写，用下划线分隔（UPPERSNAKECASE）
  • 属性名可以使用大驼峰（StudlyCaps）、小驼峰（camelCase）或下划线（snake_case），但要在一定范围内保持一致
  • 方法名必须使用小驼峰命名法（camelCase）

5. 副作用

  • 一个PHP文件应该要么定义新的声明（类、函数、常量等），要么产生副作用（输出、修改配置等），不应该两者都有
  • 推荐：每个文件只做一件事，要么定义，要么执行

PSR-4：自动加载规范

PSR-4规定了命名空间到文件路径的映射规则，用于自动加载类。

规则

  • 命名空间前缀（namespace prefix）对应一个基础目录
  • 命名空间前缀后的部分，对应文件的相对路径
  • 类名与文件名一致，.php为扩展名
  • 命名空间分隔符\对应目录分隔符/

示例

命名空间：App\Controllers\UserController
命名空间前缀：App\
基础目录：/var/www/app/
文件路径：/var/www/app/Controllers/UserController.php

目录结构示例

project/
├── app/
│   ├── Controllers/
│   │   ├── UserController.php    -> App\Controllers\UserController
│   │   └── PostController.php    -> App\Controllers\PostController
│   ├── Models/
│   │   ├── User.php               -> App\Models\User
│   │   └── Post.php               -> App\Models\Post
│   └── Services/
│       └── UserService.php        -> App\Services\UserService
├── config/
├── public/
└── vendor/

Composer自动加载

在composer.json中配置PSR-4自动加载：

{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Config\\": "config/"
        }
    }
}

然后运行composer dump-autoload生成自动加载文件。

PSR-12：编码风格规范

PSR-12是PSR-2的扩展和替代，规定了PHP代码的编码风格。

1. 缩进和行宽

  • 使用4个空格缩进，不使用Tab
  • 每行代码尽量不超过120字符（软限制）

2. 关键字和命名空间

  • PHP关键字（如if、for、function等）必须小写
  • namespace声明后必须有一个空行
  • use声明块后必须有一个空行
  • use必须按顺序：类、函数、常量，每类之间空一行

3. 类、属性和方法

  • 类的大括号换行写（Allman风格）
  • 方法的大括号换行写
  • 访问修饰符（public/protected/private）必须显式声明
  • 方法名后不要有空格，参数列表中逗号后有空格

4. 控制结构

  • 控制结构（if/for/foreach/while/switch等）关键字后有一个空格
  • 左括号后不要有空格，右括号前不要有空格
  • 右括号和左大括号之间有一个空格
  • 大括号同行写（K&R风格）

5. 运算符

  • 二元运算符（+、-、*、/、=、==、&&等）前后各有一个空格
  • 一元运算符（!、++、--等）前后不要有空格
  • 拼接运算符.前后各有一个空格

6. 字符串

  • 单引号和双引号都可以，但要保持一致
  • 字符串中的变量，简单变量直接写在双引号中，复杂变量用花括号包裹

7. 数组

  • 短数组语法[]优先于array()
  • 数组最后一个元素后可以加逗号（推荐，方便后续添加）

8. 闭包

  • 闭包声明时，function后有空格，use前后有空格
  • 闭包的大括号同行写

命名规范

好的命名，能让代码自文档化，不需要注释就能看懂。

类名

  • 大驼峰（PascalCase）
  • 使用名词，不使用动词
  • 不使用缩写（除非是广为人知的缩写，如HTTP、URL）

方法名

  • 小驼峰（camelCase）
  • 使用动词或动词短语
  • 布尔值方法用is、has、can、should开头

变量名

  • 小驼峰（camelCase）或下划线（snake_case），保持一致
  • 有意义，不要用$a、$b、$temp等无意义的名字
  • 布尔变量用is、has、can开头

常量名

  • 全大写，下划线分隔（UPPERSNAKECASE）

注释规范

注释是代码的重要组成部分，好的注释能让代码更易理解。

1. 文件注释

每个文件开头可以有文件级注释，说明文件的用途、作者、版本等。

2. 类注释

说明类的用途和功能。

3. 方法注释

说明方法的功能、参数、返回值、异常等，用@param、@return、@throws等标签。

4. 行内注释

  • 用//单行注释，不要用#
  • 注释要说明"为什么"，而不是"做什么"（代码本身就能说明做什么）
  • 不要写废话注释

5. TODO注释

用// TODO:标记待办事项，用// FIXME:标记需要修复的问题。

文件组织

良好的文件组织，能让项目结构清晰，易于维护。

目录结构

project/
├── app/                    # 应用代码
│   ├── Controllers/        # 控制器
│   ├── Models/             # 模型
│   ├── Services/           # 服务层
│   ├── Repositories/       # 数据仓库
│   ├── Middleware/         # 中间件
│   ├── Exceptions/         # 异常类
│   └── Helpers/            # 辅助函数
├── config/                 # 配置文件
├── public/                 # Web根目录
│   ├── index.php           # 入口文件
│   └── assets/             # 静态资源
├── resources/              # 资源文件
│   ├── views/              # 视图模板
│   └── lang/               # 语言文件
├── routes/                 # 路由定义
├── storage/                # 存储文件
│   ├── logs/               # 日志
│   ├── cache/              # 缓存
│   └── uploads/            # 上传文件
├── tests/                  # 测试代码
├── vendor/                 # 第三方库
├── composer.json
└── README.md

一个文件一个类

  • 每个PHP文件只定义一个类（除了辅助函数文件等特殊情况）
  • 文件名与类名一致
  • 类的命名空间与目录结构对应

入口文件简洁

入口文件（index.php）要尽量简洁，只做引导和初始化，不写业务逻辑。

设计原则

代码规范不只是格式，更重要的是设计思想。

1. DRY（Don't Repeat Yourself）

不要重复代码。重复的代码，意味着修改时要改多处，容易遗漏，产生bug。把重复的逻辑提取成函数或类。

2. KISS（Keep It Simple, Stupid）

保持简单。不要过度设计，不要为了"可能的需求"而写复杂的代码。简单的代码更容易理解、维护和调试。

3. SRP（Single Responsibility Principle）

单一职责原则。一个类或函数，只做一件事。如果一个类做了太多事情，就拆分成多个类。

4. 可读性优先

代码是写给人看的，不是写给机器看的。优先保证代码的可读性，即使稍微慢一点、长一点也没关系。可读性好的代码，更容易维护，bug更少。

5. 函数短小

函数要尽量短小，最好不超过20-30行。如果函数太长，说明它做了太多事情，应该拆分。

6. 参数不要太多

函数的参数尽量不要超过3-4个。如果参数太多，可以用数组或对象封装。

工具辅助

手动检查代码规范很麻烦，可以用工具自动检查和修复。

1. PHP_CodeSniffer（phpcs）

检查代码是否符合规范：

# 安装
composer require --dev squizlabs/php_codesniffer

# 检查
vendor/bin/phpcs --standard=PSR12 app/

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

2. PHP-CS-Fixer

自动修复代码规范：

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

# 修复
vendor/bin/php-cs-fixer fix app/ --rules=@PSR12

3. IDE配置

在IDE（如PhpStorm、VS Code）中配置代码规范：

  • 设置缩进为4空格
  • 启用PSR-12代码风格
  • 保存时自动格式化
  • 安装phpcs插件，实时检查

4. Git钩子

用Git钩子在提交前自动检查代码规范，不符合规范的不允许提交。

总结

代码规范是写出优雅可维护代码的基础。核心要点：

  1. 遵循PSR标准：PSR-1（基础规范）、PSR-4（自动加载）、PSR-12（编码风格）
  2. 好的命名：类名大驼峰、方法名小驼峰、常量全大写下划线、变量有意义
  3. 统一的代码风格：4空格缩进、大括号位置、空格使用、运算符空格
  4. 好的注释：文件/类/方法注释、行内注释说明为什么、不写废话
  5. 良好的文件组织：一个文件一个类、目录结构清晰、入口文件简洁
  6. 设计原则：DRY、KISS、SRP、可读性优先、函数短小
  7. 工具辅助：phpcs、php-cs-fixer、IDE配置、Git钩子

代码规范不是束缚，而是提升代码质量和开发效率的工具。从今天开始，遵循PSR标准，写出优雅、一致、可维护的PHP代码吧。