# PHP API

Visam, kas pieejams Queuety, var piekļūt, izmantojot statisko klasi `Queuety\Queuety`. Tā ir vienīgais ieejas punkts darbu nosūtīšanai, darbplūsmu izveidei, stāvokļu mašīnu vadībai, rindu pārvaldībai un piekļuvei iekšējām apakšsistēmām.

```php
use Queuety\Queuety;
```

## Atsevišķa piekļuve kodolam

Queuety datubāzes izpildvidi var inicializēt ārpus WordPress.

Šis atsevišķais režīms paredzēts orķestrēšanas kodolam:

- darbi un darbplūsmas veicēji (darbplūsmu veicēju pūliem nepieciešamas arī konstantes `DB_HOST`, `DB_NAME`, `DB_USER` un `DB_PASSWORD`; skatiet tālāk)
- darbplūsmas un signāli
- stāvokļu mašīnas un notikumi
- artefakti, žurnāli, metrikas un grafiki

Tas neaizstāj WordPress adapteri. `Queuety::on_action()`,
`replace_wp_cron()`, spraudņa inicializācija un faktiskā `wp queuety ...`
reģistrācijas plūsma joprojām prasa WordPress.

### `Queuety::init( Connection $conn )`

Inicializējiet Queuety, izmantojot tiešu savienojumu ar datubāzi.

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

Neobligātais arguments `table_prefix` katram savienojumam maina Queuety izpildvides daļu tabulu nosaukumos:

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

Tādējādi, piemēram, tabulas `queuety_jobs` nosaukums tiek mainīts uz `wp_themequeue_jobs`.

### `Queuety::ensure_schema()`

Nodrošiniet, ka aktīvajam savienojumam ir pieejamas Queuety izpildlaika tabulas.

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

