了解 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中文網其他相關文章！