為什麼需要命名規範?
統一風格降低認知負荷、減少合併衝突、利於靜態分析、新人上手快。現代 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 / Enum | PascalCase | `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,讓風格問題在提交前自動解決,代碼審查專注於邏輯與架構,才是高效團隊的標配。