PHP开发规范最佳实践

作为一个PHP程序员写代码不仅要能运行还要写得规范优雅可维护。一个好的开发规范能让代码更加易读易懂易维护也能提高团队协作的效率。

但是在实际开发中很多PHP程序员并不太注重开发规范写的代码比较随意不规范导致代码可读性差维护困难。特别是一些新手程序员写的代码更是混乱不堪。

今天就来分享一下PHP开发规范的最佳实践包括代码风格命名规范注释规范安全规范性能规范等希望能帮到大家。

1. 代码风格规范

1.1 缩进

缩进是代码风格最基本的要素。统一的缩进能让代码层次分明易读易懂。

PHP开发中推荐使用4个空格作为缩进而不是Tab。因为不同的编辑器对Tab的显示宽度不一样可能会导致代码对齐混乱。而空格在任何编辑器中显示都是一致，的。

现在很多编辑器和IDE都支持将Tab自动转换为空格建议开启这个功能。

1.2 行宽

代码的行宽建议不要超过80-120个字符。如果一行代码太长会导致阅读困难需要横向滚动才能看完整。

如果一行代码太长可以考虑换行或者拆分成多行。比如函数参数太多可以每个参数占一行。数组元素太多可以每个元素占一行。

1.3 大括号

大括号的使用有两种风格：Allman风格和K&R风格。

Allman风格是大括号另起一行：

if ($condition)
{
    // code
}

K&R风格是大括号跟在语句后面：

if ($condition) {
    // code
}

PHP开发中推荐使用K&R风格这也是PSR-2规范推荐的风格。K&R风格更紧凑能节省行数也是很多主流编程语言的通用风格。

1.4 空格

空格的使用也很重要。合理的空格能让代码更加易读易懂。

推荐在以下地方添加空格：

逗号后面：function foo($a, $b, $c)
运算符两边：$a = $b + $c，if ($a == $b)
控制结构关键字后面：if ($condition)，for ($i = 0; $i < 10; $i++)
函数参数列表中逗号后面：function foo($a, $b, $c)

不推荐在以下地方添加空格：

函数名和括号之间：function foo($a)，而不是，function foo ($a)
括号内部两侧：if ($condition)，而不是，if ( $condition )
数组下标括号内部两侧：$arr[0]，而不是，$arr[ 0 ]

2. 命名规范

2.1 变量命名

变量命名推荐使用小驼峰命名法即第一个单词小写后面的单词首字母大写。比如：$userName，$orderList，$isValid。

变量命名要有意义能表达变量的用途和含义。不要使用无意义的名字比如，$a，$b，$c，$data，$list，等除非是临时变量或者循环变量。

变量命名也不要太长一般不超过3-5个单词。如果变量名太长说明这个变量的职责可能不单一需要考虑拆分。

2.2 函数命名

函数命名推荐使用小驼峰命名法和变量命名一样。比如：getUserName()，createOrder()，isValid()。

函数命名要动宾结构能表达函数的功能和用途。比如，getUserName()，表示获取用户名；createOrder()，表示创建订单；isValid()，表示判断是否有效。

函数命名也要注意一致性。比如获取数据的函数都用，get，开头；设置数据的函数都用，set，开头；判断是否的函数都用，is，或，has，开头。

2.3 类命名

类命名推荐使用大驼峰命名法即每个单词首字母都大写。比如：User，UserService，OrderController。

类命名要有意义能表达类的职责和用途。比如，User，表示用户，类；UserService，表示用户服务，类；OrderController，表示订单控制器，类。

类命名也要注意后缀。比如控制器类都用，Controller，后缀；服务类都用，Service，后缀；模型类都用，Model，后缀；异常类都用，Exception，后缀。

2.4 常量命名

常量命名推荐使用全大写字母单词之间用下划线分隔。比如：MAXRETRYCOUNT，DEFAULTPAGESIZE，STATUS_ACTIVE。

常量命名要有意义能表达常量的含义和用途。比如，MAXRETRYCOUNT，表示最大重试次数；DEFAULTPAGESIZE，表示默认分页大小；STATUS_ACTIVE，表示激活状态。

3. 注释规范

3.1 文件注释

每个PHP文件开头都应该有文件注释说明文件的功能和用途。比如：

<?php
/**
 * 用户服务类
 *
 * 提供用户相关的业务逻辑处理
 *
 * @author John Doe <john@example.com>
 * @date 2016-01-06
 */

