specsfy-specialist-laravel-package-manager

Laravel パッケージマネージャー

使用する場面

• Laravel アプリケーション向けパッケージの GitHub リポジトリ URL がタスクに含まれている場合に使用します。
• インストール済みの Composer パッケージについて使用方法のファイルが必要な場合や、composer.json、composer.lock、docs/packages/ の内容が同期していない場合にも使用します。
• npm パッケージ、Laravel を使用しない PHP プロジェクト、または Packagist へのライブラリ公開には使用しないでください。

フロー

1. プロジェクトのルートを確認し、GitHub の HTTPS URL を github.com/<組織>/<リポジトリ> の形式に正規化します。小文字、数字、ピリオド、アンダースコア、ハイフンのみを含むセグメントを受け入れます。識別可能な GitHub リポジトリを指していない URL は拒否してください。
2. パッケージやコマンドを提案する前に、ローカルの指示、composer.json、composer.lock、.specsfy/PACKAGES.md、docs/packages/README.md、既存の各ファイルを読みます。新しい代替パッケージを探す前に、インストール済みのパッケージを確認してください。
3. 指定されたリポジトリで composer.json、README、設定ドキュメント、公開バージョン、使用例を確認します。情報源に記載されている内容、ローカルプロジェクトで確認できる内容、未確認の内容を分けて記録してください。
4. Composer パッケージ名、PHP バージョン、Laravel のバージョン、追加要件、インストールコマンド、設定ファイル、公開コマンド、テスト方法を特定します。リポジトリが互換性のある Composer パッケージを公開していない場合は、プロジェクトを変更する前に作業を中止し、不足している点を説明してください。パッケージが Packagist に公開されていない場合は、マニフェストの repositories を確認し、VCS ソースを追加する前に個別の許可を求めてください。
5. composer.json、composer.lock、vendor/composer/、コード内でパッケージを検索します。すでにインストールされている場合はそれを再利用し、別の composer require は実行しないでください。
6. パッケージがまだ存在せず、現在の依頼でインストールが許可されている場合は、プロジェクトのルートで composer require <vendor/nome> を実行します。プロジェクト自体がそのパッケージを開発用依存関係として扱う場合に限り、--dev を使用してください。README からコピーしたインストール後のコマンドは、目的と実行許可を確認せずに実行しないでください。
7. docs/packages/<vendor>-<nome>.md を作成または更新し、Composer 名、ロックファイルのバージョン、GitHub URL、目的、インストール方法、設定、プロジェクトで確認された使用方法、テスト、参照元を記載します。管理対象セクションの外にある人手で追加されたメモは保持してください。
8. docs/packages/README.md を作成または更新し、プロジェクトで宣言されているすべての Composer パッケージのインデックスとして、バージョン、短い目的、各ファイルへのリンクを記載します。依存関係の推移的なものも含む完全な一覧が必要な場合は、.specsfy/PACKAGES.md を参照するよう案内してください。

規則

• インストール済みのバージョンは composer.lock に記載されているバージョンです。GitHub の最新タグやマニフェストの制約だけからバージョンを推定してはいけません。
• ファイル名には正規化された Composer 名を使用し、/ は - に置き換えます。バージョンが変わっても同じファイルを更新してください。
• インデックスでは本番用と開発用の依存関係を分け、推移的な依存関係をプロジェクトが選択したものとして扱わないでください。
• 各ファイルには、ローカルコードに存在する場合、provider、facade、middleware、command、migration、config、class など、アプリケーションが実際に使用しているエントリーポイントを記載します。
• インストール、公開、テストの各コマンドには、実行する理由と変更対象となるファイルを併記してください。
• シークレット、.env の値、パッケージのコード全文、サードパーティーのドキュメントの大部分を docs/packages/ にコピーしてはいけません。

アンチパターン

• composer.json とロックファイルを読む前にインストールすると、互換性のないバージョンが導入されたり、すでに存在する依存関係が重複したりする可能性があります。
• PHP のリポジトリをすべて Laravel パッケージとして扱うと、Composer の契約を特定できないまま、汎用ライブラリ、アプリケーション、拡張機能を混同してしまいます。
• 影響と許可を確認せずに php artisan vendor:publish、マイグレーション、パッケージのスクリプトを実行すると、ファイル、データベース、設定が変更される可能性があります。
• README だけに基づいて汎用的な説明ページを作成すると、利用側のプロジェクトにパッケージがどのように現れるかを説明できなくなります。

検証

• URL、Composer 名、バージョン、要件が、一次情報または対応するローカルファイルに記載されていることを確認してください。
• composer validate --strict を実行し、パッケージがインストールされている場合は composer show <vendor/nome> を確認してください。
• プロジェクトで利用可能なテスト、フォーマッター、静的解析を実行してください。パッケージの検証だけを目的に新しいテストランナーを導入しないでください。
• docs/packages/README.md に composer.json の直接依存関係がすべて記載されていること、各リンクが既存の説明ページを参照していること、目的がまだ確認されていない場合はその旨が説明ページに記載されていることを確認してください。
• リンク、コマンド、設定名、サンプルがインストール済みのバージョンと一致していることを確認してください。対応する情報源やテストがない限り、互換性、安全性、動作について断言しないでください。

関連スキル

• $specsfy-specialist-laravel は、HTTP、Eloquent、キュー、認可、Laravel のテストにおけるパッケージの利用方法を案内します。
• $specsfy-specialist-technical-research は、リポジトリで疑問が解消されない場合に、ドキュメント、バージョン、一次情報の比較を支援します。

説明ページの規約、情報源の優先順位、適用可能な Composer コマンドについては、references/standards.md をお読みください。