了解 PSR - PHP 编码风格指南

如果您使用 PHP 进行开发已有一段时间，您可能遇到过术语 PSR-12。它是 PHP 社区中最广泛接受的编码标准之一，旨在确保不同项目之间 PHP 代码库的一致性。无论您是单独工作还是作为团队的一员，遵循 PSR-12 都可以使您的代码更干净、更具可读性并且更易于维护。在本博客中，我们将详细介绍 PSR-12 是什么、它为何重要以及如何将其应用到您的项目中。

目录

1. 什么是 PSR-12？
2. 为什么 PSR-12 很重要？
3. PSR-12 的主要规则
   • 文件结构
   • 命名空间和使用声明
   • 类和方法
   • 控制结构
   • 评论和文档
4. 如何在 PHP 项目中应用 PSR-12
5. 帮助您遵循 PSR-12 的工具
6. 最后的想法

什么是 PSR-12？

PSR-12 是 PHP 编码风格指南，由 PHP-FIG（框架互操作性小组）开发。它建立在之前的 PSR-2 标准的基础上，提供了一组更新的规则，反映了现代 PHP 实践并提高了代码库之间的一致性。

将 PSR-12 视为编写干净、可读且可维护的 PHP 代码的蓝图。通过遵循 PSR-12，开发人员可以确保他们的代码遵循标准化结构，从而更轻松地与他人协作并开展开源项目。

为什么 PSR-12 很重要？

像 PSR-12 这样的编码标准不仅仅是对空格和制表符吹毛求疵。这就是它们重要的原因：

• 可读性：遵循标准样式的代码更容易阅读，特别是对于刚接触项目的开发人员。
• 协作：如果每个人都遵循相同的规则，那么合作就会变得更加顺利和高效。
• 可维护性：干净、一致的代码更容易调试、测试和随着时间的推移进行扩展。
• 互操作性：在开源项目或集成第三方库时，遵循通用标准可确保不同代码库之间的兼容性。

PSR-12 的主要规则

让我们深入了解 PSR-12 规定的一些关键规则。虽然有许多较小的指南，但以下是最引人注目的指南。

1. 文件结构

• 开始标签：PHP 文件必须使用
• 编码：文件必须以 UTF-8 编码，不带 BOM（字节顺序标记）。
• 行长度：行不应超过 120 个字符，但最好不超过 80 个字符。
• 空行：PHP 开始标签之后或结束标签之前不应有空行。此外，return 语句之前以及方法定义之间必须有一个空行。

2. 命名空间和使用声明

PSR-12 要求命名空间和使用声明遵循特定的顺序以提高清晰度：

• 命名空间声明：命名空间声明必须是 PHP 开始标记之后的第一行。命名空间后必须有一个空行。
• Use 声明：所有 use 声明必须在命名空间声明之后组合在一起，并用空行分隔。此外，最后一个 use 语句后必须有一个空行。

示例：

<?php namespace App\Controllers;

use App\Models\User;
use App\Repositories\UserRepository;

class UserController {
    // Class implementation
}

3. 类和方法

PSR-12 对如何声明类、属性和方法强制执行一些严格的规则：

• 类声明：class关键字后面必须跟一个空格，然后是类名。左大括号 { 必须与类声明放在同一行，右大括号 } 放在自己的行上。
• 属性：所有属性都必须声明可见性（公共、受保护、私有）。
• 方法：与类声明类似，function 关键字后面必须跟一个空格，然后是方法名称。必须为所有方法声明可见性。

class UserController {
    private $userRepository;

    public function __construct(UserRepository $userRepository) {
        $this->userRepository = $userRepository;
    }
}

4. 控制结构

if、for、switch 等控制结构必须遵循一定的规则：

• 结构：控制关键字和左括号之间必须有一个空格。必须始终使用大括号 {}，即使对于单行语句也是如此。
• 缩进：控制结构内的所有块都必须缩进一级（通常为四个空格）。

if ($user->isAdmin()) {
    echo "User is an admin";
} else {
    echo "User is not an admin";
}

5. 评论和文档

注释对于解释为什么代码的某些部分存在至关重要。 PSR-12 强调需要正确、清晰的评论。

• 块注释：使用 /* */ 进行多行注释，并在注释前放置一个空行。
• 单行注释：使用//进行内联注释，并确保注释有意义。

<?php namespace App\Controllers;

use App\Models\User;
use App\Repositories\UserRepository;

class UserController {
    // Class implementation
}

如何在 PHP 项目中应用 PSR-12

要在项目中遵循 PSR-12，您可以在编写代码时手动遵守指南，但确保合规性的最佳方法是使用自动化工具。

首先，熟悉这些一般做法：

• 使用一致的缩进：缩进需要四个空格。
• 限制行长度：尽量将行长度控制在 120 个字符以下，但为了更好的可读性，最好使用 80 个字符。
• 组织代码结构：遵循类声明、可见性和控制结构的规则。

帮助您遵循 PSR-12 的工具

手动确保您的代码遵循 PSR-12 可能非常耗时，但有一些工具可以帮助您自动化此过程。

1. PHP_CodeSniffer

确保 PHP 代码遵循 PSR-12 的最流行工具之一是 PHP_CodeSniffer。它会分析您的代码并指出您偏离标准的地方。

安装和使用它：

class UserController {
    private $userRepository;

    public function __construct(UserRepository $userRepository) {
        $this->userRepository = $userRepository;
    }
}

然后，针对您的代码运行它：

if ($user->isAdmin()) {
    echo "User is an admin";
} else {
    echo "User is not an admin";
}

2. PHP CS 修复程序

另一个有用的工具是 PHP CS Fixer。它不仅可以检测问题，还可以自动修复您的代码以符合 PSR-12。

// Fetch user from the repository
$user = $userRepository->find($id);

/*
 * If user is not found, throw an exception.
 * This helps in handling invalid user IDs.
 */
if (!$user) {
    throw new NotFoundException();
}

使用以下命令运行修复程序：

composer require "squizlabs/php_codesniffer=*"

3. PHPStorm

如果您使用 PHPStorm，您可以将其配置为遵循 PSR-12。前往设置 -> 编辑器 -> 代码风格 -> PHP 并将标准设置为 PSR-12。

最后的想法

在 PHP 项目中遵循 PSR-12 不仅仅是遵守任意规则。它是为了让你的代码更干净、更易读、更容易维护——无论你是单独工作还是与团队一起工作。通过遵循 PSR-12，您不仅为自己编写代码，而且为整个 PHP 社区编写代码。

采用此标准是朝着编写专业、一致且可维护的 PHP 代码迈出的一步。使用提到的工具使过程变得更容易，并观察您的项目变得多么干净和有组织！

编码愉快！

以上是了解 PSR - PHP 编码风格指南的详细内容。更多信息请关注PHP中文网其他相关文章！