PHP API

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 2cc7b2b

Všetko v Queuety je dostupné cez statickú triedu Queuety\Queuety. Je jediným vstupným bodom na odosielanie úloh, vytváranie pracovných postupov, riadenie stavových automatov, správu frontov a prístup k interným subsystémom.

PHP

use Queuety\Queuety;

Samostatný prístup k jadru

Behové prostredie Queuety založené na databáze možno inicializovať mimo WordPress.

Táto samostatná cesta slúži jadru orchestrace:

úlohy a pracovníci (skupiny pracovníkov potrebujú aj konštanty DB_HOST, DB_NAME, DB_USER a DB_PASSWORD; pozri nižšie)
pracovné postupy a signály
stavové automaty a udalosti
artefakty, záznamy, metriky a plánovače

Nenahrádza adaptér WordPress. Queuety::on_action(), replace_wp_cron(), inicializácia doplnku a skutočná cesta registrácie wp queuety ... stále vyžadujú WordPress.

`Queuety::init( Connection $conn )`

Inicializujte Queuety priamym pripojením k databáze.

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

Voliteľný argument table_prefix mení časť názvov runtime tabuliek Queuety pre každé pripojenie:

PHP

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

Tým sa názvy tabuliek, napríklad queuety_jobs, prevedú na wp_themequeue_jobs.

`Queuety::ensure_schema()`

Uistite sa, že pre aktívne pripojenie existujú runtime tabuľky Queuety.

PHP

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

Úplný model a hranice WordPress nájdete v časti Samostatné použitie.

Úlohy

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

Odošle úlohu. Prijíma buď reťazec s názvom obslužnej funkcie, alebo inštanciu Contracts\Job. Vráti zostavovač PendingJob na reťazenie možností.

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

Keď sa odovzdá inštancia Contracts\Job, serializátor použije FQCN ako názov obslužnej funkcie a verejné vlastnosti ako údaje. Parameter $payload sa ignoruje, ak je $handler inštanciou Job.

Metódy `PendingJob`

Metóda	Opis
`on_queue( string $queue )`	Nastaví cieľový front
`with_priority( Priority $priority )`	Nastaví úroveň priority
`delay( int $seconds )`	Čas, po ktorom bude úloha dostupná
`max_attempts( int $max )`	Maximálny počet pokusov o opakovanie
`rate_limit( int $max, int $window )`	Obmedzenie frekvencie: maximum vykonaní za počet sekúnd intervalu
`unique()`	Zabráni duplicitnému odoslaniu
`after( int $job_id )`	Počká, kým sa najprv dokončí iná úloha
`concurrency_group( string $group, int $limit )`	Zaradí úlohu do zdieľanej skupiny na prijímanie pracovníkov
`cost_units( int $units )`	Pripojí k odoslaniu metadáta o relatívnej náročnosti vykonania
`id()`	Vynúti odoslanie a vráti ID úlohy

concurrency_group() a cost_units() sú súčasťou širšieho modelu Správa zdrojov, takže to isté odoslanie môže podliehať limitom súbežnosti podľa počtu, váženým rozpočtom frontu alebo poskytovateľa a heuristikám prijímania pracovníkov.

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

Vykoná úlohu synchrónne v aktuálnom procese bez pridania do frontu.

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

Metóda handle() úlohy sa zavolá priamo. Nevytvorí sa žiadny riadok v databáze, nepoužije sa pracovník a neuplatní sa middleware.

`Queuety::batch( $jobs )`

Odošle viacero úloh jediným viacriadkovým príkazom INSERT.

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

Vytvorí BatchBuilder na odosielanie skupiny úloh so spätnými volaniami a sledovaním priebehu. Podrobnosti nájdete v časti Dávkové spracovanie.

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

Metódy `BatchBuilder`

Metóda	Vráti	Opis
`name( string $name )`	`self`	Nastaví názov dávky
`on_queue( string $queue )`	`self`	Nastaví front pre všetky úlohy v dávke
`then( string $handler_class )`	`self`	Obslužná funkcia volaná po úspešnom dokončení dávky
`catch( string $handler_class )`	`self`	Obslužná funkcia volaná pri zlyhaní prvej úlohy v dávke
`finally( string $handler_class )`	`self`	Obslužná funkcia volaná po dokončení dávky (úspešnom alebo neúspešnom)
`allow_failures()`	`self`	Umožní spustenie spätného volania `then` aj pri zlyhaniach
`dispatch()`	`Batch`	Vytvorí riadok dávky a všetky úlohy, vráti objekt s hodnotou `Batch`

`Queuety::find_batch( $id )`

Vyhľadá dávku podľa ID. Vráti objekt s hodnotou Batch alebo null.

PHP

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

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

Riadenie pracovníkov

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

Spustí priamo jednu slučku pracovníka.

PHP

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

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

