PHP 編程風格規範 (PSR-12 兼容版) 完整指南

統一代碼風格能顯著降低認知負荷、減少合併衝突、提升團隊協作效率。本文整理一套兼容 **PSR-12** 的 PHP 編程規範，涵蓋命名、縮排、空格、花括號、聲明嚴格類型、註釋、SQL 安全等核心規則，並提供 PHP_CodeSniffer 自動檢查配置。

一、基礎代碼風格 (PSR-12 核心)

1. 文件與編碼

• 所有 PHP 文件**必須**使用 ``。
• 編碼**必須**為 **UTF-8 無 BOM**。
• 行尾**必須**為 Unix 風格 `LF (\n)`。
• 文件**必須**以單個空行結尾。

2. 縮排與行長

• 縮排**必須**使用 **4 個空格**，**禁用 Tab**。
• 單行長度**建議**不超過 120 字符，**硬性限制** 100 字符 (IDE 設置 `right margin`)。
• 非邏輯分組的 `use` 聲明**必須**分組並按字母序排序。

3. 關鍵字與類型聲明

• PHP 關鍵字**必須**小寫：`if`、`else`、`foreach`、`function`、`class`、`public`、`private` 等。
• 類型聲明**必須**小寫：`int`、`string`、`array`、`bool`、`float`、`iterable`、`object`、`void`、`?string` (可空)。
• 嚴格模式**必須**在文件頂部聲明：`declare(strict_types=1);`。

二、命名規範

三、聲明結構

1. 類結構順序

<?php
declare(strict_types=1);

namespace App\Service;

use App\Entity\User;
use Psr\Log\LoggerInterface;

final class UserService
{
    // 1. 常量
    public const MAX_LOGIN_ATTEMPTS = 5;

    // 2. 屬性 (public → protected → private)
    private LoggerInterface $logger;
    private int $attempts = 0;

    // 3. 建構子
    public function __construct(LoggerInterface $logger) {
        $this->logger = $logger;
    }

    // 4. 公共方法
    public function register(string $email, string $password): User {
        // ...
    }

    // 5. 受保護方法
    protected function validateEmail(string $email): bool {
        // ...
    }

    // 6. 私有方法
    private function hashPassword(string $password): string {
        // ...
    }
}
?>

2. 方法/函數簽名

• 返回類型**必須**聲明 (含 `void`)。
• 參數列表**超過 120 字符**時，**每個參數獨佔一行**，結尾逗號對齊。
• 閉包 `fn` 箭頭函數簡短時可單行。

<?php
// 多行參數
public function create(
    string $name,
    string $email,
    ?string $phone = null,
    array $tags = [],
): UserEntity {
    // ...
}

// 閉包
$users = array_filter($all, fn(User $u) => $u->isActive());
?>

四、控制結構與運算符

1. if/else/elseif/switch

• 關鍵字後**必須**有一個空格：`if (`、`foreach (`、`while (`。
• 條件括號內**不加**空格：`if ($a === $b)`。
• 左花括號**同行**，前有空格：`) {`。
• 右花括號**獨佔一行**，與關鍵字對齊。
• `else`/`elseif` **同行** 接右花括號：`} else {`、`} elseif () {`。
• `switch` 的 `case` 縮排 4 空格，`break` 同層；非空 `case` **必須**有 `break`/`return`/`throw` 或註釋 `// no break`。

<?php
if ($a === $b) {
    foo();
} elseif ($a > $b) {
    bar();
} else {
    baz();
}

switch ($action) {
    case 'create':
        $this->create();
        break;
    case 'delete':
        $this->delete();
        // no break
    default:
        throw new InvalidArgumentException("Unknown action: $action");
}
?>

2. 運算符空格

• 二元運算符**前後各一空格**：`$a + $b`、`$a === $b`、`$a && $b`、`$a ?? $b`。
• 一元運算符**不加空格**：`$a++`、`--$b`、`!$c`、`~$d`。
• 三元運算符 `?:` **前後各一空格**：`$a = $b ? $c : $d;`。
• 解構賦值/陣列解包：`[$a, $b] = $arr;`、`[$x, $y] = fn() => [1,2];`。

五、陣列與字串

• 短語法 `[]` 取代 `array()`。
• 多行陣列**每個元素獨佔一行**，**尾隨逗號必須保留** (方便擴展、Git diff 乾淨)。
• 字串連接 `.` **前後各一空格**：`$s = 'a' . $b . 'c';`。
• 雙引號字串**必須**使用 `{}` 包裹變數：`"Hello {$user->name}"` (不允許 `"Hello $user->name"`)。
• Heredoc/Nowdoc 用於長字串/SQL，標識符大寫：`<<

<?php
$config = [
    'host' => '127.0.0.1',
    'port' => 3306,
    'options' => [
        'timeout' => 5,
    ],
];

$sql = <<

<?php
/**
 * 使用者註冊服務
 *
 * @package App\Service
 * @see UserRepository
 */
class UserService
{
    /**
     * 註冊新用戶
     *
     * @param string $email    郵箱 (唯一)
     * @param string $password 明文密碼 (長度 8-72)
     * @return UserEntity      已持久化的實體
     * @throws ValidationException 郵箱已存在或密碼不符合策略
     * @psalm-param non-empty-string $email
     * @psalm-param non-empty-string $password
     */
    public function register(string $email, string $password): UserEntity
    {
        // ...
    }
}
?>

<?php
$sql = << :since
ORDER BY u.`id` DESC
LIMIT :limit
SQL;

$stmt = $pdo->prepare($sql);
$stmt->execute([
    ':status' => 'active',
    ':since'  => '2024-01-01',
    ':limit'  => 20,
]);
?>

# 安裝
composer require --dev squizlabs/php_codesniffer friendsofphp/php-cs-fixer

# 專案根目錄 .phpcs.xml (PSR-12 規則集)


    
    
    */vendor/*
    */migrations/*


# .php-cs-fixer.php
in(__DIR__)
    ->exclude('vendor')
    ->exclude('var')
    ->name('*.php');

return (new PhpCsFixer\Config())
    ->setRules([
        '@PSR12' => true,
        'strict_param' => true,
        'phpdoc_align' => ['align' => 'vertical'],
        'array_syntax' => ['syntax' => 'short'],
        'no_unused_imports' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
    ])
    ->setFinder($finder);

# 執行檢查
vendor/bin/phpcs src/
vendor/bin/php-cs-fixer fix --dry-run --diff

# CI 整合 (GitHub Actions)
- name: Code Style
  run: vendor/bin/phpcs src/ && vendor/bin/php-cs-fixer fix --dry-run --diff

composer require --dev phpstan/phpstan vimeo/psalm
# phpstan.neon
parameters:
    level: 5
    paths: [src]
# psalm.xml

    
        
    

# package.json (需 Node 環境) 或用 PHP 版 pre-commit
# composer require --dev captainhook/captainhook
# captainhook.json
{
    "pre-commit": {
        "enabled": true,
        "actions": [
            {"action": "phpcs", "options": {"dir": "src"}},
            {"action": "phpstan", "options": {"configuration": "phpstan.neon"}}
        ]
    }
}