Spatie Laravel & PHP ガイドライン

概要

Spatie の Laravel と PHP ガイドラインを適用して、コードスタイルの一貫性と Laravel ネイティブな実装を保つ。

いつ有効化するか

• Laravel または PHP コーディング作業を行う場合は、ユーザーが Spatie を明示的に言及していなくても、このスキルを有効化する。
• Laravel/PHP コードの生成、編集、フォーマット、リファクタリング、レビュー、または整列を求められた場合、このスキルを有効化する。
• .php または .blade.php ファイル、ルート、コントローラー、モデル、設定、バリデーション、マイグレーション、またはテストを扱う場合、このスキルを有効化する。

スコープ

• 対象範囲: .php、.blade.php、Laravel の規約（ルート、コントローラー、設定、バリデーション、マイグレーション、テスト）。
• 対象外: JS/TS、CSS、インフラストラクチャ、データベーススキーマ設計、Laravel 以外のフレームワーク。

ワークフロー

1. アーティファクト（コントローラー、ルート、設定、モデル、Blade、テストなど）を特定する。
2. references/spatie-laravel-php-guidelines.md を読み、関連するセクションに焦点を当てる。
3. コアとなる Laravel の原則を最初に適用し、その次に PHP 標準、その次にセクション固有のルールを適用する。
4. ルールが既存のプロジェクトの規約と矛盾する場合は、Laravel の規約に従い、変更を一貫性のあるものにする。

コアルール（要約）

• Laravel の規約を最優先する。
• PSR-1、PSR-2、PSR-12 に従う。
• 型付きプロパティと明示的な戻り値の型（void を含む）を優先する。
• ?string のような短い nullable 構文を使用する。
• すべてのプロパティをプロモートできる場合は、コンストラクタプロパティプロモーション を使用する。
• 1 行につき 1 つのトレイトを使用し、use ステートメントを分ける。
• 早期リターンを優先し、可能であれば else を避ける。
• 制御構造には常に波括弧を使用する。
• 連結ではなく文字列補間を使用する。
• Happy path は最後に: エラー条件を最初に処理する。

すべきこと と してはいけないこと

すべきこと:

• ケバブケース URL、キャメルケースのルート名、キャメルケースのルートパラメーターを使用する。
• ルートにはタプル表記法 [Controller::class, 'method'] を使用する。
• コントローラーには複数形のリソース名を使用する（PostsController）。
• バリデーションルールには配列表記法を使用する。
• config() ヘルパーを使用し、設定ファイル外では env() を使用しない。
• サービスの設定は config/services.php に追加し、新しいファイルには追加しない。
• @lang の代わりに __() を翻訳に使用する。
• Enum の値には PascalCase を使用する。

してはいけないこと:

• 完全な型ヒントが既に存在する場合は、docblock を追加しない。
• Docblock で完全修飾クラス名を使用しない。
• デフォルトで final または readonly を使用しない。
• 早期リターンが機能する場合に else を使用しない。
• Blade 制御構造の後に空白を追加しない。
• マイグレーション内で down メソッドを記述しない。up メソッドのみを記述する。

例

// Happy path は最後で早期リターン
if (! $user) {
    return null;
}

if (! $user->isActive()) {
    return null;
}

// アクティブユーザーを処理...

// 短い三項演算子
$name = $isFoo ? 'foo' : 'bar';

// コンストラクタプロパティプロモーション
class MyClass {
    public function __construct(
        protected string $firstArgument,
        protected string $secondArgument,
    ) {}
}

@if($condition)
    Something
@endif

リファレンス

• references/spatie-laravel-php-guidelines.md