Spustí priamo skupinu pracovníkov s pevnou veľkosťou. Vyžaduje rozšírenia pcntl a posix. Skupina pre pripojenia svojich podprocesov načítava konštanty WordPress, DB_HOST, DB_NAME, DB_USER a DB_PASSWORD (z inicializovaného pripojenia preberá iba predpony tabuliek), preto ich definujte pri spustení skupiny mimo WordPress (#5).

PHP

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

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

Spustí priamo adaptívnu skupinu pracovníkov. Platí rovnaké požiadavky ako pre run_worker_pool().

PHP

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

Objekt s hodnotou `Batch`

Metóda/vlastnosť	Typ	Opis
`$id`	`int`	ID dávky
`$name`	`string\|null`	Voliteľný názov dávky
`$total_jobs`	`int`	Celkový počet úloh v dávke
`$pending_jobs`	`int`	Zostávajúce čakajúce úlohy
`$failed_jobs`	`int`	Počet neúspešných úloh
`$failed_job_ids`	`array`	ID neúspešných úloh
`$created_at`	`DateTimeImmutable`	Čas vytvorenia dávky
`$finished_at`	`DateTimeImmutable\|null`	Čas dokončenia dávky
`$cancelled_at`	`DateTimeImmutable\|null`	Čas zrušenia dávky
`progress()`	`int`	Percento dokončenia (0 – 100)
`finished()`	`bool`	Či je dávka dokončená
`has_failures()`	`bool`	Či zlyhala niektorá úloha
`cancelled()`	`bool`	Či bola dávka zrušená

`Queuety::chain( $jobs )`

Vytvorí ChainBuilder na postupné vykonávanie úloh. Každá úloha závisí od úspešného dokončenia predchádzajúcej.

PHP

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

Metódy `ChainBuilder`

Metóda	Vráti	Opis
`on_queue( string $queue )`	`self`	Nastaví front pre všetky úlohy v reťazci
`catch( string $handler_class )`	`self`	Obslužná funkcia volaná, keď je niektorá úloha v reťazci natrvalo presunutá do úložiska neúspešných úloh
`dispatch()`	`int`	Vytvorí všetky úlohy so sekvenčnými závislosťami a vráti ID prvej úlohy

`Queuety::retry( $job_id )`

Zopakuje konkrétnu úlohu a obnoví jej stav na pending.

PHP

Queuety::retry( 42 );

`Queuety::retry_buried()`

Zopakuje všetky úlohy presunuté do úložiska neúspešných úloh. Vráti počet zopakovaných úloh.

PHP

$count = Queuety::retry_buried();

`Queuety::purge( $older_than_days )`

Odstráni dokončené úlohy. Vráti počet odstránených úloh.

PHP

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

Fronty

`Queuety::stats( $queue )`

Získa počty úloh zoskupené podľa stavu.

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

Získa všetky úlohy presunuté do úložiska neúspešných úloh.

PHP

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

`Queuety::pause( $queue )`

Pozastaví front, aby ho pracovníci preskakovali.

PHP

Queuety::pause( 'emails' );

`Queuety::resume( $queue )`

Obnoví pozastavený front.

PHP

Queuety::resume( 'emails' );

`Queuety::is_paused( $queue )`

Skontroluje, či je front pozastavený.

PHP

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

Pracovné postupy

`Queuety::workflow( $name )`

Začne vytvárať pracovný postup. Vráti WorkflowBuilder.

PHP

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

Metódy `WorkflowBuilder`

Metóda	Opis
`then( string $handler_class, ?string $name = null )`	Pridá sekvenčný krok. Voliteľný názov umožňuje podmienené vetvenie.
`parallel( array $handler_classes )`	Pridá skupinu paralelných krokov.
`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 )`	Pridá dynamický krok for-each, ktorý v stave pracovného postupu vytvorí jednu vetviacu úlohu pre každú položku.
`repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Vráti sa k predchádzajúcemu pomenovanému kroku, kým sa nezhoduje verejný kľúč stavu alebo trieda `RepeatCondition`.
`repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Vráti sa k predchádzajúcemu pomenovanému kroku, kým sa nezhoduje verejný kľúč stavu alebo trieda `RepeatCondition`.
`run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )`	Pridá krok na spustenie pracovného postupu.
`delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Pridá trvalý krok čakania. Sčítajú sa všetky trvania.
`wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )`	Pridá krok čakania na signál. Voliteľné `match_payload` a `correlation_key` umožňujú ignorovať nesúvisiace udalosti.
`wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Čaká na všetky alebo ľubovoľné z viacerých signálov; umožňuje voliteľné porovnávanie údajov a koreláciu.
`wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Čaká na signál schválenia od človeka.
`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 )`	Čaká na schválenie alebo zamietnutie a uloží štruktúrované údaje o rozhodnutí.
`wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Čaká na signál s ľudským vstupom.
`wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )`	Čaká na dokončenie jedného pracovného postupu alebo pracovného postupu, ktorého ID je uložené vo verejnom stave.
`wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )`	Čaká na dokončenie všetkých, ľubovoľných alebo kvóra viacerých pracovných postupov.
`wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )`	Čaká na už spustenú skupinu pracovných postupov podľa interného kľúča skupiny.
`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 )`	Odoslať jeden pracovný postup najvyššej úrovne pre každú položku za behu a voliteľne označiť spustenú skupinu trvalým kľúčom skupiny.
`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 orientovaný na agentov pre `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 orientovaný na agentov pre `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 orientovaný na agentov pre `wait_for_workflow_group()`.
`version( string $version )`	Označiť definíciu pracovného postupu verziou na úrovni aplikácie, aby ju bolo možné kontrolovať a exportovať.
`idempotency_key( string $key )`	Zabezpečiť trvalé odoslanie pracovného postupu pre kľúč zadaný volajúcim. Opätovné odoslanie s rovnakým kľúčom vráti pôvodné ID pracovného postupu.
`max_transitions( int $max )`	Zlyhať pracovný postup, ak sa dokončí viac než `$max` prechodov krokov.
`max_for_each_items( int $max )`	Zlyhať pracovný postup, ak sa krok `for_each()` pokúsi rozšíriť na viac než `$max` položiek.
`max_state_bytes( int $bytes )`	Zlyhať pracovný postup, ak verejný stav prekročí veľkosť `$bytes`.
`max_cost_units( int $max )`	Zlyhať pracovný postup, ak dokončené kroky spotrebujú viac než `$max` jednotiek nákladov.
`max_started_workflows( int $max )`	Zlyhať pracovný postup pred odoslaním viac než `$max` podriadených pracovných postupov.
`compensate_with( string $handler_class )`	Pripojiť obslužnú rutinu kompenzácie k naposledy pridanému kroku.
`compensate_on_failure()`	Pri zlyhaní pracovného postupu automaticky spustiť kompenzácie dokončených krokov.
`on_queue( string $queue )`	Nastaviť front pre všetky kroky.
`with_priority( Priority $priority )`	Nastaviť prioritu všetkých krokov.
`max_attempts( int $max )`	Nastaviť maximálny počet opakovaní pre každý krok.
`on_cancel( string $handler_class )`	Zaregistrovať triedu obslužnej rutiny na čistenie pri zrušení. Podrobnosti nájdete v časti Zrušenie.
`prune_state_after( int $steps = 2 )`	Povoliť automatické orezávanie stavu. Odstráni výstupy krokov staršie než stanovený limit. Pozrite si časť Orezávanie stavu.
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Nastaviť časový limit pracovného postupu. Sčítajú sa všetky trvania. Pozrite si časť Časové limity.
`on_deadline( string $handler_class )`	Zaregistrovať obslužnú rutinu, ktorá sa zavolá po prekročení časového limitu pracovného postupu. Pozrite si časť Časové limity.
`dispatch( array $initial_payload = [] )`	Odoslať pracovný postup. Vráti jeho ID.

`Queuety::workflow_status( $workflow_id )`

Získať stav pracovného postupu. Vráti objekt WorkflowState alebo 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 navyše sprístupňuje:

waiting_for: názvy signálov alebo ID pracovných postupov, ktoré momentálne blokujú beh
current_step_name: nakonfigurovaný názov aktuálneho kroku, ak je nastavený
wait_mode: aktuálny režim čakania (all, any alebo quorum) počas blokovania
wait_details: ďalšie údaje na kontrolu, napríklad počet zodpovedajúcich a zostávajúcich blokujúcich položiek
definition_version: hodnota nastavená pomocou version(), ak je nastavená
definition_hash: deterministický hash definície pracovného postupu
idempotency_key: trvalý kľúč odoslania, ak je nastavený
budget: nakonfigurované limity a aktuálne využitie, ak sú zapnuté ochranné limity
artifact_count: počet uložených artefaktov pracovného postupu
artifact_keys: kľúče uložených artefaktov na rýchlu kontrolu

`Queuety::retry_workflow( $workflow_id )`

Zopakovať neúspešný pracovný postup od kroku, pri ktorom zlyhal.

PHP

Queuety::retry_workflow( $workflow_id );

Vyvolá RuntimeException, ak už bol pracovný postup po zlyhaní kompenzovaný.

`Queuety::pause_workflow( $workflow_id )`

Pozastaviť spustený pracovný postup. Práca aktuálneho kroku, ktorá už bola zaradená do frontu, sa môže dokončiť, ale ďalšie kroky sa nezaradia do frontu, kým pracovný postup neobnovíte.

PHP

Queuety::pause_workflow( $workflow_id );

`Queuety::resume_workflow( $workflow_id )`

Obnoviť pozastavený pracovný postup.

PHP

Queuety::resume_workflow( $workflow_id );

`Queuety::cancel_workflow( $workflow_id )`

Zrušiť pracovný postup a spustiť všetky zaregistrované obslužné rutiny na čistenie. Nastaví stav na cancelled a odloží všetky čakajúce aj spracúvané úlohy pracovného postupu.

PHP

Queuety::cancel_workflow( $workflow_id );

Vyvolá RuntimeException, ak je pracovný postup už v stave completed alebo cancelled. Podrobnosti nájdete v časti Zrušenie.

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

Vrátiť pracovný postup na predchádzajúci krok a spustiť ho znova odtiaľ. Stav sa obnoví zo záznamu udalostí state_after pre daný krok a nasledujúci krok sa zaradí do frontu.

PHP

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

Vyvolá RuntimeException, ak pre cieľový krok neexistuje zaznamenaný stav. Vyžaduje Záznam udalostí pracovného postupu. Podrobnosti nájdete v časti Cestovanie v čase.

`Queuety::fork_workflow( $workflow_id )`

Vytvoriť z bežiaceho pracovného postupu nezávislú kópiu v jeho aktuálnom stave. Vráti ID nového pracovného postupu.

PHP

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

Rozvetvený pracovný postup má vlastné ID a funguje nezávisle od pôvodného. Podrobnosti nájdete v časti Vetvenie.

`Queuety::export_workflow( $workflow_id )`

Exportovať úplnú históriu vykonávania pracovného postupu ako pole serializovateľné vo formáte JSON. Zahŕňa záznam pracovného postupu, všetky úlohy, udalosti pracovného postupu a záznamy v protokole.

PHP

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

Štruktúru JSON a prípady použitia nájdete v časti Export a opätovné prehratie.

`Queuety::replay_workflow( $data )`

Opätovne prehrať exportovaný pracovný postup v aktuálnom prostredí. Z exportovaných údajov vytvorí nový pracovný postup a vráti jeho ID.

PHP

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

Podrobnosti nájdete v časti Export a opätovné prehratie.

`Queuety::replace_wp_cron()`

Nahradiť vstavaný systém WordPress cron plánovačom od Queuety. Zachytáva wp_schedule_event(), wp_unschedule_event() a wp_get_scheduled_event() a smeruje opakujúce sa udalosti cez pracovníka Queuety.

PHP

Queuety::replace_wp_cron();

Funguje iba po načítaní WordPress. Podrobnosti nájdete v časti WP-CronNáhrada.

`Queuety::restore_wp_cron()`

Obnoviť predvolené správanie WordPress cron odstránením prepojovacích hákov Queuety cron.

PHP

Queuety::restore_wp_cron();

Obmedzenia nájdete v časti WP-CronNáhrada.

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

Odoslať signál pracovného postupu. Ak pracovný postup práve čaká na tento signál, okamžite sa obnoví. V opačnom prípade sa signál uloží a spracuje, keď pracovný postup dospeje k zodpovedajúcemu kroku wait_for_signal.

PHP

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

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

Podrobnosti nájdete v časti Signály pracovného postupu.

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

Sémantický obal okolo signal() pre schvaľovacie postupy.

PHP

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

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

Sémantický obal okolo signal() pre zamietacie postupy.

PHP

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

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

Sémantický obal okolo signal() pre štruktúrovaný vstup od používateľa.

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 = [] )`

