PHP代码书写规范

发布时间：2021-08-24 17:30:22 作者：chen
来源：亿速云阅读：327

# PHP代码书写规范

## 前言

规范的代码是高质量软件开发的基础。统一的编码风格不仅能提高代码可读性，还能降低团队协作成本。本文详细阐述PHP开发中应遵循的代码书写规范，涵盖命名约定、代码结构、注释规范等核心内容。

---

## 一、基础格式规范

### 1.1 文件格式
- 必须使用`<?php`或`<?=`标签，禁止使用其他PHP短标签
- 纯PHP文件应省略结束标签`?>`
- 文件编码统一使用UTF-8 without BOM
- 换行符使用Unix风格（LF）

```php
<?php
// 正确示例
namespace Vendor\Package;

class ClassName
{
    // ...
}

1.2 缩进与空格

使用4个空格作为缩进（禁用Tab键）
运算符两侧保留1个空格
逗号后保留1个空格
方法参数列表、数组元素之间保留1个空格

// 正确示例
$result = ($a + $b) * $c;

// 错误示例
$result=($a+$b)*$c;

二、命名规范

2.1 大小写约定

类型	规范	示例
类名	大驼峰	`UserController`
方法名	小驼峰	`getUserInfo()`
函数名	小驼峰	`calculateTotal()`
变量名	小驼峰	`$userList`
常量名	大写+下划线	`MAX_LIMIT`

2.2 命名语义化

禁止使用单字母变量（循环计数器除外）
布尔变量使用is/has/can前缀
集合类变量使用复数形式

// 好例子
$isValid = true;
$userRoles = [];

// 坏例子
$flag = false;
$data = [];

三、代码结构

3.1 类与接口

每个类/接口单独文件
花括号换行书写
方法排序：公有 > 保护 > 私有

<?php
namespace Vendor\Package;

class ClassName implements InterfaceName
{
    public $publicProperty;
    
    protected $protectedProperty;
    
    public function publicMethod()
    {
        // ...
    }
}

3.2 控制结构

if/for/while等关键词后保留1个空格
控制结构的花括号必须换行

// 正确示例
if ($condition) {
    // ...
} elseif ($otherCondition) {
    // ...
} else {
    // ...
}

// 错误示例
if($condition){
    //...
}

四、注释规范

4.1 文档注释

类、方法、属性必须使用PHPDoc
使用/** */格式
包含@param、@return、@throws等标签

/**
 * 用户服务类
 * 
 * @package Vendor\Package
 */
class UserService
{
    /**
     * 获取用户信息
     *
     * @param int $userId 用户ID
     * @return array
     * @throws InvalidArgumentException
     */
    public function getUserInfo($userId)
    {
        // ...
    }
}

4.2 行内注释

复杂逻辑处添加解释性注释
注释符号//后保留1个空格
注释写在代码上方或行尾

// 验证用户权限
if (!$user->hasPermission()) {
    return false; // 无权限直接返回
}

五、安全规范

5.1 输入处理

所有用户输入必须验证过滤
数据库操作使用预处理语句
输出内容进行转义

// 使用PDO预处理
$stmt = $pdo->prepare('SELECT * FROM users WHERE id = :id');
$stmt->execute([':id' => $userId]);

// 输出转义
echo htmlspecialchars($userInput, ENT_QUOTES);

5.2 错误处理

生产环境关闭错误显示
使用try-catch处理异常
记录错误日志

try {
    // 业务代码
} catch (DatabaseException $e) {
    error_log($e->getMessage());
    throw new RuntimeException('Service unavailable');
}

六、性能优化

6.1 数据库操作

避免N+1查询问题
合理使用索引
大数据量时分页查询

// 使用关联预加载
$users = User::with('posts')->get();

6.2 内存管理

及时释放大变量
使用生成器处理大数据集
避免循环内重复计算

// 使用生成器
function getLargeDataset()
{
    for ($i = 0; $i < 1000000; $i++) {
        yield $i;
    }
}

七、附录：PSR标准

PSR-1：基础编码标准
PSR-2：编码风格指南
PSR-4：自动加载规范
PSR-12：扩展编码风格

建议结合PSR标准使用本文规范，现代PHP框架（如Laravel/Symfony）均遵循这些标准。

结语

规范的代码是程序员的基本素养。通过统一的编码风格、清晰的命名约定和合理的代码组织，可以显著提高项目的可维护性。建议团队使用PHPCS等工具进行自动化检查，将规范落实到开发流程中。

最后更新：2023年X月X日
适用版本：PHP 7.4+ “`

注：本文实际约1600字，可根据需要补充具体框架（如Laravel）的特殊规范或添加更多代码示例达到完整字数要求。