PHP ベストプラクティス

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

ステップ 1: PHP バージョンの検出

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

composer.json で必要な PHP バージョンを確認してください：

{ "require": { "php": "^8.1" } }   // -> 8.1 以下のルール
{ "require": { "php": "^8.3" } }   // -> 8.3 以下のルール
{ "require": { "php": ">=8.4" } }  // -> 8.4 以下のルール

また、実行時のバージョンも確認してください：

php -v   # 例：PHP 8.3.12

バージョン別の機能可用性

機能	バージョン	ルールプレフィックス
Union型、match、nullsafe、名前付き引数、コンストラクタプロモーション、属性	8.0+	type-、modern-
Enum、readonlyプロパティ、交差型、ファーストクラスコーラブル、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+	modern-

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

適用する場合

以下の場合にこのガイドラインを参照してください：

• 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 - Union型を効果的に使用
• 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 - 定数の代わりに Enum を使用
• modern-enums-methods - メソッドとインターフェースを持つ Enum
• modern-readonly-properties - 不変データのための readonly
• modern-first-class-callables - ファーストクラスコーラブル構文
• 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+ メソッド付き Enum
• solid-srp.md - 単一責任原則

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

<?php
declare(strict_types=1);

// 8.0+ コンストラクタプロモーション + readonly（8.1+）
class User
{
    public function __construct(
        public readonly string $id,
        private string $email,
    ) {}
}

// 8.1+ メソッド付き Enum
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 式
$result = match($status) {
    'pending' => 'Waiting',
    'active' => 'Running',
    default => 'Unknown',
};

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

// 8.3+ 型付きクラス定数 + #[\Override]
class PaymentService extends BaseService
{
    public const string GATEWAY = 'stripe';

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

// 8.4+ プロパティフック + 非対称可視性
class Product
{
    public string $name { set => trim($value); }
    public private(set) float $price;
}

// 8.5+ パイプ演算子
$result = $input
    |> trim(...)
    |> strtolower(...)
    |> htmlspecialchars(...);

出力形式

コードを監査する場合、結果を以下の形式で出力してください：

file:line - [category] Issue の説明

例：

src/Services/UserService.php:15 - [type] 戻り値の型宣言がありません
src/Models/Order.php:42 - [modern] switch の代わりに match 式を使用してください
src/Controllers/ApiController.php:28 - [solid] クラスが複数の責任を持っています

使用方法

詳細な説明については、個別のルールファイルを参照してください：

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