php-best-practices

PHP ベストプラクティス

モダンな PHP 8.x のパターン、PSR 標準、型システムのベストプラクティス、SOLID 原則。クリーンで保守しやすい PHP コードを書くための 51 のルールが含まれています。

ステップ 1：PHP のバージョンを検出する

アドバイスをする前に、必ずプロジェクトの PHP バージョンを確認してください。 機能は 8.0 ～ 8.5 で大きく異なります。プロジェクトのバージョンに存在しない構文は、決して提案しないでください。

必要な PHP バージョンを composer.json で確認します。

{ "require": { "php": "^8.1" } }   // -> 8.1 rules and below
{ "require": { "php": "^8.3" } }   // -> 8.3 rules and below
{ "require": { "php": ">=8.4" } }  // -> 8.4 rules and below

実行環境のバージョンも確認します。

php -v   # e.g. PHP 8.3.12

バージョンごとの機能の利用可否

機能	バージョン	ルールの接頭辞
共用体型、match、nullsafe、名前付き引数、コンストラクターのプロパティ昇格、属性	8.0+	type-、modern-
列挙型、readonly プロパティ、交差型、ファーストクラス callable、never、ファイバー	8.1+	modern-
readonly クラス、DNF 型、true/false/null の単独型	8.2+	modern-
型付きクラス定数、#[\Override]、json_validate()	8.3+	modern-
プロパティフック、非対称可視性、#[\Deprecated]、括弧なしの new	8.4+	modern-
パイプ演算子 `	>`	8.5+

検出したバージョンで利用できる機能のみを提案してください。 アップグレードや新しい機能についてユーザーから質問された場合は、各バージョンで利用可能になる機能を説明してください。

適用する場面

以下の場合は、これらのガイドラインを参照してください。

• PHP コードの作成またはレビュー
• クラスとインターフェースの実装
• PHP 8.x のモダンな機能の使用
• 型安全性の確保
• PSR 標準への準拠
• デザインパターンの適用

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞	ルール数
1	型システム	重大	type-	9
2	モダンな PHP 機能	重大	modern-	16
3	PSR 標準	高	psr-	6
4	SOLID 原則	高	solid-	5
5	エラー処理	高	error-	5
6	パフォーマンス	中	perf-	5
7	セキュリティ	重大	sec-	5

クイックリファレンス

1. 型システム（重大）— 9 ルール

• type-strict-mode - すべてのファイルで厳密な型を宣言する
• type-return-types - 常に戻り値の型を宣言する
• type-parameter-types - すべてのパラメーターに型を指定する
• type-property-types - クラスプロパティに型を指定する
• type-union-types - 共用体型を効果的に使用する
• type-intersection-types - 交差型を使用する
• type-nullable-types - nullable 型を適切に扱う
• type-void-never - 適切な戻り値の型に void/never を使用する
• type-mixed-avoid - 可能な限り mixed 型を避ける

2. モダンな PHP 機能（重大）— 16 ルール

8.0+:

• modern-constructor-promotion - コンストラクターのプロパティ昇格
• modern-match-expression - switch より match を使用する
• modern-named-arguments - 明確さのために名前付き引数を使用する
• modern-nullsafe-operator - nullsafe 演算子（?->）
• modern-attributes - メタデータに属性を使用する

8.1+:

• modern-enums - 定数の代わりに列挙型を使用する
• modern-enums-methods - メソッドとインターフェースを備えた列挙型
• modern-readonly-properties - 不変データに readonly を使用する
• modern-first-class-callables - ファーストクラス callable 構文
• modern-arrow-functions - アロー関数（7.4+。8.1 の機能と相性が良い）

8.2+:

• modern-readonly-classes - readonly クラス

8.3+:

• modern-typed-constants - 型付きクラス定数（const string NAME = 'foo'）
• modern-override-attribute - 親メソッド名の誤記を検出する #[\Override]

8.4+:

• modern-property-hooks - ゲッター／セッターに代わるプロパティフック
• modern-asymmetric-visibility - アクセスを制御する public private(set)

8.5+:

• modern-pipe-operator - 関数型の連鎖に使うパイプ演算子（|>）

3. PSR 標準（高）— 6 ルール

