⚡ php 代码规范总览
在现代软件工程实践中,php 代码规范已从“可选建议”演变为“团队协作基石”。它不仅关乎代码可读性,更直接影响系统稳定性、维护成本与团队协作效率。一个统一、清晰、可验证的编码规范体系,是高质量软件交付的前提。
本规范体系以PSR系列标准为基底,融合多年一线开发经验,覆盖从命名、结构、注释、异常处理到安全与性能的全生命周期维度,既符合国际通行标准,亦兼顾中文语境下的工程实践特性。
据2024年PHP官方开发者生态调研显示,采用统一编码规范的团队,其代码审查通过率提升47%,线上缺陷密度降低39%,新人上手周期缩短55%。这充分说明:规范不是束缚,而是赋能。
我们主张:规范应具象可执行,而非抽象空谈。因此,每项条款均配套可落地的示例、反例与自动化校验建议,确保规范从文档走向代码仓库。
为何必须坚持规范?三大核心价值
- 可维护性:他人(包括未来你自己)能在5分钟内理解一段代码逻辑,而非耗时1小时逆向推导。
- 协作效率:消除“个人风格”带来的认知摩擦,CI/CD流程更顺畅,Code Review聚焦业务逻辑而非格式争议。
- 安全基线:规范中嵌入安全实践(如输入过滤、输出编码),从源头阻断常见漏洞(XSS、SQL注入等)。
规范层级与适用范围
规范分为三级:
• 强制级(MUST):违反即构成严重缺陷,如变量命名非法字符、SQL拼接未参数化;
• 建议级(SHOULD):强烈推荐执行,如类名使用PascalCase、方法名用camelCase;
• 参考级(MAY):可选策略,如注释风格、空行规则,团队可自定义子集。
〈示例〉某团队将“强制级”接入ESLint+PHPStan+PHP-CS-Fixer构建自动校验流水线,实现代码提交即校验、不合规即阻断,上线后安全事件归零。
规范演进机制
规范非一成不变。建议建立版本化机制:
• 基于PSR版本(如PSR-12 v2.0)制定主干规范;
• 每季度 Review 一次,结合新技术(如PHP 8.2+混合类型、属性)更新细则;
• 重大变更需全员评审并配套迁移脚本(如rename工具、重构辅助脚本)。
⚙️ 命名规范
命名是代码的“第一语言”,好的命名让逻辑自解释,减少注释依赖。PHP社区普遍采用驼峰、下划线、帕斯卡等混合风格,本规范以PSR-1/PSR-12为基准,细化至变量、函数、类、常量、配置项等场景。
类与接口命名(PascalCase)
类名必须使用帕斯卡命名法(PascalCase),首字母大写,每个单词首字母大写,禁止下划线。接口名建议以“Interface”结尾(非强制),Trait以“Trait”结尾。
✓ 正确:
class UserService { ... }
interface PaymentGateway { ... }
trait CacheableTrait { ... }
✗ 错误:
class user_service { ... }
class User_Service { ... }
class UserGatewayService { ... } // 名称过长,应拆分职责
方法与函数命名(camelCase)
方法名、函数名使用驼峰命名法(camelCase),首字母小写,后续单词首字母大写。布尔型方法建议以is/has/can/shoud开头。
✓ 正确:
getUserById($id)
hasPermission($role)
canEdit($article)
shouldFlushCache($context)
✗ 错误:
GetUserById($id) // 首字母不应大写
get_user_by_id($id) // 下划线风格
user_get_by_id // 非动词开头
变量命名(camelCase)
变量名遵循驼峰风格,首字母小写,避免单字母(除循环计数器i/j/k)。命名应体现类型或语义,禁止拼音、缩写(除非公认)。
✓ 正确:
$userProfile
$totalAmount
$isValid
✗ 错误:
$usrlPrfl // 缩写不可读
$yongHuMing // 拼音
$a // 非循环场景
常量命名(UPPER_SNAKE_CASE)
类常量、全局常量使用全大写+下划线分隔。常量名应完整表达含义,避免缩写。
✓ 正确:
const MAX_RETRY_COUNT = 3
const DEFAULT_TIMEZONE = 'UTC'
✗ 错误:
const maxRetryCount = 3
const RETRY_COUNT = 3 // 常量名应体现“默认/最大”等语义
数据库与配置项命名
数据库表名用小写+下划线(如user_profile),字段名同理。配置项使用点分层级命名,如app.debug、cache.driver。
✓ 正确:
CREATE TABLE user_profile ( ... )
config('app.debug')
✗ 错误:
CREATE TABLE UserProfile ( ... )
config('app_debug') // 不符合点分层级逻辑
命名反模式警示
- 〈命名冗余〉
$userObject→$user即可(类型由上下文或IDE推断); - 〈语义模糊〉
$data、$info→ 应明确为$userData、$errorInfo; - 〈大小写混用〉
$user_id与$userId混用 → 统一风格,避免视觉干扰。
※ 注意:PHP 8.1+ 支持枚举(Enum),推荐用enum Status: string { case Active = 'active'; case Inactive = 'inactive'; }替代常量,提升类型安全与IDE提示能力。
〔结构规范〕
代码结构是逻辑的骨架。合理的缩进、空行、括号对齐与语句顺序,让代码具备“视觉流”,便于快速定位逻辑分支与数据流向。
缩进与空格规则
统一使用4个空格缩进(禁止Tab),操作符两侧、逗号后、括号内需空格分隔。闭合括号前不加空格。
✓ 正确:
if ($condition) {
doSomething();
}
✗ 错误:
if($condition){doSomething();}
语句分隔与空行
逻辑块之间添加空行,提升可读性。同一变量定义组内不空行,组间空一行。
✓ 正确:
$userId = (int)$input['id'];
$cacheKey = "user:{$userId}";
if ($cache->has($cacheKey)) {
return $cache->get($cacheKey);
}
$user = $repository->find($userId);
✗ 错误:
$userId = (int)$input['id'];$cacheKey = "user:{$userId}";if ($cache->has($cacheKey)) { return $cache->get($cacheKey); }$user = $repository->find($userId);
大括号风格(PSR-2)
类、方法、控制结构的大括号必须独占一行。闭合大括号后若接else/elseif,应与else同行。
✓ 正确:
class Controller {
public function index() {
if ($isValid) {
return $this->render('home');
} else {
return $this->redirect('/error');
}
}
}
✗ 错误:
class Controller {
public function index() {
if ($isValid) { return ... } else { ... }
}
}
类成员顺序规范
类内成员应按以下顺序排列:
1. 常量(const)
2. 属性(property)
3. 构造函数(__construct)
4. 公共方法(public)
5. 保护方法(protected)
6. 私有方法(private)
7. 魔术方法(__call、__get等)
✓ 正确类结构:
class UserService {
const STATUS_ACTIVE = 1;
private $repository;
public function __construct(UserRepository $repo) { ... }
public function login($email, $password) { ... }
protected function validatePassword($input, $hash) { ... }
private function logActivity($action) { ... }
}
返回类型与类型声明
PHP 7.0+ 强烈建议显式声明返回类型(return type)。参数类型必须声明。避免使用mixed(除非必要),优先用联合类型(PHP 8.0+)。
✓ 正确:
function sum(int $a, int $b): int { return $a + $b; }
function parseUser(array $data): ?User { ... }
function handleRequest(Request $req): Response|RedirectResponse { ... }
✗ 错误:
function sum($a, $b) { return $a + $b; } // 无类型
function findUser($id) { ... } // 返回类型不明
控制结构最佳实践
- 〈if-else〉避免深层嵌套(超过3层应提取函数);
- 〈switch〉每个case必须含break/default,防止fall-through;
- 〈三元运算符〉仅用于简单赋值,复杂逻辑用if-else;
- 〈短路逻辑〉合理利用&&、||简化判断,但避免过度嵌套。
✓ 正确:
$isValid = !empty($input) && is_string($input);
✗ 警告:
$result = $a ? ($b ? ($c ? process($a,$b,$c) : null) : null) : default(); // 嵌套过深
〈注释规范〉
注释不是代码的附属,而是逻辑的延伸。好的注释解释“为什么”,而非重复“是什么”。PHP社区主流使用PHPDoc(DocBlock)格式,配合IDE可生成API文档。
函数/方法注释模板
function getUserProfile(int $userId): ?array { ... }
类注释规范
类注释应说明职责、依赖与版本信息。避免空泛描述(如“用户类”),而应描述行为边界。
class UserService { ... }
行内注释原则
- 〈仅对非常规逻辑添加注释〉,如特殊算法、性能优化点;
- 〈禁止注释明显代码〉(如
// 自增1); - 〈用变量名自解释〉优于注释(
$retryAttempts优于$n = 3; // 重试次数); - 〈TODO/FIXME注释〉需标注具体任务与责任人,定期清理。
※ 警告:注释易过期!建议将关键逻辑写成单元测试,注释仅作补充说明。过期注释比无注释更危险——它传递错误信息。
注释与文档自动化
使用phpDocumentor工具可从PHPDoc生成HTML文档:
vendor/bin/phpdoc -d src -t docs
生成文档应纳入CI流程,每次发布同步更新API文档。
「错误处理」
错误处理是系统健壮性的最后一道防线。PHP 7+引入Throwable体系,统一异常与错误处理机制。规范处理错误,能避免信息泄露、数据不一致与服务崩溃。
异常抛出与捕获原则
- 〈自定义异常〉继承Exception,实现业务语义(如UserNotFoundException、PaymentFailedException);
- 〈避免空catch〉:至少记录日志或抛出新异常;
- 〈异常粒度〉:按业务域划分,而非按技术层(如DatabaseException vs UserServiceException);
- 〈异常链〉:保留原始异常信息(new CustomException("...", 0, $previous))。
✗ 错误:
try {
$user = $repo->find($id);
} catch (\Exception $e) {
// 什么也不做 —— 错误被静默吞没
}
✓ 正确:
try {
$user = $repo->find($id);
} catch (UserNotFoundException $e) {
logger()->warning("User not found: {$id}", ['trace' => $e->getTrace()]);
throw new NotFoundException("用户不存在", 404);
}
错误日志规范
使用PSR-3 LoggerInterface记录日志。错误级别必须匹配:
• error():服务不可用;
• critical():需立即处理(如支付失败);
• warning():异常但可恢复(如缓存失效);
• info():关键业务节点(如用户注册成功)。
logger()->error("支付失败", [
'order_id' => $orderId,
'reason' => $exception->getMessage(),
'user_id' => $userId
]);
错误信息对外披露
生产环境禁止输出详细错误信息(如SQL语句、堆栈)。统一返回友好提示:
return response()->json(['error' => '服务器内部错误'], 500);
⚠️ 安全警示:错误信息泄露可能导致攻击者获取数据库结构、文件路径等敏感信息,是OWASP Top 10常见问题。
事务与回滚规范
数据库操作必须显式使用事务:
1. 开启事务:beginTransaction()
2. 捕获异常后回滚:rollBack()
3. 成功则提交:commit()
✓ 正确:
try {
$db->beginTransaction();
$db->exec("INSERT INTO orders ...");
$db->exec("UPDATE inventory ...");
$db->commit();
} catch (\Exception $e) {
$db->rollBack();
throw $e;
}
【安全规范】
安全是编码的底线。90%的Web漏洞源于规范缺失(如XSS、SQL注入、CSRF)。本节聚焦PHP特有风险点,结合OWASP标准给出可执行方案。
输入验证(Validation)
所有外部输入(GET/POST/COOKIE/HEADER/FILES)必须验证:
• 类型:is_int()、filter_var($email, FILTER_VALIDATE_EMAIL);
• 范围:min/max、白名单(in_array);
• 长度:strlen()、mb_strlen()。
✗ 错误:
$sql = "SELECT * FROM users WHERE email = '{$_GET['email']}'";
✓ 正确:
$email = filter_input(INPUT_GET, 'email', FILTER_VALIDATE_EMAIL);
if (!$email) {
throw new BadRequestException("无效邮箱格式");
}
$stmt = $pdo->prepare("SELECT * FROM users WHERE email = ?");
$stmt->execute([$email]);
输出编码(Escaping)
根据输出场景选择编码方式:
• HTML:htmlspecialchars($str, ENT_QUOTES, 'UTF-8');
• JavaScript:json_encode()后转义;
• SQL:预处理语句(非拼接);
• URL:urlencode()。
✓ 正确(Blade模板自动转义):
<div>{{ $userInput }}</div>
✓ 正确(原生PHP):
echo htmlspecialchars($input, ENT_QUOTES, 'UTF-8');
CSRF防护
所有表单提交必须包含CSRF Token:
1. 生成Token:$_SESSION['csrf'] = bin2hex(random_bytes(32));
2. 表单隐藏域:;
3. 后端校验:if ($_POST['csrf'] !== $_SESSION['csrf']) throw ...
文件上传安全
严格校验上传文件:
• 类型:白名单(image/png, image/jpeg);
• 大小:限制max_file_size;
• 存储:文件名哈希化(md5(uniqid())),禁止原始文件名;
• 路径:上传目录禁止执行(.htaccess: php_flag engine off)。
⚠️ 案例:2023年某CMS漏洞因允许上传.php文件,导致全网网站被挂马。务必在服务器层限制执行权限!
密码存储规范
禁止明文/MD5/SHA1存储密码!必须使用:
• password_hash($password, PASSWORD_DEFAULT)
• password_verify($input, $hash)
• 强制密码策略(长度≥8、含大小写/数字/符号)
✓ 正确:
$hash = password_hash($password, PASSWORD_DEFAULT);
if (password_verify($input, $hash)) {
// 登录成功
}
▲ 性能优化
性能是用户体验的隐形指标。规范的代码结构、合理的数据访问模式、缓存策略,共同构成高性能系统基础。
数据库操作优化
- 〈预处理语句〉:避免SQL注入,提升执行效率;
- 〈索引优化〉:WHERE、JOIN、ORDER BY字段必须建索引;
- 〈N+1查询〉:用JOIN或批量预加载(Eloquent的with());
- 〈慢查询日志〉:开启并定期分析(slow_query_log)。
✗ 慢查询:
foreach ($orders as $order) {
$user = User::find($order->user_id); // N+1
}
✓ 优化:
$orders = Order::with('user')->get(); // 预加载
// 或
$orders = DB::table('orders')->join('users', 'orders.user_id', '=', 'users.id')->get();
缓存策略
三层缓存架构:
1. 应用缓存(OPcache):开启opcache.enable=1;
2. 数据缓存(Redis/Memcached):缓存热点数据(用户信息、配置项);
3. 页面缓存(HTTP Cache):设置Cache-Control头。
✓ 实践:
// Redis缓存用户资料
$cacheKey = "user:{$id}";
if (!$data = $redis->get($cacheKey)) {
$data = $db->fetchRow("SELECT * FROM users WHERE id = ?", [$id]);
$redis->setex($cacheKey, 3600, json_encode($data));
}
内存管理
- 〈对象复用〉:避免频繁new(如循环内);
- 〈 unset变量 〉:释放大数组/对象;
- 〈生成器(Generator)〉:处理大数据集时替代数组(yield)。
✓ 生成器示例:
function readLargeFile($path) {
$handle = fopen($path, 'r');
while (!feof($handle)) {
yield fgets($handle);
}
fclose($handle);
}
foreach (readLargeFile('big.log') as $line) {
// 内存恒定,不随文件增大而增长
}
代码级优化
- 〈单例模式慎用〉:全局状态导致测试困难;
- 〈延迟加载(Lazy Loading)〉:非必要不初始化依赖;
- 〈字符串拼接〉:多字符串用implode(),单次用“{}”(如"Hello {$name}");
- 〈函数内联〉:频繁调用的小函数可考虑内联(PHP 7.4+ JIT优化后收益减小)。
※ 警告:过早优化是万恶之源(Knuth)。先保证代码正确性,再用Xdebug+Blackfire分析热点,针对性优化。
『PSR标准详解』
PSR(PHP Standard Recommendation)是PHP-FIG制定的行业标准,当前主流版本为PSR-12(编码风格)与PSR-1/PSR-2(基础规范)。以下为核心要点:
PSR-1 基础编码规范
- 文件必须以
开始,或纯PHP代码无开始标签; - 命名空间与use声明后空一行;
- 类名必须PascalCase;
- 常量必须UPPER_SNAKE_CASE;
- 方法必须camelCase;
- 文件编码UTF-8无BOM。
PSR-2 编码风格规范
- 缩进:4空格;
- 行长度:不超过80字符(推荐120字符);
- 控制结构:空格、括号风格统一;
- 方法声明:可见性必须显式(public/protected/private)。
PSR-4 自动加载规范
核心规则:
• 类名 = 文件名(区分大小写);
• 命名空间 = 目录结构;
• autoload配置:
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
类:App\Service\UserService → 文件:src/Service/UserService.php
PSR-3 Logger接口
统一日志接口,支持8个级别:
emergency/alert/critical/error/warning/notice/info/debug
$logger->error("支付失败", [
'order_id' => 123,
'error' => $e->getMessage()
]);
PSR-7 HTTP消息接口
定义Request/Response对象,被Guzzle、Slim等广泛采用。关键方法:
• $request->getMethod() / $request->getUri()
• $response->getStatusCode() / $response->getBody()
✓ PSR-7请求处理:
function handleRequest(ServerRequestInterface $request): ResponseInterface {
$path = $request->getUri()->getPath();
if ($path === '/login') {
return new HtmlResponse($this->renderLogin());
}
return new JsonResponse(['error' => 'Not found'], 404);
}
※ 工具推荐
自动化是规范落地的关键。以下工具可集成至开发流程:
代码质量工具
| 工具 | 用途 | 命令示例 |
|---|---|---|
| PHP_CodeSniffer | 检查编码风格 | vendor/bin/phpcs --standard=PSR12 src/ |
| PHP-CS-Fixer | 自动修复风格问题 | vendor/bin/php-cs-fixer fix src/ |
| PHPStan | 静态分析(类型检查) | vendor/bin/phpstan analyse src/ |
| Psalm | 深度类型推断 | vendor/bin/psalm src/ |
开发工具链
- 〈IDE推荐〉:PHPStorm(内置PSR支持)、VS Code + PHP Intelephense;
- 〈Git Hooks〉:用husky+lint-staged在提交前自动格式化;
- 〈CI集成〉:在GitHub Actions中加入
phpcs、phpstan步骤。
.github/workflows/ci.yml 示例:
- name: Run PHPStan
run: vendor/bin/phpstan analyse src/ --level=max
文档生成工具
- phpDocumentor:生成API文档;
- Sami:Symfony官方文档生成器;
- DocBlockr:IDE插件,辅助编写PHPDoc。
〔常见问题〕
A:PSR-12是PSR-2的升级版,完全兼容并扩展。PSR-2已废弃,新项目应直接采用PSR-12。
A:建议逐步迁移。可用PHP-CS-Fixer生成迁移脚本:
php-cs-fixer fix --rules=@PSR12,并配合Git Diff逐文件审查。
A:分阶段处理:
1. 新代码强制规范;
2. 重构时顺手整改(Boy Scout Rule);
3. 静态分析工具标记问题区域,优先修复高危模块。
A:PSR是社区推荐标准,非强制。但主流框架(Laravel、Symfony)均严格遵守,违背PSR将导致生态兼容性下降。