Premiers pas

Installation

Prérequis

• PHP 8.2 ou ultérieur et WordPress 6.4 ou ultérieur
• MySQL 8.0+ ou MariaDB 10.6+. Les workers revendiquent des tâches et des planifications arrivées à échéance avec SELECT ... FOR UPDATE SKIP LOCKED, que les serveurs plus anciens rejettent avec une erreur de syntaxe.
• mysqli ou pdo_mysql (voir ci-dessous)
• WP-CLI sur le serveur si vous utilisez des workers dédiés avec wp queuety work
• Les extensions PHP pcntl et posix si vous utilisez des pools de workers avec --workers ou --min-workers/--max-workers

Queuety nécessite mysqli ou pdo_mysql dans l’environnement d’exécution PHP qui charge WordPress et WP-CLI. Le pilote est choisi automatiquement : mysqli est privilégié dans les environnements WordPress, tandis que pdo_mysql reste disponible pour une utilisation autonome ou directe de l’environnement d’exécution.

Pour utiliser l’environnement d’exécution adossé à la base de données sans la couche d’extension WordPress, consultez Utilisation autonome. Cette méthode utilise la même connexion et les mêmes tables d’exécution, mais n’inclut pas les ponts de hooks WordPress ni l’enregistrement WP-CLI.

Depuis l’archive de version

Chaque versionGitHub de comprend un fichier queuety.zip : l’extension avec ses dépendances Composer déjà installées. Installez la dernière version avec WP-CLI :

wp plugin install https://github.com/inline0/queuety/releases/latest/download/queuety.zip --activate

Vous pouvez aussi télécharger l’archive zip et la téléverser dans Extensions > Ajouter une extension > Téléverser une extension. C’est la méthode la plus simple pour un site WordPress classique.

Via Composer pour les Composer gérés par WordPress

composer require queuety/queuety

Activez ensuite l’extension :

wp plugin activate queuety

Le type de paquet est wordpress-plugin. Composer le place dans votre répertoire de plugins uniquement lorsque le projet requiert composer/installers et associe ce type à un chemin d'installation, comme le fait Bedrock, et le projet doit charger son propre vendor/autoload.php (Bedrock le fait également). Sans composer/installers, Composer l'installe dans vendor/queuety/queuety, où WordPress ne le trouve pas ; utilisez donc l'archive zip de la version sur une installation WordPress standard.

Depuis les sources pendant le développement

Placez le dépôt dans wp-content/plugins/queuety, puis installez les dépendances PHP :

composer install
wp plugin activate queuety

À l'activation, Queuety crée ses tables de base de données (queuety_jobs, queuety_workflows, queuety_logs, queuety_schedules, queuety_queue_states, queuety_webhooks, queuety_locks, queuety_signals, queuety_workflow_dependencies, queuety_workflow_dispatch_keys, queuety_batches, queuety_chunks, queuety_workflow_events, queuety_artifacts, queuety_state_machines, queuety_state_machine_events), afin que les workers puissent récupérer directement les tâches depuis MySQL.

Par défaut, le plugin planifie également un worker ponctuel via WordPress cron chaque minute pour la file d'attente default. Cela fournit une solution de base sans shell pour les tâches et workflows qui restent sur default, à condition que WordPress cron se déclenche. Chaque exécution traite au plus une tâche ; elle ne déclenche pas les planifications récurrentes, ne récupère pas les tâches obsolètes et ne vérifie pas les échéances des workflows ; ces opérations ne s'exécutent que dans un processus wp queuety work de longue durée (#14). Pour les files personnalisées, les planifications récurrentes, une latence plus faible ou des charges plus importantes, passez à des processus wp queuety work dédiés.

Configuration

Toutes les constantes sont facultatives. Définissez-les dans wp-config.php avant le chargement du plugin, ou avant le démarrage de Queuety dans une installation intégrée de type thème :

Les constantes d'admission des ressources et du pool adaptatif (QUEUETY_RESOURCE_*, QUEUETY_WORKER_POOL_*) sont répertoriées sur la page Workers.

QUEUETY_TABLE_PREFIX ne modifie que la partie Queuety des noms de tables. Le préfixe de base de données WordPress s'ajoute toujours au résultat ; ainsi, $wpdb->prefix = 'wp_' et QUEUETY_TABLE_PREFIX = 'themequeue_' produisent des tables telles que wp_themequeue_jobs. Les constantes QUEUETY_TABLE_* explicites restent prioritaires pour les tables individuelles.

Les connexions autonomes peuvent également définir le préfixe de table Queuety par connexion :

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
    table_prefix: 'themequeue_',
);