Uložiť jeden trvalý artefakt pracovného postupu.

PHP

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

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

Uložiť jeden artefakt pre práve vykonávaný krok pracovného postupu.

PHP

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

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

Načítať jeden uložený artefakt pracovného postupu.

PHP

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

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

Zobraziť zoznam artefaktov pracovného postupu.

PHP

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

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

Odstrániť jeden artefakt pracovného postupu.

PHP

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

Stavové automaty

`Queuety::machine( $name )`

Začať vytvárať stavový automat. Vráti objekt 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 ] );

Metódy `StateMachineBuilder`

Metóda	Popis
`initial( string $state_name )`	Explicitne nastaviť počiatočný stav.
`state( string $state_name, ?StateMachineStatus $terminal_status = null )`	Začať konfigurovať jeden stav.
`action( string\|array $action_class )`	Zaregistrovať akciu vstupu do aktuálneho stavu, ktorá sa zaradí do frontu. Zadajte názov triedy alebo štruktúrovanú definíciu s položkami `class`, `payload` a `config`; `payload` dosiahne `StateAction::handle()` ako `$payload`.
`on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )`	Zaregistrovať jeden prechod udalosti z aktuálneho stavu. Podmienka prijíma rovnaký štruktúrovaný formát ako `action()`.
`on_queue( string $queue )`	Nastaviť front používaný pre akcie stavov zaraďované do frontu.
`with_priority( Priority $priority )`	Nastaviť prioritu akcií stavov zaraďovaných do frontu.
`max_attempts( int $max_attempts )`	Nastaviť limit opakovaní akcií stavov zaraďovaných do frontu.
`version( string $version )`	Označiť definíciu automatu verziou na úrovni aplikácie.
`idempotency_key( string $key )`	Zabezpečiť trvalé odoslanie pre kľúč zadaný volajúcim. Opätovné odoslanie s rovnakým kľúčom vráti pôvodné ID automatu.
`dispatch( array $initial_state = [] )`	Odoslať automat a vrátiť jeho ID.

