Skip to content

PHP Attributes

View as Markdown Edit on GitHub Docs at 2cc7b2b

Queuety supports PHP 8 attributes for zero-config handler registration. Annotate your handler classes with #[QueuetyHandler] and use auto-discovery to register them all at once.

The #[QueuetyHandler] attribute

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 [];
    }
}

The attribute parameters:

Parameter Type Default Description
name string (required) Handler name used for dispatch
queue string 'default' Default queue for this handler
max_attempts int 3 Maximum number of runs before the job is buried
needs_wordpress bool false Stored on the attribute; Queuety does not read it today

Auto-discovery

Scan a directory for annotated handler classes and register them all:

PHP
use Queuety\Queuety;

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

This scans every .php file in the directory and its subdirectories, derives each class name from the namespace prefix and file path, loads it through your autoloader, and registers classes that carry the #[QueuetyHandler] attribute and implement Handler, Step, or Contracts\Job.

Auto-discovery via CLI

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

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

Example output:

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

Best practice

Register handlers in your plugin's initialization:

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

This replaces manual Queuety::register() calls for every handler. New handlers are automatically picked up when you add a class with the attribute to the directory.

Combining with manual registration

Auto-discovered handlers and manually registered handlers coexist in the same registry. You can use both approaches in the same project:

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