php-laravel

PHP と Laravel の開発

フレームワークレベルの PHP に限定します。php-src の内部処理やネイティブ PHP 拡張の開発は PHP ではなく C です。これらは ia-c-systems スキルの対象であり、Zend API の規約（gen_stub の arginfo、リクエストスコープのアロケーター、カスタムオブジェクトハンドラー、.phpt）も含まれます。

作業ルール

• シンプルな CRUD はシンプルなままにします。モデルをまたぐオーケストレーションの抽出は、具体的な用途がある場合に限ります。
• リクエスト境界で検証と認可を行います。明示的なリソースを通じてシリアライズし、サードパーティのレスポンスも検証します。
• デプロイ済みのマイグレーション履歴、キューペイロードとの互換性、並行書き込みを維持します。
• 変更によって影響を受ける場合は、実際のエントリーポイントを通じて、キャッシュのコンパイル、キューの実行、HTTP の動作を検証します。

コードスタイル

• すべてのファイルに declare(strict_types=1)
• 成功パスは最後にします。ガードとエラーを先に処理し、最後に成功処理を行います。早期リターンを使い、else は使いません。
• コメントでは「何を」ではなく「なぜ」を説明します。テストにはコメントを付けません。「何を」説明するコメントが必要なら、名前を変更するか構造を見直します。
• 1 文字の変数名は使いません。$e ではなく $exception、$r ではなく $request を使います。
• string|null ではなく ?string を使います。常に void を指定します。FQN をインラインで記述せず、クラス名をインポートします。
• パラメーターを ?T に広げる場合、同じ値を渡すすべての呼び出し箇所を監査する必要があります。隣接する呼び出し先では引き続き string が宣言されているため、declare(strict_types=1) がなくても、そこで null を渡すと TypeError が発生します。弱制型モードでも null はスカラー型に型変換されないためです。厳密性は、呼び出し先のファイルではなく、呼び出しを記述したファイルによって決まります。仕組みの詳細は common-pitfalls.md を参照してください。
• カスタムルールクラスを使いやすくするため、検証には配列記法 ['required', 'email'] を使います。
• PHPStan レベル 8 以上（phpstan analyse --level=8）を使います。新しいプロジェクトではレベル 9 を目指します。ジェネリックなコレクション型には @phpstan-type / @phpstan-param を使います。反復可能な値の型指定漏れのチェックはレベル 6（およびそれ以上のすべてのレベル）で適用されるため、レベル 8 以上のプロジェクトでは必ず対応が必要です。すべての反復可能型にジェネリック形式（@return Collection<int, User>、@param array<int, MyObject>）を使い、固定キーを返す場合は配列シェイプ記法 array{first: SomeClass, second: SomeClass} を使います。Collection または array だけではこのチェックをクリアできません。

規律

• まずシンプルさを重視します。すべての変更を可能な限りシンプルにし、コードへの影響を最小限に抑えます。
• 必要な箇所だけを変更します。無関係な変更は加えません。
• その場しのぎの回避策は使いません。修正が不適切に感じられる場合は立ち止まり、適切な解決策を実装します。
• 新しい抽象化を導入するには、3 か所以上での使用が必要です。それ未満の場合はインラインで記述します。
• 空の catch ブロックは禁止です。ログを記録するか再スローし、例外を握りつぶしてはいけません。
• 完了を宣言する前に検証します。./vendor/bin/phpstan analyse --level=8 && ./vendor/bin/phpunit を実行し、警告がないことを確認します。
• 最後だけでなく、各段階でチェックポイントを設けます。マイグレーション後に migrate:status、ルーティング変更後に route:list --path=<prefix>、ジョブ追加後に queue:work --once、PR 前に pint --test を実行します。各チェックで、変更が小さいうちにそれぞれの種類の失敗を検出できます。

参考資料

• laravel-ecosystem.md：通知、タスクスケジューリング、カスタムキャスト
• testing.md：PHPUnit の基本、データプロバイダー、テストの実行
• feature-testing.md：認証、検証、API、コンソール、DB アサーション
• mocking-and-faking.md：ファサードのフェイク、アクションのモック、Mockery
• factories.md：状態、リレーションシップ、シーケンス、afterCreating フック
• production-performance.md：OPcache、JIT、プリロード、デプロイキャッシュ
• common-pitfalls.md：イベントレイヤーの迂回、外部キーのカスケード、ピボットへの書き込み、リソースとリクエスト形式の落とし穴
• pitfalls-deep.md：afterCommit の代替手段、オブザーバーの不整合、jsonb の競合、セーブポイント、検証ルールの内部処理

タスク固有のリファレンス

該当する動作を実装またはレビューする前に、関連するリファレンスを確認してください。

• PHP の機能、コントローラー／アクションの設計、ルーティング、リソース、外部 API については、framework-patterns.md を参照してください。
• マイグレーション、Eloquent による書き込み、キャスト、キュー、ジョブのペイロード、本番環境での起動については、persistence-and-jobs.md を参照してください。
• PHPUnit に関する作業、またはイベント、シリアル化、バリデーション、ライフサイクルの動作に影響する変更については、testing-and-pitfalls.md を参照してください。

該当するトピックに適用される既存の専門リファレンス：