• psr-4-autoloading - PSR-4 のオートローディングに従う
• psr-12-coding-style - PSR-12 のコーディングスタイルに従う
• psr-naming-classes - クラスの命名規則
• psr-naming-methods - メソッドの命名規則
• psr-file-structure - 1 ファイルにつき 1 クラスにする
• psr-namespace-usage - 名前空間を適切に使用する

4. SOLID 原則（高）— 5 つのルール

• solid-srp - 単一責任：変更する理由は 1 つだけにする
• solid-ocp - オープン／クローズド：変更ではなく拡張する
• solid-lsp - リスコフの置換原則：サブタイプは置換可能でなければならない
• solid-isp - インターフェース分離の原則：小さく、目的を絞ったインターフェースにする
• solid-dip - 依存性逆転の原則：抽象に依存する

5. エラー処理（高）— 5 つのルール

• error-custom-exceptions - エラーごとに固有の例外を作成する
• error-exception-hierarchy - 例外を意味のある階層に整理する
• error-try-catch-specific - 汎用的な \Exception ではなく、特定の例外を捕捉する
• error-finally-cleanup - リソースを確実にクリーンアップするために finally を使用する
• error-never-suppress - @ エラー抑制演算子は使用しない

6. パフォーマンス（中）— 5 つのルール

• perf-avoid-globals - グローバル変数を避け、依存性注入を使用する
• perf-lazy-loading - コストのかかる処理は必要になるまで実行しない
• perf-array-functions - 手動ループではなく、ネイティブの配列関数を使用する
• perf-string-functions - 正規表現ではなく、ネイティブの文字列関数を使用する
• perf-generators - 大規模なデータセットにはジェネレーターを使用する

7. セキュリティ（重大）— 5 つのルール

• sec-input-validation - すべての外部入力を検証し、サニタイズする
• sec-output-escaping - コンテキスト（HTML、JS、URL）に応じて出力をエスケープする
• sec-password-hashing - password_hash/verify を使用し、MD5/SHA1 は使用しない
• sec-sql-prepared - すべての SQL クエリでプリペアドステートメントを使用する
• sec-file-uploads - ファイルの種類、サイズ、名前を検証し、Web ルート外に保存する

必須ガイドライン

詳細な例と説明については、ルールファイルを参照してください。

• type-strict-mode.md - 厳密な型宣言
• modern-constructor-promotion.md - コンストラクターのプロパティ昇格
• modern-enums.md - メソッドを備えた PHP 8.1+ の列挙型
• solid-srp.md - 単一責任の原則

主なパターン（クイックリファレンス）

<?php
declare(strict_types=1);

// 8.0+ Constructor promotion + readonly (8.1+)
class User
{
    public function __construct(
        public readonly string $id,
        private string $email,
    ) {}
}

// 8.1+ Enums with methods
enum Status: string
{
    case Active = 'active';
    case Inactive = 'inactive';

    public function label(): string
    {
        return match($this) {
            self::Active => 'Active',
            self::Inactive => 'Inactive',
        };
    }
}

// 8.0+ Match expression
$result = match($status) {
    'pending' => 'Waiting',
    'active' => 'Running',
    default => 'Unknown',
};

// 8.0+ Nullsafe operator
$country = $user?->getAddress()?->getCountry();

// 8.3+ Typed class constants + #[\Override]
class PaymentService extends BaseService
{
    public const string GATEWAY = 'stripe';

    #[\Override]
    public function process(): void { /* ... */ }
}

// 8.4+ Property hooks + asymmetric visibility
class Product
{
    public string $name { set => trim($value); }
    public private(set) float $price;
}

// 8.5+ Pipe operator
$result = $input
    |> trim(...)
    |> strtolower(...)
    |> htmlspecialchars(...);

出力形式

コードを監査する際は、次の形式で指摘事項を出力してください。

file:line - [category] Description of issue

例：

src/Services/UserService.php:15 - [type] Missing return type declaration
src/Models/Order.php:42 - [modern] Use match expression instead of switch
src/Controllers/ApiController.php:28 - [solid] Class has multiple responsibilities

使用方法

詳しい説明については、各ルールファイルを参照してください。

rules/modern-constructor-promotion.md
rules/type-strict-mode.md
rules/solid-srp.md