# Atributos de PHP

Queuety admite atributos de PHP 8 para registrar controladores sin configuración. Anote las clases de sus controladores con `#[QueuetyHandler]` y use la detección automática para registrarlos todos a la vez.

## El atributo `#[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 [];
    }
}
```

Parámetros del atributo:

| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| `name` | `string` | (obligatorio) | Nombre del controlador usado para el envío |
| `queue` | `string` | `'default'` | Cola predeterminada para este controlador |
| `max_attempts` | `int` | `3` | Número máximo de ejecuciones antes de enterrar el trabajo |
| `needs_wordpress` | `bool` | `false` | Se almacena en el atributo; Queuety no lo lee actualmente |

## Detección automática

Analice un directorio para encontrar clases de controladores anotadas y regístrelas todas:

```php
use Queuety\Queuety;

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

Esto analiza cada archivo `.php` del directorio y sus subdirectorios, deduce el nombre de cada clase a partir del prefijo del espacio de nombres y la ruta del archivo, lo carga mediante su autocargador y registra las clases que tienen el atributo `#[QueuetyHandler]` e implementan `Handler`, `Step` o `Contracts\Job`.

## Detección automática mediante 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
```

Ejemplo de salida:

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

## Práctica recomendada

Registre los controladores durante la inicialización de su plugin:

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

Esto sustituye las llamadas manuales a `Queuety::register()` para cada controlador. Los nuevos controladores se detectan automáticamente al añadir al directorio una clase con el atributo.

## Combinar con el registro manual

Los controladores detectados automáticamente y los registrados manualmente coexisten en el mismo registro. Puede usar ambos métodos en el mismo proyecto:

```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 );
```