Triedy akcií pri vstupe do stavu môžu sprístupňovať aj voliteľnú metódu config() s rovnakými kľúčmi pravidiel pre zdroje, aké podporujú kroky pracovného postupu: concurrency_group, concurrency_limit a cost_units.

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

Odoslať serializovaný balík definície stavového automatu. Vo väčšine aplikačného kódu sa uprednostňuje machine()->dispatch(). Táto nízkoúrovňová metóda umožňuje adaptérom spustiť automat bez priamej závislosti od nástroja na jeho vytváranie.

PHP

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

`Queuety::machine_status( $machine_id )`

Získať aktuálny stav automatu. Vráti objekt StateMachineState alebo 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 navyše sprístupňuje:

definition_version
definition_hash
idempotency_key
error_message
current_action
terminal_status

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

Odoslať externú udalosť čakajúcemu automatu.

PHP

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

Údaje udalosti sú dostupné podmienkam prechodu a po prijatí udalosti sa zlúčia s verejným stavom automatu.

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

Zobraziť zoznam trvalo uložených záznamov automatov na kontrolu.

PHP

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

Každý záznam obsahuje ID automatu, názov, stav, aktuálny stavový uzol, verziu definície, hash definície, idempotency kľúč a časové pečiatky životného cyklu.

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

Získať trvalú časovú os udalostí jedného automatu.

PHP

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

Každý záznam udalosti obsahuje: 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 a created_at.

`Queuety::machine_trace( $machine_id )`

Získať normalizovaný balík trasovania na ladenie stavového automatu UI.

PHP

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

Trasovanie obsahuje machine, zoskupené states, surové events, korelované akcie jobs, logs, artifacts a chunks.

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

Získať verejný stav po konkrétnej udalosti trasovania automatu alebo null, ak sa nenájde.

PHP

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

Model životného cyklu a spôsoby použitia nájdete v časti Stavové automaty.

