萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 程式碼命名規範與風格指南:PSR-12、PSR-4 與團隊協作最佳實踐

為什麼需要命名規範?

統一風格降低認知負荷、減少合併衝突、利於靜態分析、新人上手快。現代 PHP 遵循 **PSR-12 (Extended Coding Style)** 為基準,結合 **PSR-4 (Autoloading)** 目錄結構。

檔案與目錄命名

類型規範範例
PHP 類別檔案`PascalCase.php`,對應類別名`UserService.php`、`OrderController.php`
介面`PascalCase.php`,可選 `Interface` 後綴`LoggerInterface.php`、`Cacheable.php`
Trait`PascalCase.php`,`Trait` 後綴`LoggableTrait.php`
Enum (PHP 8.1+)`PascalCase.php``Status.php`
一般腳本/設定`snake_case.php``bootstrap.php`、`routes.php`、`config.php`
目錄`PascalCase` (PSR-4 命名空間對應)`src/Service/`、`app/Http/Controllers/`

類別、介面、Trait 定義

<?php
declare(strict_types=1);

namespace App\Service;

use App\Contract\LoggerInterface;
use Psr\Log\LoggerInterface as PsrLogger;

final class UserService implements LoggerInterface
{
    // 屬性:camelCase,private 預設,必要時 protected
    private PsrLogger $logger;
    private string $defaultLocale = 'zh_Hant';

    // 建構子:依賴注入
    public function __construct(PsrLogger $logger, string $defaultLocale = 'zh_Hant')
    {
        $this->logger = $logger;
        $this->defaultLocale = $defaultLocale;
    }

    // 公開方法:camelCase,動詞開頭
    public function register(array $data): User
    {
        $user = $this->createUser($data);
        $this->logRegistration($user);
        return $user;
    }

    // 私有方法:底線開頭 + camelCase
    private function createUser(array $data): User
    {
        // ...
    }

    private function logRegistration(User $user): void
    {
        $this->logger->info('User registered', ['id' => $user->id]);
    }
}

命名慣例速查表

元素慣例範例備註
類別 / 介面 / Trait / EnumPascalCase`UserService`, `LoggableTrait`名詞、單數
方法 / 函式camelCase`getUserById()`, `calculateTotal()`動詞開頭
私有/保護方法_camelCase`_parseResponse()`, `_validateInput()`慣例非強制,PSR-12 不強制底線
屬性 (公開/保護/私有)camelCase`$userName`, `$_cache`私有可加底線區分
常數 (類別/全域)UPPER_SNAKE_CASE`MAX_RETRY`, `DEFAULT_LOCALE``const` 或 `define()`
變數 (區域/參數)camelCase`$userId`, `$requestData`
資料庫表名snake_case 複數`users`, `order_items`Laravel 慣例
資料庫欄位snake_case`created_at`, `user_id`
路由名稱kebab-case / dot 分隔`users.index`, `admin.users.create`
視圖檔案kebab-case.blade.php`user-profile.blade.php`
環境變數UPPER_SNAKE_CASE`DB_HOST`, `APP_DEBUG`

縮排與格式化 (PSR-12 核心)

  • **縮排**:4 個空格 (非 Tab),編輯器設定 `Insert Spaces`
  • **行長度**:軟性 80-100 字元,硬性 120 字元
  • **控制結構**:關鍵字後一空格、左大括號同行、右大括號獨立行
<?php
if ($condition1 && $condition2) {
    action1();
} elseif ($condition3) {
    action2();
} else {
    defaultAction();
}

// 長條件換行
if (
    $condition1
    && $condition2
    && $condition3
) {
    action();
}

// Switch
switch ($expr) {
    case 0:
        echo 'Zero';
        break;
    default:
        echo 'Other';
        break;
}

函式呼叫與參數

<?php
// 短呼叫單行
$result = foo($arg1, $arg2);

// 長呼叫換行:參數各佔一行,結尾逗號 (PHP 7.3+)
$result = veryLongFunctionName(
    $argument1,
    $argument2,
    $argument3,
);

// 多行參數對齊 (可選)
$short       = foo($bar);
$longerName  = foo($baz);
$veryLongVar = foo($qux);

陣列定義風格

<?php
// 短語法 (PHP 5.4+),尾端逗號 (方便 Git diff)
$config = [
    'driver'   => 'mysql',
    'host'     => '127.0.0.1',
    'port'     => 3306,
    'database' => 'app',
];

// 多行長鍵值對齊 (可選)
$map = [
    'short'           => 'value',
    'very_long_key'   => 'value',
    'another_key'     => 'value',
];

註解標準:PHPDoc

<?php
/**
 * 計算訂單總金額 (含稅、折扣、運費)
 *
 * @param Order $order 訂單實體
 * @param float $discountRate 折扣率 0.0-1.0
 * @return float 總金額 (元)
 * @throws InsufficientStockException 庫存不足
 */
function calculateOrderTotal(Order $order, float $discountRate = 0.0): float
{
    // ...
}

檔案包含策略

  • **永遠使用 `require_once` / `include_once`** (或 Composer 自動載入)
  • 類別檔案**絕不**手動 `require`,交給 PSR-4 自動載入器
  • 設定檔、引導檔可用 `require_once __DIR__ . '/config.php'`

工具自動化:讓規範落地

工具用途指令範例
PHP-CS-Fixer自動修正代碼風格 (PSR-12+)`vendor/bin/php-cs-fixer fix src --rules=@PSR12`
Pint (Laravel)零配置風格修正`vendor/bin/pint`
PHPStan靜態分析型別、邏輯錯誤`vendor/bin/phpstan analyse src --level=5`
Psalm深度靜態分析`vendor/bin/psalm --show-info=false`
PHP_CodeSniffer檢查風格違規 (不自動修)`vendor/bin/phpcs --standard=PSR12 src`

Git Hooks 整合 (Husky / pre-commit)

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: php-cs-fixer
        name: PHP CS Fixer
        entry: vendor/bin/php-cs-fixer fix --diff --dry-run
        language: system
        types: [php]
      - id: phpstan
        name: PHPStan
        entry: vendor/bin/phpstan analyse --no-progress
        language: system
        types: [php]

結語

命名規範不是束縛,而是團隊溝通的共同語言。採用 PSR-12/PSR-4 為基準,搭配自動化工具 (Pint + PHPStan) 融入 CI/CD,讓風格問題在提交前自動解決,代碼審查專注於邏輯與架構,才是高效團隊的標配。

copyright © 萬盛學電腦網 all rights reserved