Le préfixe de base de données WordPress reste ainsi intact et seule la partie Queuety de la table est modifiée.

Votre première tâche

Créez une classe de gestionnaire qui implémente l'interface Handler :

use Queuety\Handler;

class SendEmailHandler implements Handler {
    public function handle( array $payload ): void {
        wp_mail( $payload['to'], $payload['subject'], $payload['body'] );
    }

    public function config(): array {
        return [
            'queue'           => 'emails',
            'max_attempts'    => 5,
        ];
    }
}

Enregistrez-la et déclenchez son exécution :

use Queuety\Queuety;

Queuety::register( 'send_email', SendEmailHandler::class );

Queuety::dispatch( 'send_email', [
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'body'    => 'Hello from Queuety!',
] );

Vous pouvez aussi utiliser la classe de tâche moderne qui peut être déclenchée :

use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

Votre premier workflow

Définissez des gestionnaires d'étapes qui implémentent l'interface Step :

use Queuety\Step;

class FetchDataHandler implements Step {
    public function handle( array $state ): array {
        $user = get_user_by( 'ID', $state['user_id'] );
        return [ 'user_name' => $user->display_name ];
    }

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

class CallLLMHandler implements Step {
    public function handle( array $state ): array {
        $response = wp_remote_post( 'https://api.openai.com/v1/chat/completions', [
            'body' => json_encode( [ 'prompt' => "Generate report for {$state['user_name']}" ] ),
        ] );
        return [ 'llm_response' => wp_remote_retrieve_body( $response ) ];
    }

    public function config(): array {
        return [ 'max_attempts' => 5 ];
    }
}

class FormatOutputHandler implements Step {
    public function handle( array $state ): array {
        $url = save_report( $state['user_name'], $state['llm_response'] );
        return [ 'report_url' => $url ];
    }

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

Déclenchez le workflow :

$workflow_id = Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

Démarrer un worker

wp queuety work

Le worker recherche les tâches en attente, les exécute, fait avancer les workflows et se met en veille lorsque la file est vide. Appuyez sur Ctrl+C pour l'arrêter ; le processus se termine immédiatement, même en pleine exécution d'une tâche (voir Workers).

Le SendEmailHandler ci-dessus envoie ses tâches à la file emails via config() ; un worker sur default ne les récupère donc pas. Nommez chaque file que vous utilisez :

wp queuety work --queue=emails,default

Si vous n'exécutez pas de worker dédié, Queuety conserve la solution de repli WordPress cron par défaut, déclenchée une fois par minute et décrite ci-dessus ; elle est limitée à la file default et à une tâche par exécution. Le worker dédié offre un débit supérieur et une latence plus faible.

En production, exécutez plusieurs workers :

wp queuety work --workers=4

Traitez plusieurs files avec un ordre de priorité :

wp queuety work --queue=high,default,low

Étapes suivantes

• Tâches pour le guide complet sur le déclenchement et la gestion des tâches
• Workflows pour les enchaînements, les étapes parallèles, les branchements conditionnels et l'exécution de workflows
• Middleware pour la limitation de débit, le throttling et la logique personnalisée du pipeline
• Traitement par lots pour déclencher des groupes de tâches avec des fonctions de rappel
• Étapes de diffusion pour enregistrer les données diffusées fragment par fragment
• Planification pour les tâches récurrentes
• Mise en cache pour la couche de cache enfichable
• Tests pour QueueFake et les assertions de test
• RéférenceCLI pour toutes les commandes disponibles
• PHP API pour l'accès programmatique