PHP API

Afficher au format Markdown Modifier sur GitHub Documentation de 2cc7b2b

Tout ce qui se trouve dans Queuety est accessible via la classe statique Queuety\Queuety. C’est le point d’entrée unique pour distribuer des tâches, créer des workflows, piloter des machines à états, gérer des files d’attente et accéder aux sous-systèmes internes.

PHP

use Queuety\Queuety;

Accès autonome au cœur

Le runtime de Queuety, adossé à une base de données, peut être initialisé en dehors de WordPress.

Cette voie autonome est destinée au cœur d’orchestration :

tâches et workers (les pools de workers nécessitent aussi les constantes DB_HOST, DB_NAME, DB_USER et DB_PASSWORD, voir ci-dessous)
workflows et signaux
machines à états et événements
artefacts, journaux, métriques et planifications

Ce n’est pas un remplacement de l’adaptateur WordPress. Queuety::on_action(), replace_wp_cron(), l’initialisation du plugin et le véritable chemin d’enregistrement de wp queuety ... requièrent toujours WordPress.

`Queuety::init( Connection $conn )`

Initialisez Queuety avec une connexion directe à la base de données.

PHP

use Queuety\Connection;
use Queuety\Queuety;

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

Queuety::init( $conn );

L’argument facultatif table_prefix modifie la partie Queuety des noms de tables du runtime pour chaque connexion :

PHP

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

Cela associe des tables comme queuety_jobs à wp_themequeue_jobs.

`Queuety::ensure_schema()`

Assurez-vous que les tables du runtime Queuety existent pour la connexion active.

PHP

Queuety::init( $conn );
Queuety::ensure_schema();

Pour connaître le modèle complet et la limite WordPress, consultez Utilisation autonome.

Tâches

`Queuety::dispatch( $handler, $payload )`

Distribue une tâche. Accepte une chaîne indiquant le nom d’un gestionnaire ou une instance Contracts\Job. Renvoie un générateur PendingJob permettant d’enchaîner les options.

PHP

// Handler name + payload (original API)
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

// Contracts\Job instance (v0.6.0+)
Queuety::dispatch( new SendEmailJob( to: 'user@example.com' ) );

// With options
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] )
    ->on_queue( 'emails' )
    ->with_priority( Priority::High )
    ->delay( 300 )
    ->max_attempts( 5 )
    ->rate_limit( 10, 60 )
    ->unique()
    ->after( $other_job_id );

// Get the job ID
$job_id = Queuety::dispatch( 'send_email', $payload )->id();

Lorsqu’une instance Contracts\Job est transmise, le sérialiseur extrait le FQCN comme nom du gestionnaire et les propriétés publiques comme charge utile. Le paramètre $payload est ignoré lorsque $handler est une instance Job.

Méthodes de `PendingJob`

Méthode	Description
`on_queue( string $queue )`	Définir la file d’attente cible
`with_priority( Priority $priority )`	Définir le niveau de priorité
`delay( int $seconds )`	Délai avant que la tâche soit disponible
`max_attempts( int $max )`	Nombre maximal de tentatives
`rate_limit( int $max, int $window )`	Limite de débit : nombre maximal d’exécutions par fenêtre de secondes
`unique()`	Empêcher les distributions en double
`after( int $job_id )`	Attendre d’abord la fin d’une autre tâche
`concurrency_group( string $group, int $limit )`	Placer la tâche dans un groupe partagé d’admission des workers
`cost_units( int $units )`	Associer des métadonnées de coût d’exécution relatif à la distribution
`id()`	Forcer la distribution et renvoyer l’identifiant de la tâche

concurrency_group() et cost_units() s’intègrent au modèle plus large de gestion des ressources ; la même distribution peut ainsi participer aux limites de concurrence fondées sur le nombre, aux budgets pondérés des files d’attente ou des fournisseurs, ainsi qu’aux heuristiques d’admission des workers.

`Queuety::dispatch_sync( $handler, $payload )`

Exécute une tâche de façon synchrone dans le processus actuel, sans l’ajouter à la file d’attente.

PHP

// With a Job instance
Queuety::dispatch_sync( new SendEmailJob( to: 'user@example.com', subject: 'Hi', body: 'Hello' ) );

// With a handler name and payload
Queuety::dispatch_sync( 'send_email', [ 'to' => 'user@example.com' ] );

La méthode handle() de la tâche est appelée directement. Aucune ligne n’est créée dans la base de données, aucun worker n’intervient et aucun intergiciel n’est appliqué.

`Queuety::batch( $jobs )`

Distribue plusieurs tâches en une seule instruction INSERT multi-lignes.

PHP

$job_ids = Queuety::batch( [
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'a@example.com' ], 'queue' => 'emails' ],
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'b@example.com' ], 'priority' => 2 ],
] );

`Queuety::create_batch( $jobs )`

Crée un BatchBuilder pour distribuer un groupe de tâches avec des fonctions de rappel et le suivi de progression. Consultez Traitement par lots pour tous les détails.

PHP

$batch = Queuety::create_batch( [
    new ImportUsersJob( $chunk_1 ),
    new ImportUsersJob( $chunk_2 ),
] )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->allow_failures()
    ->on_queue( 'imports' )
    ->dispatch();

Méthodes de `BatchBuilder`

Méthode	Renvoie	Description
`name( string $name )`	`self`	Définir un nom pour le lot
`on_queue( string $queue )`	`self`	Définir la file d’attente de toutes les tâches du lot
`then( string $handler_class )`	`self`	Gestionnaire appelé lorsque le lot se termine avec succès
`catch( string $handler_class )`	`self`	Gestionnaire appelé lorsque la première tâche du lot échoue
`finally( string $handler_class )`	`self`	Gestionnaire appelé à la fin du lot, en cas de succès ou d’échec
`allow_failures()`	`self`	Autoriser l’exécution de la fonction de rappel `then` même en cas d’échecs
`dispatch()`	`Batch`	Créer la ligne du lot et toutes les tâches, puis renvoyer l’objet valeur `Batch`

`Queuety::find_batch( $id )`

Recherche un lot par ID. Renvoie un objet valeur Batch ou null.

PHP

$batch = Queuety::find_batch( $batch_id );

if ( null !== $batch ) {
    echo $batch->progress() . '% complete';
}

Contrôle des workers

`Queuety::run_worker( $queue = 'default', $once = false )`

Lance directement une boucle de worker.

PHP

Queuety::run_worker( 'default' );
Queuety::run_worker( 'critical,default', true );

`Queuety::run_worker_pool( $workers, $queue = 'default' )`