Šablóny pracovných postupov

`Queuety::define_workflow( $name )`

Vytvoriť nástroj na zostavenie pracovného postupu, ktorý sa použije ako šablóna.

PHP

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

`Queuety::register_workflow_template( $builder )`

Zaregistrovať šablónu pracovného postupu.

PHP

Queuety::register_workflow_template( $builder );

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

Odoslať zaregistrovanú šablónu pracovného postupu podľa názvu. Vráti ID pracovného postupu.

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' ],
);

Vyvolá RuntimeException, ak šablóna nie je zaregistrovaná.

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

Odoslať pracovný postup z balíka definície za behu.

Vo väčšine aplikačného kódu sa uprednostňuje run_workflow() alebo workflow()->dispatch(). Táto nízkoúrovňová metóda umožňuje opakovane použiteľným adaptérom odoslať serializovanú definíciu pracovného postupu bez závislosti od interných metód správcu pracovných postupov.

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

Zaregistrovať akciu WordPress, ktorá odošle pracovný postup.

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 môže byť:

názov zaregistrovanej šablóny pracovného postupu
vložený WorkflowBuilder

map, when a idempotency_key sa spúšťajú synchrónne v rámci aktuálnej požiadavky WordPress. Asynchrónne sa po odoslaní spúšťajú iba samotné kroky pracovného postupu.

Úplnú príručku nájdete v časti Spúšťače akcií.

`Queuety::workflow_templates()`

Získať register šablón pracovných postupov.

PHP

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

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

Načítať a zaregistrovať všetky súbory pracovných postupov z adresára. Každý súbor .php má vracať WorkflowBuilder. Vráti počet zaregistrovaných pracovných postupov.

PHP

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

`Queuety::load_workflow_file( $file_path )`

Načítať a zaregistrovať jeden súbor pracovného postupu. Vráti WorkflowTemplate alebo null, ak súbor nevráti nástroj na zostavenie.

PHP

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

Plánovanie

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

Vytvoriť opakovaný plán. Vráti objekt PendingSchedule.

PHP

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

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

Metódy `PendingSchedule`

Metóda	Popis
`every( string $interval )`	Nastaviť výraz intervalu (e.g. `1 hour`, `30 minutes`)
`cron( string $expression )`	Nastaviť päťpolový výraz cron
`overlap( OverlapPolicy $policy )`	Nastaviť pravidlá pre súbehy (predvolené: `Allow`). Pozrite si časť Plánovanie.
`on_queue( string $queue )`	Nastaviť cieľový front (predvolený: `default`)
`id()`	Vynútiť odoslanie a vrátiť ID plánu

`Queuety::scheduler()`

Získať internú inštanciu Scheduler.

PHP

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

Registrácia obslužných rutín

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

Zaregistrovať triedu obslužnej rutiny pod názvom.

PHP

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

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

Automaticky vyhľadať a zaregistrovať triedy obslužných rutín z adresára. Vráti počet zaregistrovaných obslužných rutín.

PHP

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

`Queuety::registry()`

Získať register obslužných rutín.

PHP

$registry = Queuety::registry();

Pozorovateľnosť

`Queuety::logger()`

Získať inštanciu Logger na vyhľadávanie záznamov v protokole.

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

Získať inštanciu Metrics.

PHP

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

`Queuety::webhook_notifier()`

Získať inštanciu WebhookNotifier.

PHP

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

`Queuety::rate_limiter()`

Získať inštanciu RateLimiter.

PHP

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

Vyrovnávacia pamäť

`Queuety::cache()`

Získať inštanciu aktívneho backendu vyrovnávacej pamäte.

PHP

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

`Queuety::set_cache( $cache )`

Prepísať backend vyrovnávacej pamäte. Ak chcete použiť vlastnú implementáciu, zavolajte túto metódu pred Queuety::init().

PHP

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

`QUEUETY_CACHE_TTL`

Predvolená životnosť záznamov vo vyrovnávacej pamäti v sekundách (predvolené: 5). Ak chcete zmeniť predvolenú životnosť používanú internými operáciami vyrovnávacej pamäte, nastavte túto konštantu v wp-config.php.

PHP

define( 'QUEUETY_CACHE_TTL', 10 );

Podrobnosti o backendoch a automatickej detekcii nájdete v časti Ukladanie do vyrovnávacej pamäte.

Záznam udalostí stavového automatu

`Queuety::machine_events()`

Získať inštanciu StateMachineEventLog.

PHP

$log = Queuety::machine_events();

Záznam udalostí pracovného postupu

`Queuety::workflow_events()`

Získať inštanciu WorkflowEventLog.

PHP

$log = Queuety::workflow_events();

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

Získať úplnú časovú os udalostí pracovného postupu. Vráti pole záznamov udalostí zoradených podľa ID.

PHP

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

Každý záznam udalosti obsahuje: 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 (skopírované z error.message), duration_ms a created_at.

`Queuety::workflow_trace( $workflow_id )`

Získať normalizovaný balík trasovania na ladenie pracovného postupu UI.

PHP

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

Trasovanie obsahuje workflow, zoskupené steps, surové events, jobs, logs, artifacts, chunks, signals a wait_dependencies.

`Queuety::trace_input( $input )`

Nastaviť vstup na úrovni aplikácie pre práve vykonávaný krok pracovného postupu.

`Queuety::trace_output( $output )`