文件注释应该包括文件的功能描述作者日期等信息。如果文件比较复杂还可以包括修改记录等信息。

3.2 类注释

每个类都应该有类注释说明类的功能和用途。比如：

/**
 * 用户服务类
 *
 * 提供用户相关的业务逻辑处理，包括用户注册、登录、信息修改等
 */
class UserService
{
    // code
}

类注释应该包括类的功能描述主要职责等信息。如果类有重要的属性或者方法也可以在类注释中说明。

3.3 方法注释

每个方法都应该有方法注释说明方法的功能参数返回值，等。比如：

/**
 * 根据用户ID获取用户信息
 *
 * @param int $userId 用户ID
 * @return array|null 用户信息，不存在返回null
 * @throws \Exception 数据库查询失败时抛出
 */
public function getUserById($userId)
{
    // code
}

方法注释应该包括方法的功能描述参数说明返回值说明异常说明，等。参数说明要包括参数类型参数名参数含义。返回值说明要包括返回值类型和含义。异常说明要包括异常类型和抛出条件。

3.4 行内注释

对于复杂的代码逻辑应该添加行内注释说明代码的意图和逻辑。比如：

// 计算用户年龄，当前年份减去出生年份
$age = date('Y') - date('Y', strtotime($birthday));

行内注释要简洁明了说明代码做什么而不是怎么做。不要对显而易见的代码添加注释比如，$a = 1; // 把1赋值给a，这样的注释没有意义。

4. 安全规范

4.1 防止SQL注入

SQL注入是Web开发中最常见的安全漏洞之一。PHP开发中要特别注意防止SQL注入。

防止SQL注入的最佳实践是使用PDO预处理语句而不是拼接SQL语句。比如：

// 错误的做法：拼接SQL语句，容易导致SQL注入
$sql = "SELECT * FROM users WHERE id = " . $userId;
$stmt = $pdo->query($sql);

// 正确的做法：使用PDO预处理语句
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = :userId");
$stmt->execute(['userId' => $userId]);
$user = $stmt->fetch();

使用PDO预处理语句参数会被自动转义能有效防止SQL注入。而且预处理语句还能提高性能因为同一条SQL语句多次执行时只需要编译一次。

4.2 防止XSS攻击

XSS（跨站脚本攻击），也是Web开发中常见的安全漏洞。PHP开发中要注意防止XSS攻击。

防止XSS攻击的最佳实践是对用户输入进行过滤和转义然后再输出到页面。比如：

// 对用户输入进行HTML转义，防止XSS攻击
echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');

htmlspecialchars，函数能将特殊字符转换为HTML实体比如，<，转换为，<，>，转换为，>，"，转换为，"，'，转换为，'。这样即使用户输入了恶意的JavaScript代码也不会被浏览器执行。

另外也可以使用CSP（内容安全策略），来进一步防止XSS攻击。CSP能限制页面中能执行的脚本来源能有效防止XSS攻击。

4.3 防止CSRF攻击

CSRF（跨站请求伪造），也是Web开发中常见的安全漏洞。PHP开发中要注意防止CSRF攻击。

防止CSRF攻击的最佳实践是使用Token验证。在表单中添加一个隐藏的Token字段提交表单时验证Token是否正确。比如：

// 生成CSRF Token，存入Session
session_start();
if (empty($_SESSION['csrf_token'])) {
    $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
}

// 表单中添加隐藏的Token字段
echo '<input type="hidden" name="csrf_token" value="' . $_SESSION['csrf_token'] . '">';

// 提交表单时验证Token
if ($_POST['csrf_token'] !== $_SESSION['csrf_token']) {
    die('CSRF token validation failed');
}

另外也可以检查请求的Referer来防止CSRF攻击。但是Referer可能被篡改或者不可靠所以最好还是使用Token验证。

4.4 文件上传安全

文件上传是Web开发中常见的功能但是也是安全风险比较高的功能。PHP开发中要特别注意文件上传安全。

文件上传安全的最佳实践包括：

检查文件类型：不要只根据文件扩展名判断文件类型要检查文件的MIME类型或者文件内容。
限制文件大小：设置文件上传的最大大小避免用户上传过大的文件。
重命名文件：上传的文件要重命名不要使用用户提供的文件名避免路径遍历攻击。
存储位置：上传的文件不要存储在Web可访问的目录下或者存储在Web可访问的目录下但是禁止执行PHP等脚本。
文件权限：上传的文件要设置合适的权限不要设置为可执行权限。