Lance directement un pool de workers de taille fixe. Nécessite les extensions pcntl et posix. Le pool lit les constantes WordPress DB_HOST, DB_NAME, DB_USER et DB_PASSWORD pour ses connexions enfants (seuls les préfixes de table proviennent de la connexion initialisée) ; définissez-les donc lorsque vous lancez un pool en dehors de WordPress (#5).

PHP

Queuety::run_worker_pool( 4, 'providers' );

`Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )`

Lance directement un pool de workers adaptatif. Mêmes exigences que pour run_worker_pool().

PHP

Queuety::run_auto_scaling_worker_pool( 2, 6, 'providers' );

Objet valeur `Batch`

Méthode/Propriété	Type	Description
`$id`	`int`	ID du lot
`$name`	`string\|null`	Nom facultatif du lot
`$total_jobs`	`int`	Nombre total de tâches dans le lot
`$pending_jobs`	`int`	Tâches encore en attente
`$failed_jobs`	`int`	Nombre de tâches en échec
`$failed_job_ids`	`array`	ID des tâches en échec
`$created_at`	`DateTimeImmutable`	Date de création du lot
`$finished_at`	`DateTimeImmutable\|null`	Date de fin du lot
`$cancelled_at`	`DateTimeImmutable\|null`	Date d’annulation du lot
`progress()`	`int`	Pourcentage d’avancement (0-100)
`finished()`	`bool`	Indique si le lot est terminé
`has_failures()`	`bool`	Indique si une tâche a échoué
`cancelled()`	`bool`	Indique si le lot a été annulé

`Queuety::chain( $jobs )`

Crée un ChainBuilder pour exécuter les tâches de manière séquentielle. Chaque tâche dépend de la réussite de la tâche précédente.

PHP

$first_job_id = Queuety::chain( [
    new FetchDataJob( $url ),
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )
    ->on_queue( 'pipeline' )
    ->catch( ChainFailedHandler::class )
    ->dispatch();

Méthodes de `ChainBuilder`

Méthode	Renvoie	Description
`on_queue( string $queue )`	`self`	Définir la file d’attente de toutes les tâches de la chaîne
`catch( string $handler_class )`	`self`	Gestionnaire appelé lorsqu’une tâche de la chaîne est définitivement mise en échec
`dispatch()`	`int`	Créer toutes les tâches avec des dépendances séquentielles et renvoyer l’ID de la première tâche

`Queuety::retry( $job_id )`

Relance une tâche précise. La réinitialise à l’état pending.

PHP

Queuety::retry( 42 );

`Queuety::retry_buried()`

Relance toutes les tâches mises en échec. Renvoie le nombre de tâches relancées.

PHP

$count = Queuety::retry_buried();

`Queuety::purge( $older_than_days )`

Supprime les tâches terminées. Renvoie le nombre de tâches supprimées.

PHP

$count = Queuety::purge();     // uses QUEUETY_RETENTION_DAYS
$count = Queuety::purge( 30 ); // purge jobs older than 30 days

Files d’attente

`Queuety::stats( $queue )`

Récupère le nombre de tâches regroupées par état.

PHP

$stats = Queuety::stats();          // all queues
$stats = Queuety::stats( 'emails' ); // specific queue
// ['pending' => 12, 'processing' => 3, 'completed' => 150, 'failed' => 2, 'buried' => 1]

`Queuety::buried( $queue )`

Récupère toutes les tâches mises en échec.

PHP

$jobs = Queuety::buried();
$jobs = Queuety::buried( 'emails' );

`Queuety::pause( $queue )`

Met en pause une file d’attente pour que les workers l’ignorent.

PHP

Queuety::pause( 'emails' );

`Queuety::resume( $queue )`

Reprend une file d’attente en pause.

PHP

Queuety::resume( 'emails' );

`Queuety::is_paused( $queue )`

Vérifie si une file d’attente est en pause.

PHP

if ( Queuety::is_paused( 'emails' ) ) {
    // Queue is paused
}

Workflows

`Queuety::workflow( $name )`

Commence à créer un workflow. Renvoie un WorkflowBuilder.

PHP

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

Méthodes de `WorkflowBuilder`

Méthode	Description
`then( string $handler_class, ?string $name = null )`	Ajouter une étape séquentielle. Nom facultatif pour les embranchements conditionnels.
`parallel( array $handler_classes )`	Ajouter un groupe d’étapes parallèles.
`for_each( string $items_key, string $handler_class, ?string $result_key = null, ForEachMode $mode = ForEachMode::All, ?int $quorum = null, ?string $reducer_class = null, ?string $name = null )`	Ajouter une étape dynamique « pour chaque », qui crée une tâche de branche par élément de l’état du workflow.
`repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Revenir à une étape nommée antérieure tant qu’une clé d’état publique ou une classe `RepeatCondition` correspond.
`repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Revenir à une étape nommée antérieure jusqu’à ce qu’une clé d’état publique ou une classe `RepeatCondition` corresponde.
`run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )`	Ajouter une étape d’exécution de workflow.
`delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Ajouter une étape de délai persistant. Toutes les durées sont cumulées.
`wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )`	Ajouter une étape d’attente de signal. `match_payload` et `correlation_key` facultatifs permettent d’ignorer les événements sans rapport.
`wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Attendre plusieurs signaux, tous ou un seul, avec correspondance facultative de charge utile et corrélation.
`wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Attendre un signal d’approbation humaine.
`wait_for_decision( string $approve_signal = 'approved', string $reject_signal = 'rejected', ?string $result_key = 'decision', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Attendre une approbation ou un rejet et enregistrer une charge utile de décision structurée.
`wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Attendre un signal de saisie humaine.
`wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )`	Attendre la fin d’un workflow indiqué par son ID ou par un ID stocké dans l’état public.
`wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )`	Attendre la fin de plusieurs workflows, tous, un seul ou un quorum.
`wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )`	Attendre un groupe de workflows démarré précédemment, indiqué par sa clé de groupe interne.
`start_workflows( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'started_workflow_ids', string $payload_key = 'item', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	Distribuer un workflow de premier niveau par élément du runtime, avec possibilité d’associer une clé de groupe persistante à l’ensemble démarré.
`start_agents( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'agent_workflow_ids', string $payload_key = 'agent_task', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	Alias orienté agent de `start_workflows()`.
`wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )`	Alias orienté agent de `wait_for_workflows()`.
`wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )`	Alias orienté agent de `wait_for_workflow_group()`.
`version( string $version )`	Associer à la définition du workflow une version au niveau de l’application pour inspection et export.
`idempotency_key( string $key )`	Rendre persistante la distribution du workflow à l’aide d’une clé fournie par l’appelant. Une nouvelle distribution avec la même clé renvoie l’ID du workflow d’origine.
`max_transitions( int $max )`	Faire échouer le workflow si plus de `$max` transitions d’étape sont terminées.
`max_for_each_items( int $max )`	Faire échouer le workflow si une étape `for_each()` tente de créer plus de `$max` éléments.
`max_state_bytes( int $bytes )`	Faire échouer le workflow si l’état public dépasse `$bytes`.
`max_cost_units( int $max )`	Faire échouer le workflow si les étapes terminées consomment plus de `$max` unités de coût.
`max_started_workflows( int $max )`	Faire échouer le workflow avant de distribuer plus de `$max` workflows enfants.
`compensate_with( string $handler_class )`	Associer un gestionnaire de compensation à la dernière étape ajoutée.
`compensate_on_failure()`	Exécuter automatiquement les compensations des étapes terminées en cas d’échec du workflow.
`on_queue( string $queue )`	Définir la file d’attente de toutes les étapes.
`with_priority( Priority $priority )`	Définir la priorité de toutes les étapes.
`max_attempts( int $max )`	Définir le nombre maximal de tentatives par étape.
`on_cancel( string $handler_class )`	Enregistrer une classe de gestionnaire de nettoyage en cas d’annulation. Voir Annulation.
`prune_state_after( int $steps = 2 )`	Activer l’élagage automatique de l’état. Supprime les sorties d’étape antérieures au seuil. Voir Élagage de l’état.
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Définir une échéance pour le workflow. Toutes les durées sont cumulées. Voir Échéances.
`on_deadline( string $handler_class )`	Enregistrer un gestionnaire appelé lorsque l’échéance du workflow est dépassée. Voir Échéances.
`dispatch( array $initial_payload = [] )`	Distribuer le workflow. Renvoie son ID.

`Queuety::workflow_status( $workflow_id )`

Récupère l’état du workflow. Renvoie un objet WorkflowState ou null.

PHP

$state = Queuety::workflow_status( $workflow_id );
echo $state->name;          // 'generate_report'
echo $state->status->value; // 'running'
echo $state->current_step;  // 1
echo $state->total_steps;   // 3
print_r( $state->state );   // accumulated public state array
echo $state->wait_type;     // 'signal' or 'workflow' while blocked
echo $state->wait_mode;     // 'all', 'any', or 'quorum'
echo $state->definition_version; // 'research.v2'
echo $state->definition_hash;    // '4c7a...'
echo $state->idempotency_key;    // 'brief:42:research'
echo $state->artifact_count;     // 2
print_r( $state->budget );       // configured workflow budget + current usage
print_r( $state->wait_details ); // matched/remaining blockers, result key, correlation info
print_r( $state->artifact_keys ); // ['draft', 'citations']

WorkflowState expose également :

waiting_for : noms des signaux ou ID de workflows qui bloquent actuellement l’exécution
current_step_name : nom configuré de l’étape actuelle, le cas échéant
wait_mode : mode d’attente actuel (all, any ou quorum) pendant le blocage
wait_details : données d’inspection supplémentaires, comme les blocages détectés et ceux qui restent
definition_version : valeur définie par version(), le cas échéant
definition_hash : hachage déterministe de la définition du workflow
idempotency_key : clé d’envoi durable, le cas échéant
budget : limites configurées et utilisation actuelle, si les garde-fous sont activés
artifact_count : nombre d’artefacts stockés pour le workflow
artifact_keys : clés des artefacts stockés pour une inspection rapide

`Queuety::retry_workflow( $workflow_id )`

Relancer un workflow en échec à partir de l’étape qui a échoué.

PHP

Queuety::retry_workflow( $workflow_id );

Lève RuntimeException si le workflow a déjà fait l’objet d’une compensation après un échec.

`Queuety::pause_workflow( $workflow_id )`

Mettre en pause un workflow en cours d’exécution. Le travail déjà mis en file d’attente pour l’étape actuelle peut encore se terminer, mais les étapes suivantes ne sont pas mises en file d’attente tant que vous n’avez pas repris le workflow.

PHP

Queuety::pause_workflow( $workflow_id );

`Queuety::resume_workflow( $workflow_id )`

Reprendre un workflow en pause.

PHP

Queuety::resume_workflow( $workflow_id );

`Queuety::cancel_workflow( $workflow_id )`

Annuler un workflow et exécuter tous les gestionnaires de nettoyage enregistrés. Définit le statut sur cancelled et place dans les éléments enfouis toutes les tâches en attente ou en cours de traitement associées au workflow.

PHP

Queuety::cancel_workflow( $workflow_id );

Lève RuntimeException si le workflow est déjà completed ou cancelled. Consultez Annulation pour en savoir plus.

`Queuety::rewind_workflow( $workflow_id, $to_step )`

Revenir à une étape précédente du workflow et le relancer à partir de là. L’état est restauré depuis le journal d’événements state_after pour l’étape indiquée, puis l’étape suivante est mise en file d’attente.

PHP

Queuety::rewind_workflow( $workflow_id, to_step: 1 );

Lève RuntimeException si aucun état enregistré n’existe pour l’étape cible. Nécessite le journal d’événements du workflow. Consultez Voyage dans le temps pour en savoir plus.

`Queuety::fork_workflow( $workflow_id )`

Créer une copie indépendante d’un workflow en cours d’exécution, à partir de son état actuel. Renvoie l’ID du nouveau workflow.

PHP

$forked_id = Queuety::fork_workflow( $workflow_id );

Le workflow créé par bifurcation reçoit son propre ID et fonctionne indépendamment de l’original. Consultez Bifurcation pour en savoir plus.

`Queuety::export_workflow( $workflow_id )`

Exporter l’historique complet d’exécution d’un workflow sous forme de tableau sérialisable en JSON. Inclut la ligne du workflow, toutes les tâches, les événements du workflow et les entrées du journal.

PHP

$data = Queuety::export_workflow( $workflow_id );

Consultez Exportation et rejeu pour connaître la structure JSON et ses cas d’utilisation.

`Queuety::replay_workflow( $data )`

Rejouer un workflow exporté dans l’environnement actuel. Crée un nouveau workflow à partir des données d’exportation et renvoie son ID.

PHP

$new_id = Queuety::replay_workflow( $data );

Consultez Exportation et rejeu pour en savoir plus.

`Queuety::replace_wp_cron()`

Remplacer le système intégré de WordPress cron par le planificateur de Queuety. Intercepte wp_schedule_event(), wp_unschedule_event() et wp_get_scheduled_event(), puis achemine les événements récurrents via le worker Queuety.

PHP

Queuety::replace_wp_cron();

Fonctionne uniquement lorsque WordPress est chargé. Consultez Remplacement de WP-Cron pour en savoir plus.

`Queuety::restore_wp_cron()`

Rétablir le comportement par défaut de WordPress cron en supprimant les hooks du pont Queuety cron.

PHP

Queuety::restore_wp_cron();

Consultez Remplacement de WP-Cron pour connaître les limites.

`Queuety::signal( $workflow_id, $name, $data )`

Envoyer un signal à un workflow. Si le workflow attend actuellement ce signal, il reprend immédiatement. Sinon, le signal est stocké et récupéré lorsque le workflow atteint l’étape wait_for_signal correspondante.

PHP

Queuety::signal( $workflow_id, 'approved' );

// With data merged into workflow state
Queuety::signal( $workflow_id, 'approved', [
    'approved_by' => 'admin@example.com',
] );

Consultez Signaux de workflow pour en savoir plus.

`Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )`

Enveloppe sémantique autour de signal() pour les processus d’approbation.

PHP

Queuety::approve_workflow( $workflow_id, [
    'reviewer' => 'editor@example.com',
] );

`Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )`

Enveloppe sémantique autour de signal() pour les processus de rejet.

PHP

Queuety::reject_workflow( $workflow_id, [
    'reason' => 'needs citations',
] );

`Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )`

Enveloppe sémantique autour de signal() pour la saisie structurée par un utilisateur.

PHP

Queuety::submit_workflow_input( $workflow_id, [
    'notes' => 'Ship after legal review',
] );

`Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )`

Stocker un artefact durable pour un workflow.

PHP

Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    [ 'summary' => 'done' ],
    'json',
    metadata: [ 'source' => 'agent' ],
);

`Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )`

Stocker un artefact pour l’étape de workflow en cours d’exécution.

PHP

Queuety::put_current_artifact(
    'draft',
    [ 'status' => 'ready' ],
    'json',
);

`Queuety::workflow_artifact( $workflow_id, $artifact_key )`

Récupérer un artefact stocké pour un workflow.

PHP

$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

`Queuety::workflow_artifacts( $workflow_id, $include_content = false )`

Lister les artefacts d’un workflow.

PHP

$artifacts = Queuety::workflow_artifacts( $workflow_id );

`Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )`

Supprimer un artefact d’un workflow.

PHP

Queuety::delete_workflow_artifact( $workflow_id, 'draft' );

Machines à états

`Queuety::machine( $name )`

Commencer à créer une machine à états. Renvoie un StateMachineBuilder.

PHP

use Queuety\Enums\StateMachineStatus;

$machine_id = Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Méthodes de `StateMachineBuilder`

Méthode	Description
`initial( string $state_name )`	Définir explicitement l’état initial.
`state( string $state_name, ?StateMachineStatus $terminal_status = null )`	Commencer à configurer un état.
`action( string\|array $action_class )`	Enregistrer une action d’entrée mise en file d’attente pour l’état actuel. Passer un nom de classe ou une définition structurée avec `class`, `payload` et `config` ; le `payload` est transmis à `StateAction::handle()` sous la forme `$payload`.
`on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )`	Enregistrer une transition d’événement depuis l’état actuel. La garde accepte la même forme structurée que `action()`.
`on_queue( string $queue )`	Définir la file d’attente utilisée pour les actions d’état mises en file.
`with_priority( Priority $priority )`	Définir la priorité des actions d’état mises en file.
`max_attempts( int $max_attempts )`	Définir la limite de tentatives pour les actions d’état mises en file.
`version( string $version )`	Attribuer à la définition de la machine une version au niveau de l’application.
`idempotency_key( string $key )`	Rendre l’envoi durable à l’aide d’une clé fournie par l’appelant. Un nouvel envoi avec la même clé renvoie l’ID de machine d’origine.
`dispatch( array $initial_state = [] )`	Envoyer la machine et renvoyer son ID.

Les classes d’action d’entrée d’état peuvent aussi exposer une méthode facultative config() avec les mêmes clés de politique de ressources que celles prises en charge par les étapes de workflow : concurrency_group, concurrency_limit et cost_units.

`Queuety::dispatch_state_machine_definition( $definition, $initial_state = [], $options = [] )`

Envoyer un ensemble de définitions de machine à états sérialisé. La plupart du code d’application devrait privilégier machine()->dispatch(). Cette méthode de bas niveau permet aux adaptateurs de démarrer une machine sans dépendre directement du constructeur.

PHP

$machine_id = Queuety::dispatch_state_machine_definition(
    $definition,
    [ 'thread_id' => 42 ],
    [ 'idempotency_key' => 'thread:42' ],
);

`Queuety::machine_status( $machine_id )`

Obtenir le statut actuel de la machine. Renvoie un objet StateMachineState ou null.

PHP

$status = Queuety::machine_status( $machine_id );

echo $status->name;               // 'agent_session'
echo $status->status->value;      // 'waiting_event'
echo $status->current_state;      // 'awaiting_review'
print_r( $status->state );        // public machine state
print_r( $status->available_events ); // valid incoming events in the current state

StateMachineState expose également :

definition_version
definition_hash
idempotency_key
error_message
current_action
terminal_status

`Queuety::machine_event( $machine_id, $event_name, $payload = [] )`

Envoyer un événement externe à une machine en attente.

PHP

Queuety::machine_event(
    $machine_id,
    'approve',
    [
        'approved' => true,
        'reviewer' => 'editor@example.com',
    ]
);

La charge utile est accessible aux gardes de transition et fusionnée avec l’état public de la machine lorsque l’événement est accepté.

`Queuety::list_machines( $limit = 50, $status = null )`

Lister les lignes de machine persistées à des fins d’inspection.

PHP

$machines = Queuety::list_machines();
$waiting  = Queuety::list_machines( status: 'waiting_event' );

Chaque ligne comprend l’ID de la machine, son nom, son statut, son état actuel, la version de la définition, le hachage de la définition, la clé d’idempotence et les horodatages du cycle de vie.

`Queuety::machine_timeline( $machine_id, $limit = 100, $offset = 0 )`

Obtenir la chronologie durable des événements d’une machine.

PHP

$timeline = Queuety::machine_timeline( $machine_id );
$page_two = Queuety::machine_timeline( $machine_id, 100, 100 );

Chaque ligne d’événement contient : id, machine_id, job_id, state_name, handler, event, event_name, transition_name, queue, attempt, input, output, state_before, state_after, context, artifacts, chunks, error, duration_ms et created_at.

`Queuety::machine_trace( $machine_id )`

Obtenir un ensemble de traces normalisé pour l’interface de débogage d’une machine à états UI.

PHP

$trace = Queuety::machine_trace( $machine_id );

La trace contient machine, states regroupés, events bruts, des jobs d’action corrélés, logs, artifacts et chunks.

`Queuety::machine_state_at( $machine_id, $event_id )`

Obtenir l’état public après un événement de trace précis de la machine, ou null si aucun résultat n’est trouvé.

PHP

$state = Queuety::machine_state_at( $machine_id, $event_id );

Consultez Machines à états pour le modèle de cycle de vie et des exemples d’utilisation.

Modèles de workflow

`Queuety::define_workflow( $name )`

Créer un constructeur de workflow à utiliser comme modèle.

PHP

$builder = Queuety::define_workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class );

`Queuety::register_workflow_template( $builder )`

Enregistrer un modèle de workflow.

PHP

Queuety::register_workflow_template( $builder );

`Queuety::run_workflow( $name, $payload, $options = [] )`

Envoyer un modèle de workflow enregistré en indiquant son nom. Renvoie l’ID du workflow.

PHP

$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );

$workflow_id = Queuety::run_workflow(
    'onboarding',
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

Lève RuntimeException si le modèle n’est pas enregistré.

`Queuety::dispatch_workflow_definition( $definition, $payload, $options = [] )`

Envoyer un workflow à partir d’un ensemble de définitions d’exécution.

La plupart du code d’application devrait privilégier run_workflow() ou workflow()->dispatch(). Cette méthode de bas niveau permet aux adaptateurs réutilisables d’envoyer une définition de workflow sérialisée sans dépendre des méthodes internes du gestionnaire de workflow.

PHP

$workflow_id = Queuety::dispatch_workflow_definition(
    $definition,
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

`Queuety::on_action( $hook, $workflow, $map = null, $when = null, $idempotency_key = null, $priority = 10, $accepted_args = null )`

Enregistrer une action WordPress qui envoie un workflow.

PHP

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);

$workflow peut être :

un nom de modèle de workflow enregistré
un WorkflowBuilder intégré au code

map, when et idempotency_key s’exécutent de façon synchrone dans la requête WordPress actuelle. Seules les étapes du workflow s’exécutent de façon asynchrone après l’envoi.

Consultez Déclencheurs d’action pour le guide complet.

`Queuety::workflow_templates()`

Obtenir le registre des modèles de workflow.

PHP

$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null

`Queuety::load_workflows( $directory, $recursive )`

Charger et enregistrer tous les fichiers de workflow d’un répertoire. Chaque fichier .php doit renvoyer un WorkflowBuilder. Renvoie le nombre de workflows enregistrés.

PHP

$count = Queuety::load_workflows( __DIR__ . '/workflows/' );
$count = Queuety::load_workflows( __DIR__ . '/workflows/', recursive: true );

`Queuety::load_workflow_file( $file_path )`

Charger et enregistrer un fichier de workflow. Renvoie le WorkflowTemplate ou null si le fichier ne renvoie pas de constructeur.

PHP

$template = Queuety::load_workflow_file( __DIR__ . '/workflows/onboard-user.php' );

Planification

`Queuety::schedule( $handler, $payload )`

Créer une planification récurrente. Renvoie un constructeur PendingSchedule.

PHP

Queuety::schedule( 'cleanup_handler' )
    ->every( '1 hour' )
    ->on_queue( 'maintenance' );

Queuety::schedule( 'nightly_report' )
    ->cron( '0 3 * * *' )
    ->on_queue( 'reports' );

Méthodes de `PendingSchedule`

Méthode	Description
`every( string $interval )`	Définir une expression d’intervalle (e.g, `1 hour`, `30 minutes`)
`cron( string $expression )`	Définir une expression cron à 5 champs
`overlap( OverlapPolicy $policy )`	Définir la politique de chevauchement (par défaut : `Allow`). Consultez Planification.
`on_queue( string $queue )`	Définir la file d’attente cible (par défaut : `default`)
`id()`	Forcer l’envoi et renvoyer l’ID de la planification

`Queuety::scheduler()`

Obtenir l’instance interne Scheduler.

PHP

$scheduler = Queuety::scheduler();
$schedules = $scheduler->list();
$scheduler->remove( 'handler_name' );
$count = $scheduler->tick(); // manually trigger

Enregistrement des gestionnaires

`Queuety::register( $name, $class )`

Enregistrer une classe de gestionnaire sous un nom.

PHP

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

`Queuety::discover_handlers( $directory, $namespace )`

Détecter automatiquement et enregistrer les classes de gestionnaire d’un répertoire. Renvoie le nombre de gestionnaires enregistrés.

PHP

$count = Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );

`Queuety::registry()`

Obtenir le registre des gestionnaires.

PHP

$registry = Queuety::registry();

Observabilité

`Queuety::logger()`

Obtenir l’instance Logger pour interroger les entrées du journal.

PHP

$logger = Queuety::logger();
$logs   = $logger->for_job( 42 );
$logs   = $logger->for_workflow( 7 );
$logs   = $logger->for_handler( 'send_email', 50 );
$logs   = $logger->for_event( LogEvent::Failed, 50 );
$logs   = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
$count  = $logger->purge( 30 );

`Queuety::metrics()`

Obtenir l’instance Metrics.

PHP

$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes

`Queuety::webhook_notifier()`

Obtenir l’instance WebhookNotifier.

PHP

$notifier = Queuety::webhook_notifier();
$id       = $notifier->register( 'job.buried', 'https://hooks.slack.com/...' );
$webhooks = $notifier->list();
$notifier->remove( $id );

`Queuety::rate_limiter()`

Obtenir l’instance RateLimiter.

PHP

$limiter = Queuety::rate_limiter();
$limiter->register( 'call_openai', 60, 60 );

Cache

`Queuety::cache()`

Obtenir l’instance du moteur de cache actif.

PHP

$cache = Queuety::cache();
$cache->set( 'my_key', 'my_value', 60 );
$value = $cache->get( 'my_key' );

`Queuety::set_cache( $cache )`

Remplacer le moteur de cache. Appelez cette méthode avant Queuety::init() pour utiliser une implémentation personnalisée.

PHP

Queuety::set_cache( new RedisCache() );
Queuety::init( $connection );

`QUEUETY_CACHE_TTL`

Durée de vie par défaut du cache, en secondes (par défaut : 5). Définissez cette constante dans wp-config.php pour modifier la durée de vie par défaut utilisée par les opérations internes du cache.

PHP

define( 'QUEUETY_CACHE_TTL', 10 );

Consultez Mise en cache pour en savoir plus sur les moteurs et la détection automatique.

Journal d’événements de la machine à états

`Queuety::machine_events()`

Obtenir l’instance StateMachineEventLog.

PHP

$log = Queuety::machine_events();

Journal d’événements du workflow

`Queuety::workflow_events()`

Obtenir l’instance WorkflowEventLog.

PHP

$log = Queuety::workflow_events();

`Queuety::workflow_timeline( $workflow_id, $limit = 100, $offset = 0 )`

Obtenir la chronologie complète des événements d’un workflow. Renvoie un tableau de lignes d’événement classées par ID.

PHP

$events = Queuety::workflow_timeline( $workflow_id );
$next   = Queuety::workflow_timeline( $workflow_id, 100, 100 );

Chaque ligne d’événement contient : id, workflow_id, job_id, parent_event_id, step_index, step_name, step_type, handler, event, queue, attempt, input, output, state_before, state_after, context, artifacts, chunks, error, error_message (copié depuis error.message), duration_ms et created_at.

`Queuety::workflow_trace( $workflow_id )`

Obtenir un ensemble de traces normalisé pour l’interface de débogage d’un workflow UI.

PHP

$trace = Queuety::workflow_trace( $workflow_id );

La trace contient workflow, steps regroupés, events bruts, jobs, logs, artifacts, chunks, signals et wait_dependencies.

`Queuety::trace_input( $input )`

Définir une entrée au niveau de l’application pour l’étape de workflow en cours d’exécution.

`Queuety::trace_output( $output )`

Définir une sortie au niveau de l’application pour l’étape de workflow en cours d’exécution.

`Queuety::trace_context( array $context )`

Fusionner un contexte au niveau de l’application dans l’étape de workflow en cours d’exécution.

`Queuety::workflow_state_at( $workflow_id, $step_index )`

Obtenir l’état public après la fin ou la reprise d’une étape précise du workflow, ou null si aucun résultat n’est trouvé.

PHP

$state = Queuety::workflow_state_at( $workflow_id, 2 );

Consultez Journal d’événements du workflow pour connaître les cas d’utilisation et les commandes CLI.

Instances internes

Ces méthodes renvoient des instances internes pour les cas d’utilisation avancés.

Méthode	Renvoie	Description
`Queuety::queue()`	`Queue`	Opérations de file d’attente (réclamation, libération, enfouissement)
`Queuety::worker()`	`Worker`	Contrôle du processus worker
`Queuety::workflow_manager()`	`Workflow`	Orchestration des workflows
`Queuety::machines()`	`StateMachine`	Gestion du cycle de vie des machines à états
`Queuety::connection()`	`Connection`	Connexion à la base de données
`Queuety::batch_manager()`	`BatchManager`	Gestion du cycle de vie des lots (annulation, élagage)
`Queuety::chunk_store()`	`ChunkStore`	Persistance des blocs pour les étapes en flux continu
`Queuety::machine_events()`	`StateMachineEventLog`	Événements de trace des machines à états et ensembles de traces normalisés
`Queuety::workflow_events()`	`WorkflowEventLog`	Événements de trace des workflows et ensembles de traces normalisés
`Queuety::resource_manager()`	`ResourceManager`	Profils d’admission des workers, budgets pondérés et inspection de la mémoire système
`Queuety::cache()`	`Cache`	Instance du moteur de cache

Tests

`Queuety::fake()`

Remplacer la file d’attente par un faux objet en mémoire pour les tests. Renvoie une instance QueueFake qui enregistre les tâches envoyées sans accéder à la base de données. create_batch() enregistre également les métadonnées fictives des lots ; les chaînes sont vérifiées à partir des tâches envoyées individuellement.

PHP

$fake = Queuety::fake();
SendEmailJob::dispatch( 'user@example.com', 'Hello', 'Hi!' );
$fake->assert_pushed( SendEmailJob::class );

`Queuety::reset()`

Réinitialiser tout l’état interne, y compris le faux objet de file d’attente. À appeler dans tearDown().

PHP

Queuety::reset();

Méthodes de `QueueFake`

Méthode	Description
`assert_pushed( string $class, ?Closure $callback )`	Vérifier qu’une classe de tâche a été ajoutée. Un callback facultatif filtre les données de la tâche.
`assert_pushed_times( string $class, int $count )`	Vérifier qu’une tâche a été ajoutée exactement N fois.
`assert_not_pushed( string $class )`	Vérifier qu’une tâche n’a jamais été ajoutée.
`assert_nothing_pushed()`	Vérifier qu’aucune tâche n’a été ajoutée.
`assert_batched( ?Closure $callback )`	Vérifier qu’un lot a été envoyé. Un callback facultatif filtre les données du lot.
`pushed( string $class )`	Obtenir tous les envois enregistrés pour une classe. Renvoie un tableau.
`batches()`	Obtenir tous les lots enregistrés. Renvoie un tableau.
`reset()`	Effacer toutes les tâches et tous les lots enregistrés.

Consultez Tests pour des exemples complets.

Interfaces

`Handler`

Interface pour les gestionnaires de tâches simples.

PHP

interface Handler {
    public function handle( array $payload ): void;
    public function config(): array;
}

config() peut renvoyer queue, max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit et cost_units.

`Step`

Interface pour les gestionnaires d’étapes de workflow.

PHP

interface Step {
    public function handle( array $state ): array;
    public function config(): array;
}

config() peut renvoyer max_attempts, backoff, concurrency_group, concurrency_limit et cost_units.

`Contracts\ForEachHandler`

Interface pour les gestionnaires de branches dynamiques de boucle for-each.

PHP

namespace Queuety\Contracts;

interface ForEachHandler {
    public function handle_item( array $state, mixed $item, int $index ): array;
    public function config(): array;
}

config() peut renvoyer max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit et cost_units.

`Contracts\ForEachReducer`

Réducteur facultatif pour les résultats de boucle for-each.

PHP

namespace Queuety\Contracts;

interface ForEachReducer {
    public function reduce( array $state, array $for_each ): array;
}

`Contracts\Compensation`

Interface pour les gestionnaires de compensation des étapes.

PHP

namespace Queuety\Contracts;

interface Compensation {
    public function handle( array $state ): void;
}

`Contracts\RepeatCondition`

Interface pour les prédicats de boucle utilisés par repeat_until() et repeat_while() lorsque la comparaison de clés d’état est trop limitée.

PHP

namespace Queuety\Contracts;

interface RepeatCondition {
    public function matches( array $state ): bool;
}

`Contracts\StateAction`

Interface pour les actions d’entrée d’état mises en file d’attente.

PHP

namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}

$payload transporte la donnée structurée payload de la définition de l’action, si la machine en comporte une. Renvoyer les mises à jour de l’état public. Inclure _event et éventuellement _event_payload si l’action doit déclencher une transition immédiate.

Les actions d’état peuvent aussi définir une méthode facultative config(). Queuety y lit concurrency_group, concurrency_limit et cost_units lorsque l’action d’entrée est mise en file d’attente.

`Contracts\StateGuard`

Interface pour les gardes de transition des machines à états.

PHP

namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}

`Contracts\Job`

Interface pour les classes de tâches autonomes pouvant être envoyées. Les classes de tâches encapsulent leur charge utile sous forme de propriétés publiques et leur logique d’exécution dans handle().

PHP

namespace Queuety\Contracts;

interface Job {
    public function handle(): void;
}

Les classes de tâches peuvent définir une méthode facultative middleware() qui renvoie un tableau d’instances Contracts\Middleware.

`Contracts\Cache`

Interface pour les moteurs de cache. Consultez Mise en cache pour connaître les implémentations intégrées et les moteurs personnalisés.

PHP

namespace Queuety\Contracts;

interface Cache {
    public function get( string $key ): mixed;
    public function set( string $key, mixed $value, int $ttl = 0 ): void;
    public function delete( string $key ): void;
    public function has( string $key ): bool;
    public function add( string $key, mixed $value, int $ttl = 0 ): bool;
    public function flush(): void;
}

Méthode	Renvoie	Description
`get( $key )`	`mixed`	Récupérer une valeur. Renvoie `null` si elle est introuvable ou expirée.
`set( $key, $value, $ttl )`	`void`	Stocker une valeur. Un TTL de 0 signifie qu’elle n’expire pas.
`delete( $key )`	`void`	Supprimer une valeur.
`has( $key )`	`bool`	Vérifier si une clé existe et n’a pas expiré.
`add( $key, $value, $ttl )`	`bool`	Définir une valeur de façon atomique si elle n’existe pas. Renvoie `true` si la valeur a été définie.
`flush()`	`void`	Supprimer tous les éléments du cache.

`WorkflowEventLog`

Enregistre les transitions des étapes de workflow avec leur contexte de trace complet. Accessible via Queuety::workflow_events().

Méthode	Renvoie	Description
`record_event( array $event )`	`void`	Enregistrer un événement de trace brut
`record_step_started( ... )`	`void`	Enregistrer un événement step_started avec l’entrée et l’état avant l’exécution
`record_step_completed( ... )`	`void`	Enregistrer un événement step_completed avec l’entrée, la sortie et les états avant et après l’exécution
`record_step_failed( ... )`	`void`	Enregistrer un événement step_failed avec le contexte de trace et des détails d’erreur structurés
`get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )`	`array`	Obtenir les événements de trace du workflow dans l’ordre, avec pagination facultative
`get_trace( int $workflow_id )`	`array`	Obtenir un ensemble de traces normalisé
`get_state_at_step( int $workflow_id, int $step_index )`	`array\|null`	Obtenir l’état public après la fin ou la reprise d’une étape précise
`prune( int $older_than_days )`	`int`	Supprimer les événements datant de plus que le nombre de jours indiqué. Renvoie le nombre de lignes supprimées.

`StateMachineEventLog`

Enregistre les événements du cycle de vie des machines à états, des actions, des transitions et des gardes, avec les mêmes champs de trace que les événements de workflow.

Méthode	Renvoie	Description
`record_event( array $event )`	`void`	Enregistre un événement brut de trace machine
`get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )`	`array`	Récupère les événements de trace machine dans l’ordre, avec pagination facultative
`get_trace( int $machine_id )`	`array`	Récupère un ensemble normalisé de traces machine
`get_state_at_event( int $machine_id, int $event_id )`	`array\|null`	Récupère l’état public après un événement de trace machine donné
`prune( int $older_than_days )`	`int`	Supprime les événements antérieurs au nombre de jours indiqué. Renvoie le nombre de lignes supprimées.

`Contracts\StreamingStep`

Interface pour les gestionnaires d’étapes de workflow qui produisent un flux de blocs. Chaque valeur générée est immédiatement enregistrée dans la base de données. Voir Étapes en flux continu.

PHP

namespace Queuety\Contracts;

interface StreamingStep {
    public function stream( array $state, array $existing_chunks = [] ): \Generator;
    public function on_complete( array $chunks, array $state ): array;
    public function config(): array;
}

Méthode	Description
`stream( $state, $existing_chunks )`	Générateur qui produit des blocs de chaînes. Chaque génération déclenche une écriture immédiate dans la base de données. En cas de nouvelle tentative, `$existing_chunks` contient les blocs déjà enregistrés.
`on_complete( $chunks, $state )`	Appelée une fois le flux terminé. Renvoie des données à fusionner avec l’état du workflow.
`config()`	Configuration facultative. Prend en charge `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` et `cost_units`.

`ChunkStore`

Gère la persistance des blocs pour les étapes en flux continu. Accessible via Queuety::chunk_store().

Méthode	Renvoie	Description
`get_chunks( int $job_id )`	`string[]`	Récupère tous les blocs d’une tâche, triés par index de bloc
`append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )`	`void`	Ajoute un bloc
`clear_chunks( int $job_id )`	`void`	Supprime tous les blocs d’une tâche
`chunk_count( int $job_id )`	`int`	Compte les blocs d’une tâche
`get_accumulated( int $job_id )`	`string`	Concatène tous les blocs en une seule chaîne

`Heartbeat`

Méthode utilitaire statique pour envoyer des signaux de présence depuis les gestionnaires d’étapes et les étapes en flux continu. Voir Signaux de présence.

Méthode	Description
`Heartbeat::init( int $job_id, Connection $conn )`	Définit le contexte de la tâche. Appelée automatiquement par le processus de travail.
`Heartbeat::beat( array $progress = [] )`	Envoie un signal de présence. Met à jour `reserved_at` et enregistre éventuellement les données de progression dans `heartbeat_data`.
`Heartbeat::clear()`	Efface le contexte de la tâche. Appelée automatiquement par le processus de travail.
`Heartbeat::current_job_id()`	Récupère l’ID de la tâche en cours (pour les tests).

`Contracts\Middleware`

Interface pour les intergiciels de tâches. Un intergiciel enveloppe l’exécution d’une tâche dans un pipeline en oignon.

PHP

namespace Queuety\Contracts;

interface Middleware {
    public function handle( object $job, \Closure $next ): void;
}

Traits

`Dispatchable`

Fournit des méthodes de distribution statique pour les classes de tâches qui implémentent Contracts\Job. Les arguments du constructeur sont transmis pour créer l’instance de la tâche.

PHP

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

class SendEmailJob implements Job {
    use Dispatchable;
    // ...
}

// Dispatches a new SendEmailJob instance
SendEmailJob::dispatch( 'user@example.com', 'Subject', 'Body' );

Méthode	Renvoie	Description
`dispatch( ...$args )`	`PendingJob`	Crée une instance et la distribue
`dispatch_if( bool $condition, ...$args )`	`PendingJob\|null`	Distribue uniquement si `$condition` est vrai
`dispatch_unless( bool $condition, ...$args )`	`PendingJob\|null`	Distribue uniquement si `$condition` est faux
`with_chain( array $jobs )`	`ChainBuilder`	Démarre une chaîne à partir de cette classe de tâche

PHP

// Conditional dispatch
SendEmailJob::dispatch_if( $user->wants_email, $user->email, 'Hello', 'Hi!' );
SendEmailJob::dispatch_unless( $maintenance_mode, $user->email, 'Hello', 'Hi!' );

// Chain from a job class
FetchDataJob::with_chain( [
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )->dispatch();

Propriétés des tâches

Les classes de tâches peuvent déclarer des propriétés publiques que le processus de travail lit par réflexion pour remplacer le comportement de nouvelle tentative et de délai d’expiration.

Propriété	Type	Description
`$tries`	`int`	Nombre maximal de tentatives avant la mise en quarantaine de la tâche
`$timeout`	`int`	Durée d’exécution maximale en secondes (nécessite `pcntl`)
`$backoff`	`array`	Valeurs de délai croissantes en secondes pour chaque nouvelle tentative

PHP

class ImportProductsJob implements Job {
    use Dispatchable;

    public int $tries = 5;
    public int $timeout = 120;
    public array $backoff = [ 10, 30, 60, 120 ];

    // ...
}

Hook `failed()`

Lorsqu’une tâche est mise en quarantaine après avoir épuisé toutes ses tentatives, le processus de travail appelle une méthode failed() sur l’instance de la tâche si elle est définie.

PHP

public function failed( \Throwable $exception ): void {
    error_log( "Job failed: {$exception->getMessage()}" );
}

Intergiciels intégrés

Toutes les classes d’intergiciel implémentent Contracts\Middleware et se trouvent dans l’espace de noms Queuety\Middleware.

Classe	Description
`RateLimited( int $max, int $window )`	Applique une limite de débit de `$max` exécutions toutes les `$window` secondes
`Timeout( int $seconds )`	Arrête la tâche après `$seconds` secondes (nécessite `pcntl`)
`UniqueJob( ?string $key )`	Empêche les exécutions simultanées au moyen d’un verrou de base de données
`WithoutOverlapping( string $key, int $release_after )`	Empêche les chevauchements d’exécution avec expiration automatique du verrou
`ThrottlesExceptions( int $max_attempts, int $decay_minutes )`	Limite les exceptions pour éviter les tempêtes de tâches lorsqu’un service externe est indisponible

Consultez Intergiciels pour connaître les détails d’utilisation et voir des exemples.

Énumérations

`Priority`

PHP

enum Priority: int {
    case Low    = 0;
    case Normal = 1;
    case High   = 2;
    case Urgent = 3;
}

`JobStatus`

PHP

enum JobStatus: string {
    case Pending    = 'pending';
    case Processing = 'processing';
    case Completed  = 'completed';
    case Failed     = 'failed';
    case Buried     = 'buried';
}

`WorkflowStatus`

PHP

enum WorkflowStatus: string {
    case Running        = 'running';
    case Completed      = 'completed';
    case Failed         = 'failed';
    case Paused         = 'paused';
    case WaitingForSignal  = 'waiting_for_signal';
    case WaitingForWorkflows = 'waiting_for_workflows';
    case Cancelled      = 'cancelled';
}

`StateMachineStatus`

PHP

enum StateMachineStatus: string {
    case Running = 'running';
    case WaitingEvent = 'waiting_event';
    case Completed = 'completed';
    case Failed = 'failed';
    case Paused = 'paused';
    case Cancelled = 'cancelled';
}

`BackoffStrategy`

PHP

enum BackoffStrategy: string {
    case Fixed       = 'fixed';
    case Linear      = 'linear';
    case Exponential = 'exponential';
}

`ForEachMode`

PHP

enum ForEachMode: string {
    case All = 'all';
    case FirstSuccess = 'first_success';
    case Quorum = 'quorum';
}

`WaitMode`

PHP

enum WaitMode: string {
    case All    = 'all';
    case Any    = 'any';
    case Quorum = 'quorum';
}

`LogEvent`

PHP

enum LogEvent: string {
    case Started                  = 'started';
    case Completed                = 'completed';
    case Failed                   = 'failed';
    case Buried                   = 'buried';
    case Retried                  = 'retried';
    case WorkflowStarted          = 'workflow_started';
    case WorkflowCompleted        = 'workflow_completed';
    case WorkflowFailed           = 'workflow_failed';
    case WorkflowPaused           = 'workflow_paused';
    case WorkflowResumed          = 'workflow_resumed';
    case WorkflowCancelled        = 'workflow_cancelled';
    case WorkflowRewound          = 'workflow_rewound';
    case WorkflowForked           = 'workflow_forked';
    case WorkflowDeadlineExceeded = 'workflow_deadline_exceeded';
    case Debug                    = 'debug';
}

`OverlapPolicy`

PHP

enum OverlapPolicy: string {
    case Allow  = 'allow';
    case Skip   = 'skip';
    case Buffer = 'buffer';
}

Consultez Planification pour savoir comment fonctionne chaque stratégie.

Attributs

`#[QueuetyHandler]`