Nastaviť výstup na úrovni aplikácie pre práve vykonávaný krok pracovného postupu.

`Queuety::trace_context( array $context )`

Zlúčiť kontext na úrovni aplikácie s práve vykonávaným krokom pracovného postupu.

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

Získať verejný stav po dokončení alebo obnovení konkrétneho kroku pracovného postupu alebo null, ak sa nenájde.

PHP

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

Prípady použitia a príkazy CLI nájdete v časti Záznam udalostí pracovného postupu.

Interné inštancie

Tieto metódy vracajú interné inštancie pre pokročilé prípady použitia.

Metóda	Návratová hodnota	Popis
`Queuety::queue()`	`Queue`	Operácie s frontom (prevzatie, uvoľnenie, odloženie)
`Queuety::worker()`	`Worker`	Ovládanie procesu pracovníka
`Queuety::workflow_manager()`	`Workflow`	Orchestrácia pracovných postupov
`Queuety::machines()`	`StateMachine`	Správa životného cyklu stavových automatov
`Queuety::connection()`	`Connection`	Pripojenie k databáze
`Queuety::batch_manager()`	`BatchManager`	Správa životného cyklu dávok (zrušenie, orezanie)
`Queuety::chunk_store()`	`ChunkStore`	Ukladanie častí pre streamované kroky
`Queuety::machine_events()`	`StateMachineEventLog`	Udalosti trasovania stavového automatu a normalizované balíky trasovania
`Queuety::workflow_events()`	`WorkflowEventLog`	Udalosti trasovania pracovného postupu a normalizované balíky trasovania
`Queuety::resource_manager()`	`ResourceManager`	Profily prijímania úloh pracovníkom, vážené rozpočty a kontrola systémovej pamäte
`Queuety::cache()`	`Cache`	Inštancia backendu vyrovnávacej pamäte

Testovanie

`Queuety::fake()`

Nahradiť front falošnou implementáciou v pamäti na účely testovania. Vráti inštanciu QueueFake, ktorá zaznamenáva odoslané úlohy bez prístupu k databáze. create_batch() zaznamenáva aj falošné metadáta dávok; reťazce sa overujú prostredníctvom jednotlivých odoslaných úloh, ktoré spúšťajú.

PHP

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

`Queuety::reset()`

Obnoviť celý interný stav vrátane falošného frontu. Zavolajte v tearDown().

PHP

Queuety::reset();

Metódy `QueueFake`

Metóda	Popis
`assert_pushed( string $class, ?Closure $callback )`	Overiť, že bola zaradená úloha danej triedy. Voliteľné spätné volanie filtruje podľa údajov úlohy.
`assert_pushed_times( string $class, int $count )`	Overiť, že úloha bola zaradená presne N-krát.
`assert_not_pushed( string $class )`	Overiť, že úloha nebola nikdy zaradená.
`assert_nothing_pushed()`	Overiť, že nebola zaradená žiadna úloha.
`assert_batched( ?Closure $callback )`	Overiť, že bola odoslaná dávka. Voliteľné spätné volanie filtruje podľa údajov dávky.
`pushed( string $class )`	Získať všetky zaznamenané odoslania pre danú triedu. Vráti pole.
`batches()`	Získať všetky zaznamenané dávky. Vráti pole.
`reset()`	Vymazať všetky zaznamenané úlohy a dávky.

Úplné príklady nájdete v časti Testovanie.

Rozhrania

`Handler`

Rozhranie pre jednoduché obslužné rutiny úloh.

PHP

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

config() môže vrátiť queue, max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit a cost_units.

`Step`

Rozhranie pre obslužné rutiny krokov pracovného postupu.

PHP

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

config() môže vrátiť max_attempts, backoff, concurrency_group, concurrency_limit a cost_units.

`Contracts\ForEachHandler`

Rozhranie pre obslužné rutiny dynamických vetiev cyklu for-each.

PHP

namespace Queuety\Contracts;

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

config() môže vrátiť max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit a cost_units.

`Contracts\ForEachReducer`

Voliteľná redukčná funkcia pre výsledky iterácie cez jednotlivé prvky.

PHP

namespace Queuety\Contracts;

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

`Contracts\Compensation`

Rozhranie pre obslužné rutiny kompenzácie krokov.

PHP

namespace Queuety\Contracts;

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

`Contracts\RepeatCondition`

Rozhranie pre predikáty cyklov používané v repeat_until() a repeat_while(), keď je porovnanie kľúčov stavu príliš obmedzené.

PHP

namespace Queuety\Contracts;

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

`Contracts\StateAction`

Rozhranie pre akcie vstupu do stavu vo fronte.

PHP

namespace Queuety\Contracts;

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

$payload obsahuje štruktúrované payload z definície akcie, ak bol takto definovaný stavový automat. Vráťte verejné aktualizácie stavu. Ak sa má akcia okamžite presunúť do ďalšieho stavu, zahrňte _event a voliteľne aj _event_payload.

Akcie stavu môžu definovať aj voliteľnú metódu config(). Queuety z nej načíta concurrency_group, concurrency_limit a cost_units pri zaradení vstupnej akcie do frontu.

`Contracts\StateGuard`

Rozhranie pre ochranné podmienky prechodov stavového automatu.

PHP

namespace Queuety\Contracts;

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

`Contracts\Job`

Rozhranie pre samostatné triedy úloh, ktoré možno odosielať. Triedy úloh zapuzdrujú svoje dáta vo verejných vlastnostiach a logiku vykonávania v handle().

