# PHP 속성

Queuety는 설정 없이 핸들러를 등록할 수 있도록 PHP 8 속성을 지원합니다. 핸들러 클래스에 `#[QueuetyHandler]`를 지정하고 자동 검색을 사용해 한 번에 모두 등록하세요.

## `#[QueuetyHandler]` 속성

```php
use Queuety\Handler;
use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    public function handle( array $payload ): void {
        wp_mail( $payload['to'], $payload['subject'], $payload['body'] );
    }

    public function config(): array {
        return [];
    }
}
```

속성 매개변수:

| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| `name` | `string` | (필수) | 디스패치에 사용되는 핸들러 이름 |
| `queue` | `string` | `'default'` | 이 핸들러의 기본 대기열 |
| `max_attempts` | `int` | `3` | 작업이 보관 상태가 되기 전 최대 실행 횟수 |
| `needs_wordpress` | `bool` | `false` | 속성에 저장되며, 현재 Queuety는 이를 읽지 않습니다 |

## 자동 검색

속성이 지정된 핸들러 클래스를 디렉터리에서 검색해 모두 등록합니다:

```php
use Queuety\Queuety;

$count = Queuety::discover_handlers(
    __DIR__ . '/handlers',  // directory to scan
    'MyPlugin\\Handlers'    // PSR-4 namespace prefix
);
// $count = number of handlers registered
```

디렉터리와 하위 디렉터리의 모든 `.php` 파일을 검색하고, 네임스페이스 접두사와 파일 경로에서 각 클래스 이름을 도출해 오토로더를 통해 불러옵니다. 그런 다음 `#[QueuetyHandler]` 속성을 포함하고 `Handler`, `Step` 또는 `Contracts\Job`를 구현하는 클래스를 등록합니다.

## CLI를 통한 자동 검색

```bash
# Preview discovered handlers
wp queuety discover /path/to/handlers MyPlugin\\Handlers

# Discover and register
wp queuety discover /path/to/handlers MyPlugin\\Handlers --register
```

출력 예시:

```
+-----------------------------------+----------+------------+
| class                             | type     | name       |
+-----------------------------------+----------+------------+
| MyPlugin\Handlers\SendEmailHandler | handler  | send_email |
| MyPlugin\Handlers\SyncDataHandler  | handler  | sync_data  |
| MyPlugin\Handlers\BuildPromptStep  | step     | (none)     |
+-----------------------------------+----------+------------+
```

## 권장 방법

플러그인의 초기화 단계에서 핸들러를 등록하세요:

```php
add_action( 'plugins_loaded', function () {
    Queuety::discover_handlers(
        __DIR__ . '/src/Handlers',
        'MyPlugin\\Handlers'
    );
} );
```

이렇게 하면 모든 핸들러에 대해 `Queuety::register()`를 수동으로 호출할 필요가 없습니다. 디렉터리에 속성이 지정된 클래스를 추가하면 새 핸들러가 자동으로 검색됩니다.

## 수동 등록과 함께 사용

자동 검색된 핸들러와 수동 등록한 핸들러는 동일한 레지스트리에 함께 존재할 수 있습니다. 같은 프로젝트에서 두 방식을 모두 사용할 수 있습니다:

```php
// Auto-discover the bulk of handlers
Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );

// Manually register a handler without the attribute
Queuety::register( 'legacy_handler', LegacyHandler::class );
```