PHP代码书写规范

# 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 大小写约定

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标准

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

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

结语

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

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

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