> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# パッケージの診断情報をaboutに追加する

> Laravel 13のAboutCommandを使い、パッケージの設定状態をCLIとJSONで表示する方法、評価タイミングと長期保守時の注意点を解説します。

利用者から問い合わせを受けたときに、パッケージの有効・無効や選択中のドライバーを同じ形式で確認できるようにします。`AboutCommand::add()` を使えば、専用コマンドを実装せずに `php artisan about` の出力へパッケージ用のセクションを追加できます。

公式ドキュメントには登録の基本例があります。このページではLaravel 13の実装まで確認し、情報を収集するタイミング、JSONの型、セクション名の衝突、テストでの登録状態を掘り下げます。

## プロバイダーで表示内容を登録する

次の例は、`courier.enabled` と `courier.driver` がパッケージの設定として登録済みであることを前提にしています。設定の登録方法は[パッケージ設定のマージと更新](/jp/advanced/package-config-merging)を参照してください。

```php theme={null}
<?php

namespace Acme\Courier;

use Illuminate\Foundation\Console\AboutCommand;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if (! $this->app->runningInConsole()) {
            return;
        }

        AboutCommand::add('Acme Courier', fn () => [
            'Enabled' => AboutCommand::format(
                (bool) config('courier.enabled', false),
                console: fn (bool $enabled) => $enabled ? 'ENABLED' : 'OFF',
            ),
            'Driver' => (string) config('courier.driver', 'log'),
        ]);
    }
}
```

`runningInConsole()` はHTTPリクエストで不要な登録を避ける条件です。`about` の実行時だけを判定する条件ではなく、他のArtisanコマンドでも登録されます。ただし、上のクロージャー内の設定取得は登録時には実行されません。

<Warning>
  表示する項目は明示的に選びます。APIキー、アクセストークン、認証情報を含む接続URL、設定配列全体は出力しないでください。JSON出力にも自動的な秘密情報のマスクはありません。問い合わせ時はパッケージのセクションだけを共有してもらい、共有前に内容を確認します。
</Warning>

## 登録と評価のタイミングを分けて考える

Laravel `v13.35.0` の `add()` は、その場でデータを収集せず、静的な `$customDataResolvers` に登録用のクロージャーを追加します。`about` の実行時に表示用データを組み立て、登録されたデータ取得用クロージャーを評価します。

```mermaid theme={null}
flowchart TD
    A["プロバイダーのboot()"] --> B["add()で登録を保存"]
    B --> C["aboutを実行"]
    C --> D["標準情報と追加セクションを収集"]
    D --> E["データ取得用クロージャーを評価"]
    E --> F["--onlyでセクションを絞る"]
    F --> G["CLIまたはJSONで表示"]
```

設定値を `add()` の外側で先に読み込んで配列へ固定するより、クロージャー内で取得するほうがコマンド実行時の状態を反映できます。一方、`--only` のフィルターはデータ取得用クロージャーの評価より**後**です。

```bash theme={null}
php artisan about --only=environment
```

このように標準セクションだけを指定しても、上の `Acme Courier` のクロージャーは評価されます。表示されないことと、処理されないことは別です。

そのため、追加情報は設定値や軽量なローカル状態から取得します。外部APIへの疎通確認、DBへの問い合わせ、ファイルの書き換えなどを入れると、無関係なセクションを確認するコマンドまで遅くなったり失敗したりします。疎通確認や修復は専用のArtisanコマンドへ分けてください。

<Tip>
  `runningInConsole()` の条件だけでは、遅延サービスプロバイダーの `boot()` が実行されることは保証されません。診断情報を常に登録したい場合は、その登録を即時読み込みのプロバイダーへ置きます。サービスのバインディングだけを遅延化する構成は[遅延サービスプロバイダー](/jp/advanced/deferred-provider)を参照してください。
</Tip>

## CLI表示とJSONの型を両立する

パッケージの情報だけを確認するには、セクション名を小文字のsnake caseにした値を指定します。`Acme Courier` の場合は `acme_courier` です。

```bash theme={null}
php artisan about --only=acme_courier
php artisan about --only=environment,acme_courier
php artisan about --only=acme_courier --json
```

上の登録例で `courier.enabled` が `true`、`courier.driver` が `log` のとき、JSONは次の形になります。

```json theme={null}
{
  "acme_courier": {
    "enabled": true,
    "driver": "log"
  }
}
```

CLIでは `Enabled` が `ENABLED` と表示されます。`AboutCommand::format()` は、CLI用の `console` とJSON用の `json` を指定できるヘルパーです。上の例は `console` だけを指定しているため、JSONでは元のboolean値が返ります。CLIの表示文字列をそのままJSONへ流用する必要はありません。