Pilnu modeli un WordPress robežu skatiet sadaļā [Lietošana atsevišķi](https://queuety.inline0.dev/lv/docs/features/standalone-use).

## Uzdevumi

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

Nosūtiet uzdevumu izpildei. Pieņem vai nu apdarinātāja nosaukuma virkni, vai `Contracts\Job` instanci. Atgriež `PendingJob` veidotāju opciju ķēdēšanai.

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

Ja tiek nodota `Contracts\Job` instance, serializētājs iegūst FQCN kā apdarinātāja nosaukumu un publiskās īpašības kā lietderīgo slodzi. Parametrs `$payload` tiek ignorēts, ja `$handler` ir `Job` instance.

### `PendingJob` metodes

| Metode | Apraksts |
|---|---|
| `on_queue( string $queue )` | Iestatīt mērķa rindu |
| `with_priority( Priority $priority )` | Iestatīt prioritātes līmeni |
| `delay( int $seconds )` | Aizkave, pirms uzdevums kļūst pieejams |
| `max_attempts( int $max )` | Maksimālais atkārtotas mēģināšanas reižu skaits |
| `rate_limit( int $max, int $window )` | Ātruma ierobežojums: maksimālais izpildes reižu skaits laika periodā sekundēs |
| `unique()` | Novērst uzdevuma nosūtīšanu dublikātā |
| `after( int $job_id )` | Gaidīt, līdz vispirms tiek pabeigts cits uzdevums |
| `concurrency_group( string $group, int $limit )` | Ievietot uzdevumu koplietojamā darbplūsmu pieņemšanas grupā |
| `cost_units( int $units )` | Pievienot nosūtīšanai relatīvās izpildes izmaksas metadatus |
| `id()` | Piespiedu kārtā nosūtīt uzdevumu un atgriezt tā ID |

`concurrency_group()` un `cost_units()` ir daļa no plašākā [Resursu pārvaldības](https://queuety.inline0.dev/lv/docs/features/resource-management) modeļa, tāpēc viena un tā pati nosūtīšana var piedalīties skaita ierobežotā vienlaicīgā izpildē, svērtos rindu vai pakalpojumu sniedzēju budžetos un darbplūsmu pieņemšanas heiristikās.

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

Sinhroni izpildīt uzdevumu pašreizējā procesā, nepievienojot to rindai.

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

Uzdevuma metode `handle()` tiek izsaukta tieši. Netiek izveidota datubāzes rinda, netiek iesaistīts darbplūsmu izpildītājs un starpprogrammatūra netiek lietota.

### `Queuety::batch( $jobs )`

Nosūtīt vairākus uzdevumus vienā vairāku rindu INSERT vaicājumā.

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

Izveidot `BatchBuilder` uzdevumu grupas nosūtīšanai ar atzvanīšanas funkcijām un progresa izsekošanu. Pilnu informāciju skatiet sadaļā [Apvienošana paketēs](https://queuety.inline0.dev/lv/docs/features/batching).

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

### `BatchBuilder` metodes

| Metode | Atgriež | Apraksts |
|---|---|---|
| `name( string $name )` | `self` | Iestatīt paketes nosaukumu |
| `on_queue( string $queue )` | `self` | Iestatīt rindu visiem paketes uzdevumiem |
| `then( string $handler_class )` | `self` | Apdarinātājs, kas tiek izsaukts, kad pakete tiek veiksmīgi pabeigta |
| `catch( string $handler_class )` | `self` | Apdarinātājs, kas tiek izsaukts, kad pirmais paketes uzdevums neizdodas |
| `finally( string $handler_class )` | `self` | Apdarinātājs, kas tiek izsaukts, kad pakete tiek pabeigta (veiksmīgi vai neveiksmīgi) |
| `allow_failures()` | `self` | Atļaut izsaukt atzvanīšanas funkciju `then` arī tad, ja ir kļūmes |
| `dispatch()` | `Batch` | Izveidot paketes rindu un visus uzdevumus, atgriezt `Batch` vērtību objektu |

### `Queuety::find_batch( $id )`

Atrast paketi pēc ID. Atgriež `Batch` vērtību objektu vai `null`.

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

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

## Darbplūsmu izpildītāju vadība

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

Tieši palaist vienu darbplūsmu izpildītāja ciklu.

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

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

Tieši palaist fiksēta lieluma darbplūsmu izpildītāju kopu. Nepieciešami paplašinājumi `pcntl` un `posix`. Kopa nolasa konstantes WordPress `DB_HOST`, `DB_NAME`, `DB_USER` un `DB_PASSWORD` savienojumiem pakārtotajos procesos (tikai tabulu prefiksi tiek pārņemti no inicializētā savienojuma), tāpēc definējiet tās, palaižot kopu ārpus WordPress ([#5](https://github.com/inline0/queuety/issues/5)).

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

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

Tieši palaist adaptīvu darbplūsmu izpildītāju kopu. Prasības ir tādas pašas kā `run_worker_pool()`.

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

### `Batch` vērtību objekts

| Metode/īpašība | Tips | Apraksts |
|---|---|---|
| `$id` | `int` | Paketes ID |
| `$name` | `string\|null` | Neobligāts paketes nosaukums |
| `$total_jobs` | `int` | Kopējais uzdevumu skaits paketē |
| `$pending_jobs` | `int` | Uzdevumi, kas vēl gaida izpildi |
| `$failed_jobs` | `int` | Neveiksmīgo uzdevumu skaits |
| `$failed_job_ids` | `array` | Neveiksmīgo uzdevumu ID |
| `$created_at` | `DateTimeImmutable` | Paketes izveides laiks |
| `$finished_at` | `DateTimeImmutable\|null` | Paketes pabeigšanas laiks |
| `$cancelled_at` | `DateTimeImmutable\|null` | Paketes atcelšanas laiks |
| `progress()` | `int` | Pabeigšanas procentuālā daļa (0–100) |
| `finished()` | `bool` | Vai pakete ir pabeigta |
| `has_failures()` | `bool` | Vai kāds uzdevums neizdevās |
| `cancelled()` | `bool` | Vai pakete tika atcelta |

### `Queuety::chain( $jobs )`

Izveidot `ChainBuilder` secīgai uzdevumu izpildei. Katrs uzdevums ir atkarīgs no tā, vai iepriekšējais uzdevums ir veiksmīgi pabeigts.

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

### `ChainBuilder` metodes

| Metode | Atgriež | Apraksts |
|---|---|---|
| `on_queue( string $queue )` | `self` | Iestatīt rindu visiem ķēdes uzdevumiem |
| `catch( string $handler_class )` | `self` | Apdarinātājs, kas tiek izsaukts, ja kāds ķēdes uzdevums tiek neatgriezeniski apglabāts |
| `dispatch()` | `int` | Izveidot visus uzdevumus ar secīgām atkarībām, atgriezt pirmā uzdevuma ID |

### `Queuety::retry( $job_id )`

Atkārtoti mēģināt izpildīt noteiktu uzdevumu. Atiestata tā statusu uz `pending`.

```php
Queuety::retry( 42 );
```

### `Queuety::retry_buried()`

Atkārtoti mēģināt izpildīt visus apglabātos uzdevumus. Atgriež atkārtoti mēģināto uzdevumu skaitu.

```php
$count = Queuety::retry_buried();
```

### `Queuety::purge( $older_than_days )`

Iztīrīt pabeigtos uzdevumus. Atgriež iztīrīto uzdevumu skaitu.

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

## Rindas

### `Queuety::stats( $queue )`

Iegūt uzdevumu skaitu, sagrupētu pēc statusa.

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

Iegūt visus apglabātos uzdevumus.

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

### `Queuety::pause( $queue )`

Pauzēt rindu, lai darbplūsmu izpildītāji to izlaistu.

```php
Queuety::pause( 'emails' );
```

### `Queuety::resume( $queue )`

Atsākt pauzētas rindas darbību.

```php
Queuety::resume( 'emails' );
```

### `Queuety::is_paused( $queue )`

Pārbaudīt, vai rinda ir pauzēta.

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

## Darbplūsmas

### `Queuety::workflow( $name )`

Sākt veidot darbplūsmu. Atgriež `WorkflowBuilder`.

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

### `WorkflowBuilder` metodes

| Metode | Apraksts |
|---|---|
| `then( string $handler_class, ?string $name = null )` | Pievienot secīgu soli. Nosaukums ir neobligāts un paredzēts nosacījuma atzarojumiem. |
| `parallel( array $handler_classes )` | Pievienot paralēlu soļu grupu. |
| `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 )` | Pievienot dinamisku for-each soli, kas katram darbplūsmas stāvokļa vienumam izveido atsevišķu atzara uzdevumu. |
| `repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Pāriet atpakaļ uz agrāku nosauktu soli, kamēr atbilst publiska stāvokļa atslēga vai `RepeatCondition` klase. |
| `repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Pāriet atpakaļ uz agrāku nosauktu soli, līdz atbilst publiska stāvokļa atslēga vai `RepeatCondition` klase. |
| `run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )` | Pievienot darbplūsmas palaišanas soli. |
| `delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Pievienot noturīgu aizkaves soli. Tiek summēts visu ilgumu laiks. |
| `wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )` | Pievienot signāla gaidīšanas soli. Neobligātie `match_payload` un `correlation_key` ļauj ignorēt ar gaidīšanu nesaistītus notikumus. |
| `wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Gaidīt vienu vai vairākus signālus, pēc izvēles saskaņojot lietderīgo slodzi un korelāciju. |
| `wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Gaidīt cilvēka apstiprinājuma signālu. |
| `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 )` | Gaidīt apstiprinājumu vai noraidījumu un saglabāt strukturētu lēmuma lietderīgo slodzi. |
| `wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Gaidīt cilvēka ievades signālu. |
| `wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )` | Gaidīt, līdz tiek pabeigta viena darbplūsma pēc ID vai darbplūsma, kuras ID saglabāts publiskajā stāvoklī. |
| `wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )` | Gaidīt, līdz tiek pabeigtas visas, jebkuras vai noteikts kvorums no vairākām darbplūsmām. |
| `wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )` | Gaidīt iepriekš palaistu darbplūsmu grupu pēc iekšējās grupas atslēgas. |
| `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 )` | Nosūtīt vienu augstākā līmeņa darbplūsmu katram izpildlaika vienumam; pēc izvēles sākto darbplūsmu kopai pievienot noturīgas grupas atslēgu. |
| `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 )` | Uz aģentiem orientēts `start_workflows()` aizstājvārds. |
| `wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )` | Uz aģentiem orientēts `wait_for_workflows()` aizstājvārds. |
| `wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )` | Uz aģentiem orientēts `wait_for_workflow_group()` aizstājvārds. |
| `version( string $version )` | Atzīmēt darbplūsmas definīciju ar lietojumprogrammas līmeņa versiju, lai to varētu pārbaudīt un eksportēt. |
| `idempotency_key( string $key )` | Padarīt darbplūsmas nosūtīšanu noturīgu, izmantojot izsaucēja norādītu atslēgu. Atkārtoti nosūtot ar to pašu atslēgu, tiek atgriezts sākotnējais darbplūsmas ID. |
| `max_transitions( int $max )` | Neveiksmīgi pabeigt darbplūsmu, ja tiek pabeigtas vairāk nekā `$max` soļu pārejas. |
| `max_for_each_items( int $max )` | Neveiksmīgi pabeigt darbplūsmu, ja `for_each()` solī tiek mēģināts izvērst vairāk nekā `$max` vienumu. |
| `max_state_bytes( int $bytes )` | Neveiksmīgi pabeigt darbplūsmu, ja publiskais stāvoklis pārsniedz `$bytes`. |
| `max_cost_units( int $max )` | Neveiksmīgi pabeigt darbplūsmu, ja pabeigtie soļi patērē vairāk nekā `$max` izmaksu vienības. |
| `max_started_workflows( int $max )` | Neveiksmīgi pabeigt darbplūsmu, pirms tiek nosūtītas vairāk nekā `$max` pakārtotās darbplūsmas. |
| `compensate_with( string $handler_class )` | Pievienot kompensācijas apdarinātāju pēdējam pievienotajam solim. |
| `compensate_on_failure()` | Automātiski palaist pabeigto soļu kompensācijas, ja darbplūsma neizdodas. |
| `on_queue( string $queue )` | Iestatīt rindu visiem soļiem. |
| `with_priority( Priority $priority )` | Iestatīt prioritāti visiem soļiem. |
| `max_attempts( int $max )` | Iestatīt maksimālo atkārtotas mēģināšanas reižu skaitu katram solim. |
| `on_cancel( string $handler_class )` | Reģistrēt atcelšanas tīrīšanas apdarinātāja klasi. Skatiet sadaļu [Atcelšana](https://queuety.inline0.dev/lv/docs/workflows/cancellation). |
| `prune_state_after( int $steps = 2 )` | Iespējot automātisku stāvokļa apgriešanu. Noņem soļu izvades, kas ir vecākas par norādīto slieksni. Skatiet sadaļu [Stāvokļa apgriešana](https://queuety.inline0.dev/lv/docs/features/state-pruning). |
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Iestatīt darbplūsmas termiņu. Tiek summēts visu ilgumu laiks. Skatiet sadaļu [Termiņi](https://queuety.inline0.dev/lv/docs/workflows/deadlines). |
| `on_deadline( string $handler_class )` | Reģistrēt apdarinātāju, kas tiek izsaukts, kad tiek pārsniegts darbplūsmas termiņš. Skatiet sadaļu [Termiņi](https://queuety.inline0.dev/lv/docs/workflows/deadlines). |
| `dispatch( array $initial_payload = [] )` | Nosūtīt darbplūsmu. Atgriež darbplūsmas ID. |

### `Queuety::workflow_status( $workflow_id )`

Iegūt darbplūsmas statusu. Atgriež `WorkflowState` objektu vai `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` atklāj arī:

- `waiting_for`: signālu nosaukumi vai darbplūsmu ID, kas pašlaik bloķē izpildi
- `current_step_name`: pašreizējā soļa konfigurētais nosaukums, ja tāds ir
- `wait_mode`: pašreizējais gaidīšanas režīms (`all`, `any` vai `quorum`), kamēr izpilde ir bloķēta
- `wait_details`: papildu pārbaudes dati, piemēram, saskaņoto un atlikušo bloķētāju skaits
- `definition_version`: vērtība, ko iestatījis `version()`, ja tāda ir
- `definition_hash`: darbplūsmas definīcijas deterministiska jaucējvērtība
- `idempotency_key`: noturīgās nosūtīšanas atslēga, ja tāda ir
- `budget`: konfigurētie ierobežojumi un pašreizējais lietojums, ja ir iespējoti aizsargmehānismi
- `artifact_count`: saglabāto artefaktu skaits darbplūsmai
- `artifact_keys`: saglabāto artefaktu atslēgas ātrai pārbaudei

### `Queuety::retry_workflow( $workflow_id )`

Atkārtoti mēģināt palaist neveiksmīgu darbplūsmu, sākot ar tās neveiksmīgo soli.

```php
Queuety::retry_workflow( $workflow_id );
```

Ja darbplūsma pēc kļūmes jau ir kompensēta, tiek izmests `RuntimeException`.

### `Queuety::pause_workflow( $workflow_id )`

Pauzēt darbplūsmu, kas tiek izpildīta. Pašreizējā soļa rindā jau iekļautais darbs joprojām var tikt pabeigts, taču nākamie soļi netiek ievietoti rindā, kamēr darbplūsma netiek atsākta.

```php
Queuety::pause_workflow( $workflow_id );
```

### `Queuety::resume_workflow( $workflow_id )`

Atsākt pauzētu darbplūsmu.

```php
Queuety::resume_workflow( $workflow_id );
```

### `Queuety::cancel_workflow( $workflow_id )`

Atcelt darbplūsmu un palaist reģistrētos tīrīšanas apdarinātājus. Iestata statusu uz `cancelled` un apglabā visus darbplūsmas uzdevumus, kas gaida izpildi vai tiek apstrādāti.

```php
Queuety::cancel_workflow( $workflow_id );
```

Ja darbplūsma jau ir `completed` vai `cancelled`, tiek izmests `RuntimeException`. Plašāku informāciju skatiet sadaļā [Atcelšana](https://queuety.inline0.dev/lv/docs/workflows/cancellation).

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

Atgriezt darbplūsmu pie iepriekšējā soļa un atsākt izpildi no tā. Norādītajam solim stāvoklis tiek atjaunots no notikumu žurnāla `state_after`, un tiek ievietots rindā nākamais solis.

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

Ja mērķa solim nav reģistrēta stāvokļa, tiek izmests `RuntimeException`. Nepieciešams [Darbplūsmas notikumu žurnāls](https://queuety.inline0.dev/lv/docs/workflows/event-log). Plašāku informāciju skatiet sadaļā [Ceļošana laikā](https://queuety.inline0.dev/lv/docs/workflows/time-travel).

### `Queuety::fork_workflow( $workflow_id )`

Atzarot izpildāmo darbplūsmu, izveidojot neatkarīgu kopiju tās pašreizējā stāvoklī. Atgriež jaunās darbplūsmas ID.

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

Atzarotajai darbplūsmai ir savs ID, un tā darbojas neatkarīgi no sākotnējās darbplūsmas. Plašāku informāciju skatiet sadaļā [Atzarošana](https://queuety.inline0.dev/lv/docs/workflows/forking).

### `Queuety::export_workflow( $workflow_id )`

Eksportēt pilnu darbplūsmas izpildes vēsturi kā JSON serializējamu masīvu. Ietver darbplūsmas rindu, visus uzdevumus, darbplūsmas notikumus un žurnāla ierakstus.

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

Informāciju par JSON struktūru un lietojumiem skatiet sadaļā [Eksportēšana un atkārtota atskaņošana](https://queuety.inline0.dev/lv/docs/workflows/export-replay).

### `Queuety::replay_workflow( $data )`

Atkārtoti atskaņot eksportētu darbplūsmu pašreizējā vidē. Izveido jaunu darbplūsmu no eksporta datiem un atgriež jaunās darbplūsmas ID.

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

Plašāku informāciju skatiet sadaļā [Eksportēšana un atkārtota atskaņošana](https://queuety.inline0.dev/lv/docs/workflows/export-replay).

### `Queuety::replace_wp_cron()`

Aizstāt iebūvēto WordPress cron sistēmu ar Queuety plānotāju. Pārtver `wp_schedule_event()`, `wp_unschedule_event()` un `wp_get_scheduled_event()` un novirza periodiskos notikumus caur darbplūsmu izpildītāju Queuety.

```php
Queuety::replace_wp_cron();
```

Darbojas tikai tad, ja ir ielādēts WordPress. Plašāku informāciju skatiet sadaļā [WP-Cron aizstāšana](https://queuety.inline0.dev/lv/docs/features/wp-cron).

### `Queuety::restore_wp_cron()`

Atjaunot WordPress noklusējuma cron darbību, noņemot Queuety cron tilta āķus.

```php
Queuety::restore_wp_cron();
```

Ierobežojumus skatiet sadaļā [WP-Cron aizstāšana](https://queuety.inline0.dev/lv/docs/features/wp-cron).

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

Nosūtīt signālu darbplūsmai. Ja darbplūsma pašlaik gaida šo signālu, tā uzreiz atsāk izpildi. Citādi signāls tiek saglabāts un izmantots, kad darbplūsma sasniedz atbilstošo `wait_for_signal` soli.

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

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

Plašāku informāciju skatiet sadaļā [Darbplūsmas signāli](https://queuety.inline0.dev/lv/docs/workflows/signals).

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

Semantiskais iesaiņotājs ap `signal()` apstiprināšanas plūsmām.

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

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

Semantiskais iesaiņotājs ap `signal()` noraidīšanas plūsmām.

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

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

Semantiskais iesaiņotājs ap `signal()` strukturētai cilvēka ievadei.

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

Saglabāt vienu noturīgu darbplūsmas artefaktu.

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

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

Saglabāt vienu pašlaik izpildāmā darbplūsmas soļa artefaktu.

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

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

Ielādēt vienu saglabātu darbplūsmas artefaktu.

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

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

Uzskaitīt darbplūsmas artefaktus.

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

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

Dzēst vienu darbplūsmas artefaktu.

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

## Stāvokļu mašīnas

### `Queuety::machine( $name )`

Sākt veidot stāvokļu mašīnu. Atgriež `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 ] );
```

### `StateMachineBuilder` metodes

| Metode | Apraksts |
|---|---|
| `initial( string $state_name )` | Skaidri iestatīt sākotnējo stāvokli. |
| `state( string $state_name, ?StateMachineStatus $terminal_status = null )` | Sākt viena stāvokļa konfigurēšanu. |
| `action( string\|array $action_class )` | Reģistrēt rindā ievietotu darbību pašreizējam stāvoklim. Norādīt klases nosaukumu vai strukturētu definīciju ar `class`, `payload` un `config`; `payload` tiek nodots `StateAction::handle()` kā `$payload`. |
| `on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )` | Reģistrēt vienu pāreju uz notikumu no pašreizējā stāvokļa. Nosacījums pieņem tādu pašu strukturētu formu kā `action()`. |
| `on_queue( string $queue )` | Iestatīt rindu, ko izmanto rindā ievietotajām stāvokļa darbībām. |
| `with_priority( Priority $priority )` | Iestatīt prioritāti rindā ievietotajām stāvokļa darbībām. |
| `max_attempts( int $max_attempts )` | Iestatīt atkārtojumu limitu rindā ievietotajām stāvokļa darbībām. |
| `version( string $version )` | Pievienot mašīnas definīcijai lietotnes līmeņa versijas marķējumu. |
| `idempotency_key( string $key )` | Padarīt nosūtīšanu noturīgu, izmantojot zvanītāja norādītu atslēgu. Atkārtoti nosūtot ar to pašu atslēgu, tiek atgriezts sākotnējais mašīnas ID. |
| `dispatch( array $initial_state = [] )` | Nosūtīt mašīnu un atgriezt tās ID. |

Stāvokļa ievades darbību klasēm var būt arī izvēles metode `config()` ar tām pašām resursu politikas atslēgām, ko atbalsta darbplūsmas soļi: `concurrency_group`, `concurrency_limit` un `cost_units`.

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

Nosūtīt serializētu stāvokļu mašīnas definīcijas pakotni. Vairumam lietotnes koda ieteicams izmantot `machine()->dispatch()`. Šī zemāka līmeņa metode ļauj adapteriem palaist mašīnu, tieši neizmantojot veidotāju.

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

### `Queuety::machine_status( $machine_id )`

Iegūt pašreizējo mašīnas statusu. Atgriež objektu `StateMachineState` vai `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` piedāvā arī:

- `definition_version`
- `definition_hash`
- `idempotency_key`
- `error_message`
- `current_action`
- `terminal_status`

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

Nosūtīt vienu ārēju notikumu mašīnai, kas gaida.

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

Dati ir pieejami pāreju nosacījumiem, un, pieņemot notikumu, tie tiek apvienoti ar publisko mašīnas stāvokli.

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

Uzskaitīt saglabātās mašīnas rindas pārbaudei.

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

Katrā rindā ir mašīnas ID, nosaukums, statuss, pašreizējais stāvoklis, definīcijas versija, definīcijas jaucējvērtība, idempotences atslēga un dzīves cikla laika zīmogi.

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

Iegūt vienas mašīnas noturīgo notikumu laika skalu.

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

Katrā notikuma rindā ir: `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` un `created_at`.

### `Queuety::machine_trace( $machine_id )`

Iegūt normalizētu izsekojuma pakotni stāvokļu mašīnas atkļūdotājam UI.

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

Izsekojumā ir `machine`, grupēti `states`, neapstrādāti `events`, saistītā darbība `jobs`, `logs`, `artifacts` un `chunks`.

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

Iegūt publisko stāvokli pēc konkrēta mašīnas izsekojuma notikuma vai `null`, ja tas nav atrasts.

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

Dzīves cikla modeli un lietošanas paraugus skatiet sadaļā [Stāvokļu mašīnas](https://queuety.inline0.dev/lv/docs/state-machines).

## Darbplūsmu veidnes

### `Queuety::define_workflow( $name )`

Izveidot darbplūsmas veidotāju, ko izmantot kā veidni.

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

### `Queuety::register_workflow_template( $builder )`

Reģistrēt darbplūsmas veidni.

```php
Queuety::register_workflow_template( $builder );
```

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

Nosūtīt reģistrētu darbplūsmas veidni pēc nosaukuma. Atgriež darbplūsmas ID.

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

Ja veidne nav reģistrēta, tiek izraisīts `RuntimeException`.

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

Nosūtīt darbplūsmu no izpildlaika definīcijas pakotnes.

Vairumam lietotnes koda ieteicams izmantot `run_workflow()` vai `workflow()->dispatch()`. Šī zemāka līmeņa metode ļauj atkārtoti izmantojamiem adapteriem nosūtīt serializētu darbplūsmas definīciju, neizmantojot iekšējās darbplūsmu pārvaldnieka metodes.

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

Reģistrēt WordPress darbību, kas nosūta darbplūsmu.

```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` var būt:

- reģistrētas darbplūsmas veidnes nosaukums
- iekļauta `WorkflowBuilder`

`map`, `when` un `idempotency_key` tiek izpildīti sinhroni pašreizējā WordPress pieprasījuma ietvaros. Asinhroni pēc nosūtīšanas tiek izpildīti tikai darbplūsmas soļi.

Pilnu ceļvedi skatiet sadaļā [Darbību aktivizētāji](https://queuety.inline0.dev/lv/docs/features/action-triggers).

### `Queuety::workflow_templates()`

Iegūt darbplūsmas veidņu reģistru.

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

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

Ielādēt un reģistrēt visus darbplūsmu failus no direktorija. Katram `.php` failam jāatgriež `WorkflowBuilder`. Atgriež reģistrēto darbplūsmu skaitu.

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

### `Queuety::load_workflow_file( $file_path )`

Ielādēt un reģistrēt vienu darbplūsmas failu. Atgriež `WorkflowTemplate` vai `null`, ja fails neatgriež veidotāju.

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

## Plānošana

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

Izveidot periodisku grafiku. Atgriež veidotāju `PendingSchedule`.

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

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

### `PendingSchedule` metodes

| Metode | Apraksts |
|---|---|
| `every( string $interval )` | Iestatīt intervāla izteiksmi (e.g. `1 hour`, `30 minutes`) |
| `cron( string $expression )` | Iestatīt 5 lauku cron izteiksmi |
| `overlap( OverlapPolicy $policy )` | Iestatīt pārklāšanās politiku (noklusējums: `Allow`). Skatiet sadaļu [Plānošana](https://queuety.inline0.dev/lv/docs/features/scheduling). |
| `on_queue( string $queue )` | Iestatīt mērķa rindu (noklusējums: `default`) |
| `id()` | Piespiedu kārtā nosūtīt un atgriezt grafika ID |

### `Queuety::scheduler()`

Iegūt iekšējo `Scheduler` instanci.

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

## Apstrādātāju reģistrēšana

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

Reģistrēt apstrādātāja klasi ar nosaukumu.

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

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

Automātiski atrast un reģistrēt apstrādātāju klases no direktorija. Atgriež reģistrēto apstrādātāju skaitu.

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

### `Queuety::registry()`

Iegūt apstrādātāju reģistru.

```php
$registry = Queuety::registry();
```

## Novērojamība

### `Queuety::logger()`

Iegūt instanci `Logger` žurnāla ierakstu vaicājumu veikšanai.

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

Iegūt instanci `Metrics`.

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

### `Queuety::webhook_notifier()`

Iegūt instanci `WebhookNotifier`.

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

### `Queuety::rate_limiter()`

Iegūt instanci `RateLimiter`.

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

## Kešatmiņa

### `Queuety::cache()`

Iegūt aktīvās kešatmiņas aizmugursistēmas instanci.

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

### `Queuety::set_cache( $cache )`

Aizstāt kešatmiņas aizmugursistēmu. Izsauciet `Queuety::init()` pirms pielāgotas implementācijas izmantošanas.

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

### `QUEUETY_CACHE_TTL`

Noklusējuma kešatmiņas TTL sekundēs (noklusējums: `5`). Iestatiet šo konstanti `wp-config.php`, lai mainītu iekšējo kešatmiņas darbību izmantoto noklusējuma TTL.

```php
define( 'QUEUETY_CACHE_TTL', 10 );
```

Sīkāku informāciju par aizmugursistēmām un automātisko noteikšanu skatiet sadaļā [Kešatmiņas veidošana](https://queuety.inline0.dev/lv/docs/features/caching).

## Stāvokļu mašīnas notikumu žurnāls

### `Queuety::machine_events()`

Iegūt instanci `StateMachineEventLog`.

```php
$log = Queuety::machine_events();
```

## Darbplūsmas notikumu žurnāls

### `Queuety::workflow_events()`

Iegūt instanci `WorkflowEventLog`.

```php
$log = Queuety::workflow_events();
```

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

Iegūt pilnu darbplūsmas notikumu laika skalu. Atgriež notikumu rindu masīvu, kas sakārtots pēc ID.

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

Katrā notikuma rindā ir: `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` (kopēts no `error.message`), `duration_ms` un `created_at`.

### `Queuety::workflow_trace( $workflow_id )`

Iegūt normalizētu izsekojuma pakotni darbplūsmas atkļūdotājam UI.

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

Izsekojumā ir `workflow`, grupēti `steps`, neapstrādāti `events`, `jobs`, `logs`, `artifacts`, `chunks`, `signals` un `wait_dependencies`.

### `Queuety::trace_input( $input )`

Iestatīt lietotnes līmeņa ievaddatus pašlaik izpildāmajam darbplūsmas solim.

### `Queuety::trace_output( $output )`

Iestatīt lietotnes līmeņa izvaddatus pašlaik izpildāmajam darbplūsmas solim.

### `Queuety::trace_context( array $context )`

Apvienot lietotnes līmeņa kontekstu ar pašlaik izpildāmo darbplūsmas soli.

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

Iegūt publisko stāvokli pēc konkrēta darbplūsmas soļa pabeigšanas vai atsākšanas, vai `null`, ja tas nav atrasts.

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

Lietošanas piemērus un CLI komandas skatiet sadaļā [Darbplūsmas notikumu žurnāls](https://queuety.inline0.dev/lv/docs/workflows/event-log).

## Iekšējās instances

Šīs metodes atgriež iekšējās instances izmantošanai īpašos gadījumos.

| Metode | Atgriež | Apraksts |
|---|---|---|
| `Queuety::queue()` | `Queue` | Rindas darbības (pieprasīt, atbrīvot, noglabāt) |
| `Queuety::worker()` | `Worker` | Darbinieka procesa vadība |
| `Queuety::workflow_manager()` | `Workflow` | Darbplūsmas orķestrēšana |
| `Queuety::machines()` | `StateMachine` | Stāvokļu mašīnas dzīves cikla pārvaldība |
| `Queuety::connection()` | `Connection` | Savienojums ar datubāzi |
| `Queuety::batch_manager()` | `BatchManager` | Sēriju dzīves cikla pārvaldība (atcelšana, apgriešana) |
| `Queuety::chunk_store()` | `ChunkStore` | Daļu saglabāšana straumēšanas soļiem |
| `Queuety::machine_events()` | `StateMachineEventLog` | Stāvokļu mašīnas izsekojuma notikumi un normalizētas izsekojuma pakotnes |
| `Queuety::workflow_events()` | `WorkflowEventLog` | Darbplūsmas izsekojuma notikumi un normalizētas izsekojuma pakotnes |
| `Queuety::resource_manager()` | `ResourceManager` | Darbinieku pieņemšanas profili, svērtie budžeti un sistēmas atmiņas pārbaude |
| `Queuety::cache()` | `Cache` | Kešatmiņas aizmugursistēmas instance |

## Testēšana

### `Queuety::fake()`

Aizstāt rindu ar atmiņā esošu testdublikātu. Atgriež instanci `QueueFake`, kas reģistrē nosūtītos uzdevumus, nepiekļūstot datubāzei. `create_batch()` reģistrē arī viltotus sēriju metadatus; ķēdes pārbauda, izmantojot atsevišķi nosūtītos uzdevumus.

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

### `Queuety::reset()`

Atiestatīt visu iekšējo stāvokli, tostarp rindas testdublikātu. Izsauciet testā `tearDown()`.

```php
Queuety::reset();
```

### `QueueFake` metodes

| Metode | Apraksts |
|---|---|
| `assert_pushed( string $class, ?Closure $callback )` | Pārbaudīt, vai uzdevuma klase tika ievietota rindā. Izvēles atzvanfunkcija atlasa pēc uzdevuma datiem. |
| `assert_pushed_times( string $class, int $count )` | Pārbaudīt, vai uzdevums tika ievietots rindā tieši N reizes. |
| `assert_not_pushed( string $class )` | Pārbaudīt, vai uzdevums nekad netika ievietots rindā. |
| `assert_nothing_pushed()` | Pārbaudīt, vai rindā vispār netika ievietots neviens uzdevums. |
| `assert_batched( ?Closure $callback )` | Pārbaudīt, vai sērija tika nosūtīta. Izvēles atzvanfunkcija atlasa pēc sērijas datiem. |
| `pushed( string $class )` | Iegūt visas reģistrētās nosūtīšanas konkrētai klasei. Atgriež masīvu. |
| `batches()` | Iegūt visas reģistrētās sērijas. Atgriež masīvu. |
| `reset()` | Notīrīt visus reģistrētos uzdevumus un sērijas. |

Pilnus piemērus skatiet sadaļā [Testēšana](https://queuety.inline0.dev/lv/docs/features/testing).

## Saskarnes

### `Handler`

Vienkāršu uzdevumu apstrādātāju saskarne.

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

`config()` var atgriezt `queue`, `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` un `cost_units`.

### `Step`

Darbplūsmas soļu apstrādātāju saskarne.

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

`config()` var atgriezt `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` un `cost_units`.

### `Contracts\ForEachHandler`

Dinamisku cikla katram zaru apstrādātāju saskarne.

```php
namespace Queuety\Contracts;

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

`config()` var atgriezt `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` un `cost_units`.

### `Contracts\ForEachReducer`

Izvēles reducētājs cikla katram rezultātiem.

```php
namespace Queuety\Contracts;

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

### `Contracts\Compensation`

Soļu kompensācijas apstrādātāju saskarne.

```php
namespace Queuety\Contracts;

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

### `Contracts\RepeatCondition`

Cikla predikātu saskarne, ko izmanto `repeat_until()` un `repeat_while()`, ja salīdzināšana pēc stāvokļa atslēgas ir pārāk ierobežota.

```php
namespace Queuety\Contracts;

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

### `Contracts\StateAction`

Rindā ievietotu stāvokļa ievades darbību saskarne.

```php
namespace Queuety\Contracts;

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

`$payload` saņem strukturēto `payload` no darbības definīcijas, ja mašīna tika definēta ar šādu. Atgrieziet publiskā stāvokļa atjauninājumus. Iekļaujiet `_event` un pēc izvēles `_event_payload`, ja darbībai nekavējoties jāizraisa pāreja.

Stāvokļa darbībām var būt arī izvēles metode `config()`. Queuety nolasa no tās `concurrency_group`, `concurrency_limit` un `cost_units`, kad ievades darbība tiek ievietota rindā.

### `Contracts\StateGuard`

Stāvokļu mašīnas pāreju nosacījumu saskarne.

```php
namespace Queuety\Contracts;

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

### `Contracts\Job`

Pašpietiekamu nosūtāmu uzdevumu klašu saskarne. Uzdevumu klases iekapsulē datus kā publiskus rekvizītus, bet izpildes loģiku — `handle()`.

```php
namespace Queuety\Contracts;

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

Uzdevumu klasēs pēc izvēles var definēt metodi `middleware()`, kas atgriež instanču `Contracts\Middleware` masīvu.

### `Contracts\Cache`

Kešatmiņas aizmugursistēmu saskarne. Iebūvētās implementācijas un pielāgotās aizmugursistēmas skatiet sadaļā [Kešatmiņas veidošana](https://queuety.inline0.dev/lv/docs/features/caching).

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

| Metode | Atgriež | Apraksts |
|---|---|---|
| `get( $key )` | `mixed` | Iegūt vērtību. Atgriež `null`, ja tā nav atrasta vai tās derīguma termiņš ir beidzies. |
| `set( $key, $value, $ttl )` | `void` | Saglabāt vērtību. TTL 0 nozīmē, ka tā derīguma termiņš nebeidzas. |
| `delete( $key )` | `void` | Noņemt vērtību. |
| `has( $key )` | `bool` | Pārbaudīt, vai atslēga pastāv un tās derīguma termiņš nav beidzies. |
| `add( $key, $value, $ttl )` | `bool` | Atomāri iestatīt, ja vērtības nav. Atgriež `true`, ja vērtība tika iestatīta. |
| `flush()` | `void` | Noņemt visus vienumus no kešatmiņas. |

### `WorkflowEventLog`

Reģistrē darbplūsmas soļu pārejas ar pilnu izsekojuma kontekstu. Pieejams, izmantojot `Queuety::workflow_events()`.

| Metode | Atgriež | Apraksts |
|---|---|---|
| `record_event( array $event )` | `void` | Reģistrēt neapstrādātu izsekojuma notikumu |
| `record_step_started( ... )` | `void` | Reģistrēt step_started notikumu ar ievaddatiem un stāvokli pirms izpildes |
| `record_step_completed( ... )` | `void` | Reģistrēt step_completed notikumu ar ievaddatiem, izvaddatiem, stāvokli pirms un pēc izpildes |
| `record_step_failed( ... )` | `void` | Reģistrēt step_failed notikumu ar izsekojuma kontekstu un strukturētu kļūdas informāciju |
| `get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )` | `array` | Iegūt darbplūsmas izsekojuma notikumus secībā, pēc izvēles izmantojot lappušu dalījumu |
| `get_trace( int $workflow_id )` | `array` | Iegūt normalizētu izsekojuma pakotni |
| `get_state_at_step( int $workflow_id, int $step_index )` | `array\|null` | Iegūt publisko stāvokli pēc konkrēta soļa pabeigšanas vai atsākšanas |
| `prune( int $older_than_days )` | `int` | Dzēst notikumus, kas vecāki par norādīto dienu skaitu. Atgriež izdzēsto rindu skaitu. |

### `StateMachineEventLog`

Reģistrē stāvokļu mašīnas dzīves cikla, darbību, pāreju un nosacījumu notikumus, izmantojot tos pašus izsekojuma laukus kā darbplūsmas notikumiem.

| Metode | Atgriež | Apraksts |
|---|---|---|
| `record_event( array $event )` | `void` | Reģistrēt neapstrādātu mašīnas izsekojuma notikumu |
| `get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )` | `array` | Iegūt mašīnas izsekojuma notikumus secībā, pēc izvēles izmantojot lappušu dalījumu |
| `get_trace( int $machine_id )` | `array` | Iegūt normalizētu mašīnas izsekojuma pakotni |
| `get_state_at_event( int $machine_id, int $event_id )` | `array\|null` | Iegūt publisko stāvokli pēc konkrēta mašīnas izsekojuma notikuma |
| `prune( int $older_than_days )` | `int` | Dzēst notikumus, kas vecāki par norādīto dienu skaitu. Atgriež izdzēsto rindu skaitu. |

### `Contracts\StreamingStep`

Darbplūsmas soļu apstrādātāju saskarne, kas ģenerē daļu straumi. Katra ģenerētā vērtība tiek nekavējoties saglabāta datubāzē. Skatiet sadaļu [Straumēšanas soļi](https://queuety.inline0.dev/lv/docs/workflows/streaming).

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

| Metode | Apraksts |
|---|---|
| `stream( $state, $existing_chunks )` | Ģenerators, kas izvada virknes daļas. Katra izvade izraisa tūlītēju ierakstu datubāzē. Atkārtotas izpildes laikā `$existing_chunks` ir iepriekš saglabātās daļas. |
| `on_complete( $chunks, $state )` | Tiek izsaukta pēc straumes pabeigšanas. Atgriež datus, kas jāapvieno ar darbplūsmas stāvokli. |
| `config()` | Izvēles konfigurācija. Atbalsta `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` un `cost_units`. |

### `ChunkStore`

Pārvalda daļu saglabāšanu straumēšanas soļiem. Pieejams, izmantojot `Queuety::chunk_store()`.

| Metode | Atgriež | Apraksts |
|---|---|---|
| `get_chunks( int $job_id )` | `string[]` | Iegūt visas uzdevuma daļas, sakārtotas pēc daļas indeksa |
| `append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )` | `void` | Pievienot vienu daļu |
| `clear_chunks( int $job_id )` | `void` | Dzēst visas uzdevuma daļas |
| `chunk_count( int $job_id )` | `int` | Saskaitīt uzdevuma daļas |
| `get_accumulated( int $job_id )` | `string` | Savienot visas daļas vienā virknē |

### `Heartbeat`

Statisks palīgrīks aktivitātes signālu sūtīšanai no soļu apstrādātājiem un straumēšanas soļiem. Skatiet sadaļu [Aktivitātes signāli](https://queuety.inline0.dev/lv/docs/features/heartbeats).

| Metode | Apraksts |
|---|---|
| `Heartbeat::init( int $job_id, Connection $conn )` | Iestatīt uzdevuma kontekstu. Darbinieks to izsauc automātiski. |
| `Heartbeat::beat( array $progress = [] )` | Nosūtīt aktivitātes signālu. Atjaunina `reserved_at` un pēc izvēles saglabā progresa datus `heartbeat_data`. |
| `Heartbeat::clear()` | Notīrīt uzdevuma kontekstu. Darbinieks to izsauc automātiski. |
| `Heartbeat::current_job_id()` | Iegūt pašreizējā uzdevuma ID (testēšanai). |

### `Contracts\Middleware`

Uzdevumu starpprogrammatūras saskarne. Starpprogrammatūra aptver uzdevuma izpildi sīpola slāņu principā veidotā konveijerā.

```php
namespace Queuety\Contracts;

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

## Pazīmes

### `Dispatchable`

Nodrošina statiskas nosūtīšanas metodes uzdevumu klasēm, kas implementē `Contracts\Job`. Konstruktoram nodotie argumenti tiek izmantoti uzdevuma instances izveidei.

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

| Metode | Atgriež | Apraksts |
|---|---|---|
| `dispatch( ...$args )` | `PendingJob` | Izveidot instanci un nosūtīt to |
| `dispatch_if( bool $condition, ...$args )` | `PendingJob\|null` | Nosūtīt tikai tad, ja `$condition` ir true |
| `dispatch_unless( bool $condition, ...$args )` | `PendingJob\|null` | Nosūtīt tikai tad, ja `$condition` ir false |
| `with_chain( array $jobs )` | `ChainBuilder` | Sākt ķēdi no šīs uzdevumu klases |

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

### Uzdevumu rekvizīti

Uzdevumu klasēs var deklarēt publiskus rekvizītus, kurus darbinieks nolasa ar refleksijas palīdzību, lai mainītu atkārtošanas un noildzes darbību.

| Rekvizīts | Tips | Apraksts |
|---|---|---|
| `$tries` | `int` | Maksimālais mēģinājumu skaits, pirms uzdevums tiek noglabāts |
| `$timeout` | `int` | Maksimālais izpildes laiks sekundēs (nepieciešams `pcntl`) |
| `$backoff` | `array` | Pieaugošas aizkaves vērtības katram atkārtotas izpildes mēģinājumam |

```php
class ImportProductsJob implements Job {
    use Dispatchable;

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

    // ...
}
```

### `failed()` āķis

Kad pēc visu atkārtoto mēģinājumu izsmelšanas uzdevums tiek noglabāts, darbinieks izsauc metodi `failed()` uzdevuma instancē, ja tā ir definēta.

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

## Iebūvētā starpprogrammatūra

Visas starpprogrammatūras klases implementē `Contracts\Middleware` un atrodas `Queuety\Middleware` nosaukumvietā.

| Klase | Apraksts |
|---|---|
| `RateLimited( int $max, int $window )` | Ierobežo izpildes biežumu līdz `$max` reizēm `$window` sekundēs |
| `Timeout( int $seconds )` | Pārtrauc uzdevumu pēc `$seconds` sekundēm (nepieciešams `pcntl`) |
| `UniqueJob( ?string $key )` | Novērš vienlaicīgu izpildi, izmantojot datubāzes bloķēšanu |
| `WithoutOverlapping( string $key, int $release_after )` | Novērš pārklājošos izpildi, automātiski beidzot bloķēšanu |
| `ThrottlesExceptions( int $max_attempts, int $decay_minutes )` | Ierobežo izņēmumu biežumu, lai nepieļautu uzdevumu vētru ārēja pakalpojuma darbības pārtraukuma laikā |

Lietošanas informāciju un piemērus skatiet sadaļā [Starpprogrammatūra](https://queuety.inline0.dev/lv/docs/features/middleware).

## Uzskaitījumi

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

Detalizētu informāciju par katras politikas darbību skatiet sadaļā [Plānošana](https://queuety.inline0.dev/lv/docs/features/scheduling).

## Atribūti

### `#[QueuetyHandler]`

PHP 8 atribūts automātiskai reģistrēšanai. Skatiet [PHP atribūtus](https://queuety.inline0.dev/lv/docs/features/attributes).

```php
use Queuety\Attributes\QueuetyHandler;

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

## CLI tilts

### `Queuety::cli_command()`

Atgriež publicēto WP-CLI saknes komandas nosaukumu.

Noklusētā saknes komanda ir `queuety`. Definējiet `QUEUETY_CLI_COMMAND`, pirms tiek palaists Queuety, ja komanda jāpublicē ar citu nosaukumu.

### `Queuety::cli_command_map()`

Atgriež serializējamu Queuety CLI katalogu vidēm, kurām jāizprot piegādāto komandu kopums, neanalizējot WP-CLI klases.

Katrs ieraksts ietver:
- stabilu operācijas ID
- relatīvo CLI ceļu
- WP-CLI apstrādātāja klasi un metodi
- iespējamos izpildes mērķus
- adapteri, kas normalizē neapstrādātos CLI argumentus izpildes plānā

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

Pārvērš parsētu CLI izsaukumu izpildes plānā, ko videi vajadzētu palaist.

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

Izpildes plānos apzināti ņemts vērā transporta veids:
- komandas tiek sasaistītas ar publiski pieejamām PHP izsaucamām funkcijām ar normalizētiem argumentiem
- katalogā jau sākumā uzskaitīti visi iespējamie izpildes mērķi, savukārt `callable` un `transport` norāda zaru, kas izvēlēts parsētajai ievadei

Šis ir standarta veids, kā Queuety izmanto aģentu izpildvidēs: stabils operācijas ID, publisks API mērķis un adaptera nodrošināta normalizēšana ar CLI saistītām vajadzībām, piemēram, rindas noklusējuma vērtībām, JSON datu dekodēšanai, zaru izvēlei darbinieku kopai un darbplūsmas eksporta failu apstrādei.