PHP 8 attribut pour l’enregistrement automatique. Voir Attributs PHP.

PHP

use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    // ...
}

Pont CLI

`Queuety::cli_command()`

Renvoie le nom publié de la commande racine WP-CLI.

La commande racine par défaut est queuety. Définissez QUEUETY_CLI_COMMAND avant le démarrage de Queuety si la commande doit être publiée sous un autre nom.

`Queuety::cli_command_map()`

Renvoie le catalogue sérialisable de commandes Queuety CLI destiné aux environnements de test qui doivent connaître les commandes fournies sans analyser les classes WP-CLI.

Chaque entrée comprend :

un ID d’opération stable
le chemin relatif CLI
la classe et la méthode du gestionnaire WP-CLI
les cibles d’exécution possibles
l’adaptateur qui normalise les arguments CLI bruts en un plan d’exécution

`Queuety::resolve_cli_command( $path, $args, $assoc_args )`

Transforme un appel CLI analysé en plan d’exécution à lancer dans l’environnement de test.

PHP

$plan = Queuety::resolve_cli_command(
    [ 'workflow', 'export' ],
    [ '42' ],
    [ 'output' => '/tmp/workflow.json' ]
);

echo $plan['callable']; // Queuety\Queuety::export_workflow_to_file
print_r( $plan['arguments'] );

