ServiceProvider::optimizes() を使うと、生成と削除のコマンドをLaravelの optimize と optimize:clear に組み込めます。
このページではパッケージ開発の基礎を前提に、Laravel Framework v13.35.0 の実装を確認します。キャッシュファイルの形式ではなく、登録と運用の契約を扱います。
コマンドの登録とタスクの登録を分ける
commands() はArtisanから呼べるコマンドクラスを登録します。optimizes() は、すでに実行可能なコマンド名を最適化タスクとして登録する別の処理です。後者だけを呼んでも、コマンドクラスは登録されません。
次の例は、パッケージに CacheMetadataCommand と ClearMetadataCommand が実装済みで、それぞれの $signature が courier:cache と courier:clear-cache であることを前提にしています。
optimizes() の引数はすべてnullableで、生成だけ、削除だけの登録も可能です。ただし、生成したキャッシュをどの手順で無効化するかは、必ず利用者に案内してください。
登録キーも利用者向けの契約になる
ServiceProvider は、生成コマンドを静的配列の $optimizeCommands に、削除コマンドを $optimizeClearCommands に保存します。どちらも key が配列キーになります。
key を省略すると、プロバイダーのクラス名から名前が生成されます。たとえば CourierServiceProvider なら courier です。クラス名だけを使うため、別の名前空間にある同名プロバイダーでも衝突し得ます。
同じキーに再登録すると、その側のコマンドが後の値で上書きされます。複数のタスクを登録したい場合は、別々のキーを指定してください。また、config や routes などLaravel標準タスクのキーは避けます。標準タスクとパッケージタスクをまとめる際にも、同じ文字列キーは上書きされるためです。
標準タスクの後で実行される
確認した実装では、両コマンドは標準タスクの配列にパッケージの登録配列を展開してから、順番に呼び出します。衝突しないキーを使った場合、パッケージタスクは標準タスクの後に追加されます。
この順序を前提に、生成コマンドは他の標準キャッシュを作り直すのではなく、パッケージが所有するデータだけを生成します。複数パッケージ間の依存順序を制御するAPIとして
optimizes() を使わず、厳密な順序が必要なら専用コマンドを明示的に並べます。
キーまたはコマンド名で除外する
両コマンドの--except は、カンマ区切りの値を受け取ります。各値の前後の空白を取り除き、タスクのキーまたはコマンド名に一致したものを除外します。
cache:clear を除外します。cache はタスクのキーで、パッケージ専用の名前ではありません。
除外指定はその実行だけに作用します。プロバイダーの登録を無効化したり、以前に作ったパッケージキャッシュを自動削除したりする設定ではありません。
タスクのFAILと親コマンドの終了コードを区別する
OptimizeCommand と OptimizeClearCommand は各タスクを callSilently() で呼び、終了コードが 0 かどうかをタスク表示に渡します。通常の子コマンドの出力は表示されないため、原因の調査には専用コマンドを直接実行します。
Laravel v13.35.0 の両 handle() は、子コマンドが非ゼロを返してもその値を親の戻り値として返しません。画面に FAIL と表示されてもループは続き、例外がなければ親コマンドの終了コードは 0 になります。一方、投げられた例外はタスク表示コンポーネントで再送出されるため、同じ継続動作ではありません。
パッケージの生成がデプロイの必須条件なら、子コマンドの終了コードを直接確認できる手順にします。たとえば、以下はパッケージタスクを一括実行から除外し、標準タスクの後に1回だけ直接実行する例です。
courier:cache の失敗を終了コードに反映しますが、標準タスクの非ゼロ終了を集約するものではありません。標準タスクも厳密に検知する必要があるデプロイでは、必要なコマンドを個別に実行して終了コードを確認してください。
更新に耐えるキャッシュの設計と確認
登録だけでなく、コマンドと読み取り側の責務も決めておきます。- 生成は繰り返し実行しても同じ入力から同じ状態になり、途中失敗で不完全なデータを有効にしない。
- 削除はキャッシュが存在しない場合も正常に完了し、利用者の公開済み設定や永続データを削除しない。
- 生成に失敗したコマンドはエラーを報告して非ゼロを返す。読み取り側も壊れたキャッシュを無条件に正常扱いしない。
- キャッシュ形式を変更したら、利用者に再生成の必要性を案内し、長時間動くプロセスの再起動も検討する。
関連ページ
パッケージ設定のマージとキャッシュ
公開済み設定の補完と、設定キャッシュ再構築の関係を確認します。
パッケージのテスト
プロバイダーとArtisanコマンドをテスト環境に登録します。