PHP

namespace Queuety\Contracts;

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

Triedy úloh môžu voliteľne definovať metódu middleware(), ktorá vracia pole inštancií Contracts\Middleware.

`Contracts\Cache`

Rozhranie pre vyrovnávacie úložiská. Vstavané implementácie a vlastné úložiská nájdete v časti Ukladanie do vyrovnávacej pamäte.

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

Metóda	Vracia	Opis
`get( $key )`	`mixed`	Načíta hodnotu. Ak sa hodnota nenájde alebo jej platnosť vypršala, vráti `null`.
`set( $key, $value, $ttl )`	`void`	Uloží hodnotu. TTL 0 znamená, že platnosť nevyprší.
`delete( $key )`	`void`	Odstráni hodnotu.
`has( $key )`	`bool`	Overí, či kľúč existuje a jeho platnosť nevypršala.
`add( $key, $value, $ttl )`	`bool`	Atómové nastavenie iba v prípade, že hodnota ešte neexistuje. Ak sa hodnota nastavila, vráti `true`.
`flush()`	`void`	Odstráni všetky položky z vyrovnávacej pamäte.

`WorkflowEventLog`

Zaznamenáva prechody medzi krokmi pracovného postupu vrátane úplného kontextu trasovania. Prístup cez Queuety::workflow_events().

Metóda	Vracia	Opis
`record_event( array $event )`	`void`	Zaznamená surovú udalosť trasovania
`record_step_started( ... )`	`void`	Zaznamená udalosť step_started so vstupom a stavom pred vykonaním
`record_step_completed( ... )`	`void`	Zaznamená udalosť step_completed so vstupom, výstupom, stavom pred vykonaním a po ňom
`record_step_failed( ... )`	`void`	Zaznamená udalosť step_failed s kontextom trasovania a štruktúrovanými podrobnosťami o chybe
`get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )`	`array`	Získa udalosti trasovania pracovného postupu v poradí, prípadne s podporou stránkovania
`get_trace( int $workflow_id )`	`array`	Získa normalizovaný balík trasovania
`get_state_at_step( int $workflow_id, int $step_index )`	`array\|null`	Získa verejný stav po dokončení alebo obnovení konkrétneho kroku
`prune( int $older_than_days )`	`int`	Odstráni udalosti staršie než zadaný počet dní. Vráti počet odstránených riadkov.

`StateMachineEventLog`

Zaznamenáva udalosti životného cyklu stavového automatu, akcií, prechodov a ochranných podmienok s rovnakými poľami trasovania ako udalosti pracovného postupu.

Metóda	Vracia	Opis
`record_event( array $event )`	`void`	Zaznamená surovú udalosť trasovania stavového automatu
`get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )`	`array`	Získa udalosti trasovania stavového automatu v poradí, prípadne s podporou stránkovania
`get_trace( int $machine_id )`	`array`	Získa normalizovaný balík trasovania stavového automatu
`get_state_at_event( int $machine_id, int $event_id )`	`array\|null`	Získa verejný stav po konkrétnej udalosti trasovania stavového automatu
`prune( int $older_than_days )`	`int`	Odstráni udalosti staršie než zadaný počet dní. Vráti počet odstránených riadkov.

`Contracts\StreamingStep`

Rozhranie pre obslužné rutiny krokov pracovného postupu, ktoré vytvárajú prúd častí. Každá vygenerovaná hodnota sa okamžite uloží do databázy. Pozrite si Prúdové kroky.

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

Metóda	Opis
`stream( $state, $existing_chunks )`	Generátor, ktorý vytvára časti reťazca. Každé vytvorenie časti spustí okamžitý zápis do databázy. Pri opakovanom pokuse obsahuje `$existing_chunks` predtým uložené časti.
`on_complete( $chunks, $state )`	Volá sa po skončení prúdu. Vráti údaje, ktoré sa zlúčia so stavom pracovného postupu.
`config()`	Voliteľná konfigurácia. Podporuje `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` a `cost_units`.

`ChunkStore`

Spravuje ukladanie častí pri prúdových krokoch. Prístup cez Queuety::chunk_store().

Metóda	Vracia	Opis
`get_chunks( int $job_id )`	`string[]`	Načíta všetky časti úlohy zoradené podľa indexu časti
`append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )`	`void`	Pridá jednu časť
`clear_chunks( int $job_id )`	`void`	Odstráni všetky časti úlohy
`chunk_count( int $job_id )`	`int`	Spočíta časti úlohy
`get_accumulated( int $job_id )`	`string`	Spojí všetky časti do jedného reťazca

`Heartbeat`

Statická pomocná trieda na odosielanie signálov aktivity z obslužných rutín krokov a prúdových krokov. Pozrite si Signály aktivity.

Metóda	Opis
`Heartbeat::init( int $job_id, Connection $conn )`	Nastaví kontext úlohy. Pracovník ju zavolá automaticky.
`Heartbeat::beat( array $progress = [] )`	Odošle signál aktivity. Aktualizuje `reserved_at` a voliteľne uloží údaje o priebehu do `heartbeat_data`.
`Heartbeat::clear()`	Vymaže kontext úlohy. Pracovník ju zavolá automaticky.
`Heartbeat::current_job_id()`	Získa aktuálne ID úlohy (na testovanie).

`Contracts\Middleware`

Rozhranie pre middleware úloh. Middleware obaluje vykonávanie úloh do reťazového spracovateľského toku.

PHP

namespace Queuety\Contracts;

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

Vlastnosti

`Dispatchable`

Poskytuje statické metódy na odosielanie úloh pre triedy úloh implementujúce Contracts\Job. Argumenty konštruktora sa odovzdajú na vytvorenie inštancie úlohy.

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

Metóda	Vracia	Opis
`dispatch( ...$args )`	`PendingJob`	Vytvorí inštanciu a odošle ju
`dispatch_if( bool $condition, ...$args )`	`PendingJob\|null`	Odošle úlohu iba vtedy, ak je `$condition` pravdivé
`dispatch_unless( bool $condition, ...$args )`	`PendingJob\|null`	Odošle úlohu iba vtedy, ak je `$condition` nepravdivé
`with_chain( array $jobs )`	`ChainBuilder`	Spustí reťazec úloh z tejto triedy

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

Vlastnosti úloh

Triedy úloh môžu deklarovať verejné vlastnosti, ktoré pracovník číta pomocou reflexie na účely prepísania správania pri opakovaných pokusoch a časových limitoch.

Vlastnosť	Typ	Opis
`$tries`	`int`	Maximálny počet pokusov, po ktorom sa úloha odloží
`$timeout`	`int`	Maximálny čas vykonávania v sekundách (vyžaduje `pcntl`)
`$backoff`	`array`	Postupne sa predlžujúce oneskorenia v sekundách pre každý opakovaný pokus

PHP

class ImportProductsJob implements Job {
    use Dispatchable;

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

    // ...
}

Hook `failed()`

Keď sa úloha po vyčerpaní všetkých opakovaných pokusov odloží, pracovník zavolá metódu failed() na inštancii úlohy, ak je definovaná.

PHP

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

Vstavaný middleware

Všetky triedy middleware implementujú Contracts\Middleware a nachádzajú sa v mennom priestore Queuety\Middleware.

Trieda	Opis
`RateLimited( int $max, int $window )`	Vynúti limit `$max` vykonaní za `$window` sekúnd
`Timeout( int $seconds )`	Ukončí úlohu po `$seconds` sekundách (vyžaduje `pcntl`)
`UniqueJob( ?string $key )`	Zabráni súbežnému vykonávaniu pomocou zámku databázy
`WithoutOverlapping( string $key, int $release_after )`	Zabráni prekrývaniu vykonávania s automatickým vypršaním platnosti zámku
`ThrottlesExceptions( int $max_attempts, int $decay_minutes )`	Obmedzí výnimky, aby pri výpadku externej služby nedošlo k návalu úloh

Podrobnosti o použití a príklady nájdete v časti Middleware.

Výčtové typy

`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';
}

Podrobnosti o fungovaní jednotlivých politík nájdete v časti Plánovanie.

Atribúty

`#[QueuetyHandler]`

PHP 8 atribút na automatickú registráciu. Pozrite si PHP Atribúty.

PHP

use Queuety\Attributes\QueuetyHandler;

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

Mostík CLI

`Queuety::cli_command()`

Vráti zverejnený názov koreňového príkazu WP-CLI.

Predvolený koreňový príkaz je queuety. Ak sa má príkaz zverejniť pod iným názvom, definujte QUEUETY_CLI_COMMAND pred spustením Queuety.

`Queuety::cli_command_map()`

Vráti serializovateľný katalóg príkazov Queuety CLI pre testovacie prostredia, ktoré potrebujú poznať dostupné príkazy bez prehľadávania tried WP-CLI.

Každá položka obsahuje:

stabilné ID operácie
relatívnu cestu CLI
triedu a metódu obslužnej rutiny WP-CLI
možné ciele vykonania
adaptér, ktorý normalizuje nespracované argumenty CLI na plán vykonávania

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

Premení analyzované vyvolanie CLI na plán vykonávania, ktorý má testovacie prostredie spustiť.

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

Plány vykonávania zohľadňujú prenosové vrstvy:

príkazy sa namapujú na verejne dostupné funkcie PHP s normalizovanými argumentmi
katalóg vopred uvádza všetky možné ciele vykonania, zatiaľ čo callable a transport určujú vetvu zvolenú pre analyzovaný vstup

Toto je štandardné použitie Queuety pre testovacie prostredia agentov: stabilné ID operácie, verejný cieľ API a normalizácia v správe adaptéra pre záležitosti špecifické pre CLI, ako sú predvolené hodnoty frontu, dekódovanie dát JSON, výber vetvy fondu pracovníkov a spracovanie súborov pri exporte pracovného postupu.

PHP API

Samostatný prístup k jadru

Queuety::init( Connection $conn )

Queuety::ensure_schema()

Úlohy

Queuety::dispatch( $handler, $payload )

Metódy PendingJob

Queuety::dispatch_sync( $handler, $payload )

Queuety::batch( $jobs )

Queuety::create_batch( $jobs )

Metódy BatchBuilder

Queuety::find_batch( $id )

Riadenie pracovníkov

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

Objekt s hodnotou Batch

Queuety::chain( $jobs )

Metódy ChainBuilder

Queuety::retry( $job_id )

Queuety::retry_buried()

Queuety::purge( $older_than_days )

Fronty

Queuety::stats( $queue )

Queuety::buried( $queue )

Queuety::pause( $queue )

Queuety::resume( $queue )

Queuety::is_paused( $queue )

Pracovné postupy

Queuety::workflow( $name )

Metódy 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 )