Les plans d’exécution tiennent compte du transport :

les commandes sont résolues en fonctions appelables publiques PHP avec des arguments normalisés
le catalogue répertorie à l’avance toutes les cibles d’exécution possibles, tandis que callable et transport identifient la branche choisie pour l’entrée analysée

C’est le format standard utilisé par Queuety pour les environnements de test d’agents : ID d’opération stable, cible publique API et normalisation gérée par l’adaptateur pour les aspects propres à CLI, tels que les valeurs par défaut des files d’attente, le décodage des données utiles JSON, le choix de branche du pool de processus et la gestion des fichiers d’export de workflow.

PHP API

Accès autonome au cœur

Queuety::init( Connection $conn )

Queuety::ensure_schema()

Tâches

Queuety::dispatch( $handler, $payload )

Méthodes de PendingJob

Queuety::dispatch_sync( $handler, $payload )

Queuety::batch( $jobs )

Queuety::create_batch( $jobs )

Méthodes de BatchBuilder

Queuety::find_batch( $id )

Contrôle des workers

Queuety::run_worker( $queue = 'default', $once = false )

Queuety::run_worker_pool( $workers, $queue = 'default' )

Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )

Objet valeur Batch

Queuety::chain( $jobs )

Méthodes de ChainBuilder

Queuety::retry( $job_id )

Queuety::retry_buried()

Queuety::purge( $older_than_days )

Files d’attente

Queuety::stats( $queue )

Queuety::buried( $queue )

Queuety::pause( $queue )

Queuety::resume( $queue )

Queuety::is_paused( $queue )

Workflows

Queuety::workflow( $name )

Méthodes de WorkflowBuilder

Queuety::workflow_status( $workflow_id )

Queuety::retry_workflow( $workflow_id )

Queuety::pause_workflow( $workflow_id )

Queuety::resume_workflow( $workflow_id )

Queuety::cancel_workflow( $workflow_id )

Queuety::rewind_workflow( $workflow_id, $to_step )

Queuety::fork_workflow( $workflow_id )

Queuety::export_workflow( $workflow_id )

Queuety::replay_workflow( $data )

Queuety::replace_wp_cron()

Queuety::restore_wp_cron()

Queuety::signal( $workflow_id, $name, $data )

Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )

Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )

Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )

Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )

Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )

Queuety::workflow_artifact( $workflow_id, $artifact_key )

Queuety::workflow_artifacts( $workflow_id, $include_content = false )

Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )