> ## 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`가 패키지 설정으로 이미 등록되어 있다는 것을 전제로 합니다. 설정 등록 방법은 [패키지 설정 병합과 캐시](/ko/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()`가 실행된다는 보장이 없습니다. 진단 정보를 항상 등록하고 싶다면 그 등록을 즉시 로드되는 프로바이더에 둡니다. 서비스 바인딩만 지연시키는 구성은 [지연 서비스 프로바이더](/ko/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로 변환한 후 같은 키가 되는 이름은 피하세요. 등록 위치를 한 곳으로 모으고, CLI와 JSON 어느 쪽에서도 항목이 고유하도록 설계합니다.

## 정적 등록 상태를 테스트에서 다루기

`about` 실행이 시작될 때 표시용 `$data`는 초기화되지만, 추가 정보의 등록 목록인 `$customDataResolvers`는 유지됩니다. 매번 같은 등록으로부터 정보를 다시 수집할 수 있는 반면, 같은 PHP 프로세스에서 프로바이더의 `boot()`를 반복하면 등록이 누적될 수 있습니다.

`AboutCommand::flushState()`는 **모든 패키지의 등록**과 표시용 데이터를 지우는 메서드입니다. 프로덕션 프로바이더에서 자신의 섹션 중복을 피하려고 호출하지 마세요. 다른 패키지의 진단 정보까지 사라집니다.

자체 테스트 기반에서 애플리케이션을 재구성하는 경우, 테스트 간 상태를 초기화할 책임을 정해 둡니다. 초기화한다면 대상 프로바이더를 부팅하기 전에 수행하고, 그 후에 필요한 등록을 모두 수행합니다. 기존 테스트 기반이 상태를 초기화하고 있는지도 확인하세요.

### 릴리스 전 확인 항목

[Orchestra Testbench로 Laravel 패키지를 테스트하기](/ko/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="/ko/advanced/package-development">
    프로바이더와 리소스 등록의 기본을 확인합니다.
  </Card>

  <Card title="패키지 설정 병합과 캐시" icon="sliders" href="/ko/advanced/package-config-merging">
    기본값, 사용자의 덮어쓰기, 설정 캐시의 관계를 확인합니다.
  </Card>
</Columns>

## 참고한 1차 자료

* [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 패키지 개발](/ko/advanced/package-development.md)
- [코어 패키지와 커스텀 드라이버 - Feedable](/ko/packages/feedable/core.md)
- [Feed Generator](/ko/packages/laravel-bluesky/feed-generator.md)
- [패키지의 서비스 해석 후 훅](/ko/advanced/package-service-resolution.md)
- [Dumpable 트레이트](/ko/advanced/dumpable.md)


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