5. 性能规范

5.1 减少数据库查询

数据库查询是Web应用性能瓶颈的常见来源。PHP开发中要注意减少数据库查询的次数。

减少数据库查询的方法包括：

使用缓存：对频繁查询的数据使用缓存比如Redis，Memcached等减少数据库查询。
批量查询：不要在循环中查询数据库要批量查询然后在PHP中处理。
只查询需要的字段：不要使用，SELECT *，只查询需要的字段减少数据传输，量。
使用索引：为常用的查询条件添加索引提高查询效率。

5.2 合理使用缓存

缓存是提升Web应用性能的重要手段。PHP开发中要合理使用缓存。

缓存的常见类型包括：

页面缓存：对整个页面进行缓存适合内容不经常变化的页面。
数据缓存：对数据库查询结果进行缓存适合频繁查询的数据。
查询缓存：对SQL查询结果进行缓存MySQL自带查询缓存但是MySQL 8.0已经移除了查询缓存。
OPcache：对PHP脚本编译结果进行缓存能大幅提升PHP应用的性能。

使用缓存时要注意缓存的更新策略避免缓存和数据库数据不一致。还要注意防止缓存雪崩缓存穿透缓存击穿等问题。

5.3 优化PHP代码

PHP代码本身的优化也很重要。一些常见的PHP代码优化技巧包括：

使用单引号代替双引号：单引号字符串比双引号字符串解析快因为双引号会解析变量和转义字符。
避免在循环中调用函数：在循环中调用函数会每次循环都调用一次影响性能。如果函数结果不变可以在循环外调用一次。
使用isset代替strlen：判断字符串是否为空时使用，isset($str[0])，比，strlen($str) > 0，快。
使用echo代替print：echo，比，print，快因为，echo，是语言结构不是函数。
关闭不必要的标签：PHP文件末尾的，?>，标签可以省略避免输出多余的空白字符。

这些微优化的效果可能有限但是积少成多也能提升一定的性能。但是不要过度追求微优化而牺牲代码的可读性和可维护性。

6. 其他最佳实践

6.1 使用版本控制

版本控制是团队协作和代码管理的重要工具。PHP开发中推荐使用Git进行版本控制。

使用版本控制能记录代码的修改历史方便回溯和对比。也能支持多人协作开发避免代码冲突。还能支持分支管理方便开发新功能和修复bug。

6.2 编写单元测试

单元测试是保证代码质量的重要手段。PHP开发中推荐使用PHPUnit编写单元测试。

单元测试能验证代码的正确性避免修改代码时引入新的bug。也能作为代码的文档说明代码的功能和用法。还能促进代码的重构因为有单元测试保护重构时不用担心引入新的bug。

6.3 代码审查

代码审查是保证代码质量的重要手段。PHP开发中推荐进行代码审查。

代码审查能发现代码中的问题比如bug安全漏洞性能问题不规范的代码，等。也能促进团队成员之间的知识分享和学习。还能统一团队的代码风格和开发规范。

6.4 遵循PSR规范

PSR（PHP Standards Recommendations），是PHP-FIG制定的PHP开发规范推荐PHP开发者遵循。

常见的PSR规范包括：

PSR-1：基础编码规范
PSR-2：代码风格规范
PSR-3：日志接口规范
PSR-4：自动加载规范
PSR-7：HTTP消息接口规范
PSR-11：容器接口规范
PSR-12：代码风格规范扩展版

遵循PSR规范能让代码更加规范统一也能提高代码的可移植性和互操作性。

写在最后

以上就是PHP开发规范的最佳实践。这些规范和实践都是在长期的开发中总结出来的能帮助我们写出更加规范优雅可维护的代码。

当然开发规范不是一成不变的也不是绝对的我们可以根据自己的项目和团队情况进行调整和定制。但是基本的原则和规范还是应该遵循，的。

写代码不仅是为了让机器运行更是为了让人阅读和维护。一个好的开发规范能让代码更加易读易懂易维护也能提高团队协作的效率。

希望大家都能注重开发规范写出更加规范优雅可维护的代码。

最后用一句话结尾：代码是写给人看的只是顺便能在机器上运行。 愿每一个PHP程序员都能写出让人看得懂的优雅代码。