| 対象 | 実装上の変換・処理 |
| - | - |
| `--only` の値とセクション名 | 小文字にした後にsnake caseへ変換して比較 |
| JSONのセクションキー | セクション名をsnake caseへ変換 |
| JSONの項目キー | 項目名を小文字にした後にsnake caseへ変換 |
| `format()` の値 | CLIでは `console`、JSONでは `json` を使用。未指定なら元の値 |

例のように通常の英語の単語を空白で区切った名前を使うと、フィルターやJSONキーを扱いやすくなります。自動処理で参照するキーは、表示名の変更でも変わり得るため、リリース時に互換性を確認します。

## セクションはパッケージ専用の名前にする

`add()` は同じセクションへの項目を追記します。同じ名前のセクションを指定したからといって、先に登録した内容全体を置き換えるわけではありません。

他のパッケージと区別できる `Acme Courier` のような名前を選び、Laravel標準の `Environment`、`Cache`、`Drivers`、`Storage` への追加は必要な場合に限定します。

同一セクションに同名の項目を重複登録すると、CLIでは複数行として残り得ますが、JSONでは同じキーに集約され後の値が残ります。また、異なる表記でもsnake caseへの変換後に同じキーになる名前は避けてください。登録場所を1か所にまとめ、CLIとJSONのどちらでも項目が一意になる設計にします。

## 静的な登録状態をテストで扱う

`about` の実行開始時に表示用の `$data` は初期化されますが、追加情報の登録リスト `$customDataResolvers` は保持されます。毎回同じ登録から情報を再収集できる一方、同一PHPプロセスでプロバイダーの `boot()` を繰り返すと登録が累積する可能性があります。

`AboutCommand::flushState()` は**すべてのパッケージの登録**と表示用データを消すメソッドです。本番のプロバイダーで自分のセクションを重複回避するために呼ばないでください。他のパッケージの診断情報まで失われます。

独自のテスト基盤でアプリケーションを再構築する場合は、テスト間で状態を初期化する責任を決めます。初期化するなら対象プロバイダーを起動する前に行い、その後に必要な登録をすべて行います。既存のテスト基盤が状態を初期化しているかも確認してください。

### リリース前の確認項目

[パッケージのテスト](/jp/advanced/package-testing)と実際の利用アプリケーションで、次の組み合わせを確認します。

| 確認する操作 | 期待する結果 |
| - | - |
| `about --only=acme_courier` | パッケージのセクションのみを表示し、項目が重複しない |
| `about --only=acme_courier --json` | `enabled` はboolean、`driver` はstringとして取得できる |
| `about --only=environment` | パッケージの情報収集に外部通信や副作用がなく、正常に終了する |
| 有効・無効やドライバーを変更 | 表示値とJSONの値が、コマンド実行時の設定に対応する |
| 同じアプリケーションで2回実行 | 項目が累積せず、各実行で情報を再収集する |
| 同一PHPプロセスでアプリケーションを再構築 | 登録状態がテスト間に漏れず、他パッケージの情報も欠落しない |
| 設定キャッシュがある状態 | 公開設定ファイルの内容ではなく、アプリケーションが使っている設定値を表示する |

## 関連ページ

<Columns cols={2}>
  <Card title="Laravelパッケージ開発" icon="box" href="/jp/advanced/package-development">
    プロバイダーとリソース登録の基本を確認します。
  </Card>

  <Card title="パッケージ設定のマージと更新" icon="sliders" href="/jp/advanced/package-config-merging">
    既定値、利用者の上書き、設定キャッシュの関係を確認します。
  </Card>
</Columns>

## 参照した一次情報

* [Laravel公式ドキュメント: パッケージからaboutへの情報追加](https://github.com/laravel/docs/blob/13.x/packages.md#about-artisan-command)
* [Laravel公式ドキュメント: aboutと--only](https://github.com/laravel/docs/blob/13.x/configuration.md#the-about-command)
* [Laravel Framework v13.35.0: AboutCommand](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/AboutCommand.php) — 登録、評価順序、キー変換、`format()`、`flushState()`。
* [Laravel Framework v13.35.0: formatのテスト](https://github.com/laravel/framework/blob/v13.35.0/tests/Foundation/Console/AboutCommandTest.php)
* [Laravel Framework v13.35.0: JSON出力の統合テスト](https://github.com/laravel/framework/blob/v13.35.0/tests/Integration/Foundation/Console/AboutCommandTest.php)


## Related topics

- [Laravelパッケージ開発](/jp/advanced/package-development.md)
- [パッケージの静的解析（PHPStan / Larastan）](/jp/advanced/package-static-analysis.md)
- [パッケージのバージョン互換性管理](/jp/advanced/package-versioning.md)
- [パッケージの公開アセットと更新](/jp/advanced/package-assets.md)
- [パッケージのサービス解決後フック](/jp/advanced/package-service-resolution.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.