# PHP API

Allt i Queuety är tillgängligt via den statiska klassen `Queuety\Queuety`. Den är den enda ingångspunkten för att skicka jobb, bygga arbetsflöden, styra tillståndsmaskiner, hantera köer och komma åt interna delsystem.

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

## Fristående åtkomst till kärnan

Queuetys databasbaserade körmiljö kan initieras utanför WordPress.

Den fristående lösningen gäller orkestreringskärnan:

- jobb och arbetare (arbetarpooler behöver också konstanterna `DB_HOST`, `DB_NAME`, `DB_USER` och `DB_PASSWORD`, se nedan)
- arbetsflöden och signaler
- tillståndsmaskiner och händelser
- artefakter, loggar, mätvärden och scheman

Det är ingen ersättning för adaptern WordPress. `Queuety::on_action()`,
`replace_wp_cron()`, insticksprogrammets uppstart och den riktiga registreringsvägen för `wp queuety ...`
kräver fortfarande WordPress.

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

Initiera Queuety med en direkt databasbaserad anslutning.

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

Det valfria argumentet `table_prefix` ändrar Queuety-delen av körmiljöns
tabellnamn per anslutning:

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

Det gör att tabeller som `queuety_jobs` får namnet `wp_themequeue_jobs`.

### `Queuety::ensure_schema()`

Se till att körmiljöns tabeller Queuety finns för den aktiva anslutningen.

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

Se [Användning fristående](https://queuety.inline0.dev/sv/docs/features/standalone-use) för hela modellen och gränsen för WordPress.

## Jobb

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

Skicka ett jobb. Godtar antingen en sträng med ett hanterarnamn eller en instans av `Contracts\Job`. Returnerar en `PendingJob`-byggare för att kedja ihop alternativ.

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

När en instans av `Contracts\Job` skickas med hämtar serialiseraren FQCN som hanterarnamn och publika egenskaper som nyttolast. Parametern `$payload` ignoreras när `$handler` är en instans av `Job`.

### `PendingJob`-metoder

| Metod | Beskrivning |
|---|---|
| `on_queue( string $queue )` | Ange målkön |
| `with_priority( Priority $priority )` | Ange prioritetsnivån |
| `delay( int $seconds )` | Fördröjning innan jobbet blir tillgängligt |
| `max_attempts( int $max )` | Maximalt antal omförsök |
| `rate_limit( int $max, int $window )` | Hastighetsbegränsning: max antal körningar per tidsfönster i sekunder |
| `unique()` | Förhindra dubbla utskick |
| `after( int $job_id )` | Vänta tills ett annat jobb har slutförts |
| `concurrency_group( string $group, int $limit )` | Placera jobbet i en gemensam grupp för arbetarintag |
| `cost_units( int $units )` | Lägg till metadata om relativ körkostnad för utskicket |
| `id()` | Tvinga igenom utskicket och returnera jobb-ID:t |

`concurrency_group()` och `cost_units()` ingår i den bredare modellen för [Resurshantering](https://queuety.inline0.dev/sv/docs/features/resource-management). Därför kan samma utskick ingå i samtidighetsgränser baserade på antal, viktade kö- eller leverantörsbudgetar och heuristik för arbetarintag.

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

Kör ett jobb synkront i den aktuella processen utan att lägga det i kön.

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

Jobbets metod `handle()` anropas direkt. Ingen databasrad skapas, ingen arbetare medverkar och ingen mellanprogramvara tillämpas.

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

Skicka flera jobb i en enda INSERT med flera rader.

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

Skapa en `BatchBuilder` för att skicka en grupp jobb med återanrop och förloppsspårning. Se [Batchhantering](https://queuety.inline0.dev/sv/docs/features/batching) för fullständig information.

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

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `name( string $name )` | `self` | Ange ett namn för batchen |
| `on_queue( string $queue )` | `self` | Ange kön för alla jobb i batchen |
| `then( string $handler_class )` | `self` | Hanterare som anropas när batchen slutförs utan fel |
| `catch( string $handler_class )` | `self` | Hanterare som anropas när det första jobbet i batchen misslyckas |
| `finally( string $handler_class )` | `self` | Hanterare som anropas när batchen avslutas (med eller utan fel) |
| `allow_failures()` | `self` | Tillåt att återanropet `then` körs även om fel uppstått |
| `dispatch()` | `Batch` | Skapa batchraden och alla jobb, returnerar värdeobjektet `Batch` |

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

Hitta en batch med dess ID. Returnerar ett `Batch`-värdeobjekt eller `null`.

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

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

## Arbetarkontroll

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

Kör en arbetarloop direkt.

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

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

Kör en arbetargrupp med fast storlek direkt. Kräver tilläggen `pcntl` och `posix`. Gruppen läser konstanterna WordPress, `DB_HOST`, `DB_NAME`, `DB_USER` och `DB_PASSWORD` för sina underordnade anslutningar (bara tabellprefixen hämtas från den initierade anslutningen). Definiera därför konstanterna när du kör en pool utanför 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' )`

Kör en adaptiv arbetargrupp direkt. Samma krav som för `run_worker_pool()`.

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

### `Batch`-värdeobjekt

| Metod/egenskap | Typ | Beskrivning |
|---|---|---|
| `$id` | `int` | Batch-ID |
| `$name` | `string\|null` | Valfritt batchnamn |
| `$total_jobs` | `int` | Totalt antal jobb i batchen |
| `$pending_jobs` | `int` | Jobb som fortfarande väntar |
| `$failed_jobs` | `int` | Antal misslyckade jobb |
| `$failed_job_ids` | `array` | ID:n för misslyckade jobb |
| `$created_at` | `DateTimeImmutable` | När batchen skapades |
| `$finished_at` | `DateTimeImmutable\|null` | När batchen avslutades |
| `$cancelled_at` | `DateTimeImmutable\|null` | När batchen avbröts |
| `progress()` | `int` | Slutförandegrad (0–100) |
| `finished()` | `bool` | Om batchen har avslutats |
| `has_failures()` | `bool` | Om något jobb misslyckades |
| `cancelled()` | `bool` | Om batchen avbröts |

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

Skapa en `ChainBuilder` för sekventiell körning av jobb. Varje jobb är beroende av att det föregående slutförs utan fel.

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

### `ChainBuilder`-metoder

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `on_queue( string $queue )` | `self` | Ange kön för alla jobb i kedjan |
| `catch( string $handler_class )` | `self` | Hanterare som anropas när ett jobb i kedjan blir permanent begravt |
| `dispatch()` | `int` | Skapa alla jobb med sekventiella beroenden och returnera det första jobb-ID:t |

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

Försök köra ett specifikt jobb igen. Återställer det till statusen `pending`.

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

### `Queuety::retry_buried()`

Försök köra alla begravda jobb igen. Returnerar antalet jobb som försökts köras igen.

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

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

Rensa slutförda jobb. Returnerar antalet jobb som rensades.

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

## Köer

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

Hämta antal jobb grupperade efter status.

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

Hämta alla begravda jobb.

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

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

Pausa en kö så att arbetarna hoppar över den.

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

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

Återuppta en pausad kö.

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

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

Kontrollera om en kö är pausad.

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

## Arbetsflöden

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

Börja bygga ett arbetsflöde. Returnerar en `WorkflowBuilder`.

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

### `WorkflowBuilder`-metoder

| Metod | Beskrivning |
|---|---|
| `then( string $handler_class, ?string $name = null )` | Lägg till ett sekventiellt steg. Valfritt namn för villkorlig förgrening. |
| `parallel( array $handler_classes )` | Lägg till en parallell steggrupp. |
| `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 )` | Lägg till ett dynamiskt for-each-steg som skapar ett grenjobb per objekt i arbetsflödets tillstånd. |
| `repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Gå tillbaka till ett tidigare namngivet steg medan en publik tillståndsnyckel eller klassen `RepeatCondition` matchar. |
| `repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Gå tillbaka till ett tidigare namngivet steg tills en publik tillståndsnyckel eller klassen `RepeatCondition` matchar. |
| `run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )` | Lägg till ett kör-arbetsflöde-steg. |
| `delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Lägg till ett beständigt fördröjningssteg. Alla varaktigheter summeras. |
| `wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )` | Lägg till ett steg som väntar på en signal. Valfria `match_payload` och `correlation_key` gör att orelaterade händelser kan ignoreras. |
| `wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Vänta på alla eller valfria flera signaler, med valfri nyttolastmatchning och korrelation. |
| `wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Vänta på en signal om mänskligt godkännande. |
| `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 )` | Vänta på antingen godkännande eller avslag och lagra ett strukturerat beslutsvärde. |
| `wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Vänta på en signal med mänsklig inmatning. |
| `wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )` | Vänta på att ett arbetsflödes-ID, eller ett arbetsflödes-ID lagrat i publikt tillstånd, ska slutföras. |
| `wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )` | Vänta på att alla, valfria eller ett kvorum av flera arbetsflöden ska slutföras. |
| `wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )` | Vänta på en tidigare startad arbetsflödesgrupp med dess interna gruppnyckel. |
| `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 )` | Skicka en arbetsflödesprocess på toppnivå per körningsobjekt och tagga vid behov den startade gruppen med en beständig gruppnyckel. |
| `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 )` | Agentinriktat alias för `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 )` | Agentinriktat alias för `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 )` | Agentinriktat alias för `wait_for_workflow_group()`. |
| `version( string $version )` | Tagga arbetsflödesdefinitionen med en version på applikationsnivå för inspektion och exporter. |
| `idempotency_key( string $key )` | Gör utskick av arbetsflödet beständigt för en nyckel som anroparen anger. Ett nytt utskick med samma nyckel returnerar det ursprungliga arbetsflödes-ID:t. |
| `max_transitions( int $max )` | Misslyckas arbetsflödet om fler än `$max` stegövergångar slutförs. |
| `max_for_each_items( int $max )` | Misslyckas arbetsflödet om ett `for_each()`-steg försöker utöka sig till fler än `$max` objekt. |
| `max_state_bytes( int $bytes )` | Misslyckas arbetsflödet om det publika tillståndet växer utöver `$bytes`. |
| `max_cost_units( int $max )` | Misslyckas arbetsflödet om slutförda steg förbrukar mer än `$max` kostnadsenheter. |
| `max_started_workflows( int $max )` | Misslyckas arbetsflödet innan fler än `$max` underordnade arbetsflöden skickas iväg. |
| `compensate_with( string $handler_class )` | Koppla en kompensationshanterare till det senast tillagda steget. |
| `compensate_on_failure()` | Kör kompensationer för slutförda steg automatiskt när arbetsflödet misslyckas. |
| `on_queue( string $queue )` | Ange kön för alla steg. |
| `with_priority( Priority $priority )` | Ange prioriteten för alla steg. |
| `max_attempts( int $max )` | Ange maximalt antal omförsök per steg. |
| `on_cancel( string $handler_class )` | Registrera en klass för en rensningshanterare vid avbrytning. Se [Avbrytning](https://queuety.inline0.dev/sv/docs/workflows/cancellation). |
| `prune_state_after( int $steps = 2 )` | Aktivera automatisk rensning av tillstånd. Tar bort stegresultat som är äldre än tröskelvärdet. Se [Rensning av tillstånd](https://queuety.inline0.dev/sv/docs/features/state-pruning). |
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Ange en tidsfrist för arbetsflödet. Alla tidslängder summeras. Se [Tidsfrister](https://queuety.inline0.dev/sv/docs/workflows/deadlines). |
| `on_deadline( string $handler_class )` | Registrera en hanterare som anropas när arbetsflödets tidsfrist överskrids. Se [Tidsfrister](https://queuety.inline0.dev/sv/docs/workflows/deadlines). |
| `dispatch( array $initial_payload = [] )` | Skicka iväg arbetsflödet. Returnerar arbetsflödets ID. |

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

Hämta arbetsflödets status. Returnerar ett `WorkflowState`-objekt eller `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` visar också:

- `waiting_for`: signalnamnen eller arbetsflödes-ID:na som för närvarande blockerar körningen
- `current_step_name`: det konfigurerade namnet på det aktuella steget, om det finns
- `wait_mode`: det aktuella vänteläget (`all`, `any` eller `quorum`) medan körningen är blockerad
- `wait_details`: extra inspektionsdata, till exempel matchade och återstående blockerare
- `definition_version`: värdet som angetts av `version()`, om det finns
- `definition_hash`: en deterministisk hash av arbetsflödesdefinitionen
- `idempotency_key`: den beständiga utskickningsnyckeln, om det finns
- `budget`: konfigurerade gränser plus aktuell användning, om skyddsräcken är aktiverade
- `artifact_count`: antal lagrade artefakter för arbetsflödet
- `artifact_keys`: lagrade artefaktnycklar för snabb inspektion

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

Försök köra om ett misslyckat arbetsflöde från steget där det misslyckades.

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

Kastar `RuntimeException` om arbetsflödet redan har återställts efter ett fel.

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

Pausa ett arbetsflöde som körs. Arbeten för det aktuella steget som redan ligger i kö kan fortfarande slutföras, men senare steg läggs inte i kön förrän du återupptar arbetsflödet.

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

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

Återuppta ett pausat arbetsflöde.

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

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

Avbryt ett arbetsflöde och kör eventuella registrerade rensningshanterare. Anger statusen till `cancelled` och begraver alla väntande och bearbetade jobb för arbetsflödet.

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

Kastar `RuntimeException` om arbetsflödet redan är `completed` eller `cancelled`. Mer information finns i [Avbrytande](https://queuety.inline0.dev/sv/docs/workflows/cancellation).

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

Spola tillbaka ett arbetsflöde till ett tidigare steg och kör det igen därifrån. Tillståndet återställs från händelseloggen `state_after` för det angivna steget, och nästa steg läggs i kön.

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

Kastar `RuntimeException` om det inte finns något registrerat tillstånd för målsteg. Kräver [Arbetsflödets händelselogg](https://queuety.inline0.dev/sv/docs/workflows/event-log). Mer information finns i [Tidsresa](https://queuety.inline0.dev/sv/docs/workflows/time-travel).

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

Förgrena ett arbetsflöde som körs till en oberoende kopia med dess aktuella tillstånd. Returnerar det nya arbetsflödes-ID:t.

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

Det förgrenade arbetsflödet får ett eget ID och fungerar oberoende av det ursprungliga. Mer information finns i [Förgrening](https://queuety.inline0.dev/sv/docs/workflows/forking).

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

Exportera ett arbetsflödes fullständiga körningshistorik som en JSON-serialiserbar array. Innehåller arbetsflödesraden, alla jobb, arbetsflödeshändelser och loggposter.

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

Se [Export och uppspelning](https://queuety.inline0.dev/sv/docs/workflows/export-replay) för information om strukturen JSON och användningsområden.

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

Spela upp ett exporterat arbetsflöde i den aktuella miljön. Skapar ett nytt arbetsflöde utifrån exportdata och returnerar det nya arbetsflödes-ID:t.

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

Mer information finns i [Export och uppspelning](https://queuety.inline0.dev/sv/docs/workflows/export-replay).

### `Queuety::replace_wp_cron()`

Ersätt det inbyggda systemet för WordPress cron med Queuetys schemaläggare. Fångar upp `wp_schedule_event()`, `wp_unschedule_event()` och `wp_get_scheduled_event()` och dirigerar återkommande händelser via arbetaren Queuety.

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

Fungerar bara när WordPress har laddats. Mer information finns i [WP-Cron-ersättning](https://queuety.inline0.dev/sv/docs/features/wp-cron).

### `Queuety::restore_wp_cron()`

Återställ WordPresss standardbeteende för cron genom att ta bort bryggkrokarna för Queuety cron.

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

Se [WP-Cron-ersättning](https://queuety.inline0.dev/sv/docs/features/wp-cron) för begränsningar.

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

Skicka en signal till ett arbetsflöde. Om arbetsflödet väntar på den här signalen återupptas det omedelbart. Annars lagras signalen och hämtas när arbetsflödet når motsvarande `wait_for_signal`-steg.

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

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

Mer information finns i [Arbetsflödessignaler](https://queuety.inline0.dev/sv/docs/workflows/signals).

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

Semantisk omslutning runt `signal()` för godkännandeflöden.

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

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

Semantisk omslutning runt `signal()` för avvisningsflöden.

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

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

Semantisk omslutning runt `signal()` för strukturerad mänsklig inmatning.

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

Lagra en beständig artefakt för ett arbetsflöde.

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

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

Lagra en artefakt för arbetsflödessteget som körs för närvarande.

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

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

Hämta en lagrad artefakt för ett arbetsflöde.

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

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

Lista artefakter för ett arbetsflöde.

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

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

Ta bort en artefakt för ett arbetsflöde.

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

## Tillståndsmaskiner

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

Börja skapa en tillståndsmaskin. Returnerar en `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 ] );
```

### Metoder för `StateMachineBuilder`

| Metod | Beskrivning |
|---|---|
| `initial( string $state_name )` | Ange starttillståndet uttryckligen. |
| `state( string $state_name, ?StateMachineStatus $terminal_status = null )` | Börja konfigurera ett tillstånd. |
| `action( string\|array $action_class )` | Registrera en köad åtgärd vid inträde i det aktuella tillståndet. Ange ett klassnamn eller en strukturerad definition med `class`, `payload` och `config`; `payload` når `StateAction::handle()` som `$payload`. |
| `on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )` | Registrera en händelseövergång från det aktuella tillståndet. Villkoret godtar samma strukturerade format som `action()`. |
| `on_queue( string $queue )` | Ange kön som används för köade tillståndsåtgärder. |
| `with_priority( Priority $priority )` | Ange prioritet för köade tillståndsåtgärder. |
| `max_attempts( int $max_attempts )` | Ange gränsen för omförsök av köade tillståndsåtgärder. |
| `version( string $version )` | Märk maskindefinitionen med en programversionsbeteckning. |
| `idempotency_key( string $key )` | Gör utskickningen beständig för en nyckel som anges av anroparen. Om du skickar igen med samma nyckel returneras det ursprungliga maskin-ID:t. |
| `dispatch( array $initial_state = [] )` | Skicka iväg maskinen och returnera maskin-ID:t. |

Klasser för tillståndsåtgärder vid inträde kan även ha en valfri `config()`-metod med samma nycklar för resurspolicy som arbetsflödessteg stöder: `concurrency_group`, `concurrency_limit` och `cost_units`.

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

Skicka iväg ett serialiserat definitionspaket för en tillståndsmaskin. Programkod bör i de flesta fall föredra `machine()->dispatch()`. Den här metoden på lägre nivå finns för att adaptrar ska kunna starta en maskin utan att vara beroende av byggaren direkt.

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

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

Hämta maskinens aktuella status. Returnerar ett `StateMachineState`-objekt eller `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` exponerar också:

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

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

Skicka en extern händelse till en väntande maskin.

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

Nyttolasten är tillgänglig för övergångsvillkor och slås samman med maskinens publika tillstånd när händelsen godtas.

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

Lista beständiga maskinrader för inspektion.

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

Varje rad innehåller maskinens id, namn, status, aktuella tillstånd, definitionens version, definitionshash, idempotensnyckel och tidsstämplar för livscykeln.

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

Hämta den beständiga händelsetidslinjen för en maskin.

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

Varje händelserad innehåller: `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` och `created_at`.

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

Hämta ett normaliserat spårningspaket för en felsökare för tillståndsmaskiner UI.

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

Spåret innehåller `machine`, grupperade `states`, råa `events`, korrelerade åtgärder `jobs`, `logs`, `artifacts` och `chunks`.

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

Hämta det publika tillståndet efter en specifik spårningshändelse för maskinen, eller `null` om det inte hittas.

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

Se [Tillståndsmaskiner](https://queuety.inline0.dev/sv/docs/state-machines) för livscykelmodellen och användningsmönster.

## Arbetsflödesmallar

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

Skapa en arbetsflödesbyggare som mall.

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

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

Registrera en arbetsflödesmall.

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

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

Skicka iväg en registrerad arbetsflödesmall med namn. Returnerar arbetsflödes-ID:t.

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

Kastar `RuntimeException` om mallen inte är registrerad.

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

Skicka iväg ett arbetsflöde från ett definitionspaket vid körning.

Programkod bör i de flesta fall föredra `run_workflow()` eller `workflow()->dispatch()`. Den här metoden på lägre nivå finns för att återanvändbara adaptrar ska kunna skicka iväg en serialiserad arbetsflödesdefinition utan att vara beroende av interna metoder i arbetsflödeshanteraren.

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

Registrera en WordPress-åtgärd som skickar iväg ett arbetsflöde.

```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` kan vara antingen:

- ett registrerat arbetsflödesmallnamn
- en inbäddad `WorkflowBuilder`

`map`, `when` och `idempotency_key` körs synkront i den aktuella WordPress-begäran. Endast arbetsflödesstegen körs asynkront efter utskickningen.

Se [Åtgärdsutlösare](https://queuety.inline0.dev/sv/docs/features/action-triggers) för den fullständiga guiden.

### `Queuety::workflow_templates()`

Hämta registret över arbetsflödesmallar.

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

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

Läs in och registrera alla arbetsflödesfiler från en katalog. Varje `.php`-fil ska returnera en `WorkflowBuilder`. Returnerar antalet registrerade arbetsflöden.

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

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

Läs in och registrera en enskild arbetsflödesfil. Returnerar `WorkflowTemplate` eller `null` om filen inte returnerar en byggare.

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

## Schemaläggning

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

Skapa ett återkommande schema. Returnerar en byggare `PendingSchedule`.

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

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

### Metoder för `PendingSchedule`

| Metod | Beskrivning |
|---|---|
| `every( string $interval )` | Ange ett intervalluttryck (e.g. `1 hour`, `30 minutes`) |
| `cron( string $expression )` | Ange ett cron-uttryck med 5 fält |
| `overlap( OverlapPolicy $policy )` | Ange överlappningspolicy (standard: `Allow`). Se [Schemaläggning](https://queuety.inline0.dev/sv/docs/features/scheduling). |
| `on_queue( string $queue )` | Ange målkön (standard: `default`) |
| `id()` | Tvinga utskickning och returnera schema-ID:t |

### `Queuety::scheduler()`

Hämta den interna instansen `Scheduler`.

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

## Hanterarregistrering

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

Registrera en hanterarklass under ett namn.

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

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

Identifiera och registrera automatiskt hanterarklasser från en katalog. Returnerar antalet registrerade hanterare.

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

### `Queuety::registry()`

Hämta hanterarregistret.

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

## Observerbarhet

### `Queuety::logger()`

Hämta instansen `Logger` för att fråga efter loggposter.

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

Hämta instansen `Metrics`.

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

### `Queuety::webhook_notifier()`

Hämta instansen `WebhookNotifier`.

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

### `Queuety::rate_limiter()`

Hämta instansen `RateLimiter`.

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

## Cache

### `Queuety::cache()`

Hämta instansen för den aktiva cachebackendlösningen.

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

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

Åsidosätt cachebackendlösningen. Anropa detta före `Queuety::init()` om du vill använda en anpassad implementation.

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

### `QUEUETY_CACHE_TTL`

Standardvärde för cache-TTL i sekunder (standard: `5`). Ange den här konstanten i `wp-config.php` om du vill ändra standardvärdet för TTL som används av interna cacheåtgärder.

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

Mer information om backendlösningar och automatisk identifiering finns i [Cachelagring](https://queuety.inline0.dev/sv/docs/features/caching).

## Tillståndsmaskinens händelselogg

### `Queuety::machine_events()`

Hämta instansen `StateMachineEventLog`.

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

## Arbetsflödets händelselogg

### `Queuety::workflow_events()`

Hämta instansen `WorkflowEventLog`.

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

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

Hämta hela tidslinjen med händelser för ett arbetsflöde. Returnerar en array med händelserader ordnade efter ID.

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

Varje händelserad innehåller: `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` (kopierat från `error.message`), `duration_ms` och `created_at`.

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

Hämta ett normaliserat spårningspaket för en arbetsflödesfelsökare UI.

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

Spåret innehåller `workflow`, grupperade `steps`, råa `events`, `jobs`, `logs`, `artifacts`, `chunks`, `signals` och `wait_dependencies`.

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

Ange programnivåindata för arbetsflödessteget som körs för närvarande.

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

Ange programnivåutdata för arbetsflödessteget som körs för närvarande.

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

Slå samman programnivåkontext med arbetsflödessteget som körs för närvarande.

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

Hämta det publika tillståndet efter att ett specifikt arbetsflödessteg har slutförts eller återupptagits, eller `null` om det inte hittas.

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

Se [Arbetsflödets händelselogg](https://queuety.inline0.dev/sv/docs/workflows/event-log) för användningsområden och kommandona CLI.

## Interna instanser

De här metoderna returnerar interna instanser för avancerade användningsområden.

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `Queuety::queue()` | `Queue` | Köåtgärder (ta i anspråk, frigöra, begrava) |
| `Queuety::worker()` | `Worker` | Styrning av arbetarprocesser |
| `Queuety::workflow_manager()` | `Workflow` | Orkestrering av arbetsflöden |
| `Queuety::machines()` | `StateMachine` | Hantering av tillståndsmaskinens livscykel |
| `Queuety::connection()` | `Connection` | Databasanslutning |
| `Queuety::batch_manager()` | `BatchManager` | Hantering av batchars livscykel (avbryt, rensa) |
| `Queuety::chunk_store()` | `ChunkStore` | Lagring av chunkar för strömmande steg |
| `Queuety::machine_events()` | `StateMachineEventLog` | Spårningshändelser för tillståndsmaskiner och normaliserade spårningspaket |
| `Queuety::workflow_events()` | `WorkflowEventLog` | Spårningshändelser för arbetsflöden och normaliserade spårningspaket |
| `Queuety::resource_manager()` | `ResourceManager` | Arbetarens antagningsprofiler, viktade budgetar och inspektion av systemminne |
| `Queuety::cache()` | `Cache` | Instans för cachebackendlösning |

## Testning

### `Queuety::fake()`

Ersätt kön med en minnesbaserad testdublett. Returnerar en instans `QueueFake` som registrerar utskickade jobb utan att komma åt databasen. `create_batch()` registrerar också falska batchmetadata; kedjor verifieras via de enskilda jobb som skickas iväg.

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

### `Queuety::reset()`

Återställ allt internt tillstånd, inklusive kötestdublettens tillstånd. Anropa i `tearDown()`.

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

### Metoder för `QueueFake`

| Metod | Beskrivning |
|---|---|
| `assert_pushed( string $class, ?Closure $callback )` | Kontrollera att en jobbklass har lagts till i kön. En valfri återanropsfunktion filtrerar efter jobbdata. |
| `assert_pushed_times( string $class, int $count )` | Kontrollera att ett jobb har lagts till exakt N gånger. |
| `assert_not_pushed( string $class )` | Kontrollera att ett jobb aldrig har lagts till i kön. |
| `assert_nothing_pushed()` | Kontrollera att inga jobb alls har lagts till i kön. |
| `assert_batched( ?Closure $callback )` | Kontrollera att en batch har skickats iväg. En valfri återanropsfunktion filtrerar efter batchdata. |
| `pushed( string $class )` | Hämta alla registrerade utskick för en klass. Returnerar en array. |
| `batches()` | Hämta alla registrerade batchar. Returnerar en array. |
| `reset()` | Rensa alla registrerade jobb och batchar. |

Se [Testning](https://queuety.inline0.dev/sv/docs/features/testing) för fullständiga exempel.

## Gränssnitt

### `Handler`

Gränssnitt för enkla jobbhanterare.

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

`config()` kan returnera `queue`, `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` och `cost_units`.

### `Step`

Gränssnitt för hanterare av arbetsflödessteg.

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

`config()` kan returnera `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` och `cost_units`.

### `Contracts\ForEachHandler`

Gränssnitt för dynamiska för varje-grenhanterare.

```php
namespace Queuety\Contracts;

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

`config()` kan returnera `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` och `cost_units`.

### `Contracts\ForEachReducer`

Valfri reducerare för för varje-resultat.

```php
namespace Queuety\Contracts;

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

### `Contracts\Compensation`

Gränssnitt för hanterare av återställningsåtgärder för steg.

```php
namespace Queuety\Contracts;

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

### `Contracts\RepeatCondition`

Gränssnitt för loopvillkor som används av `repeat_until()` och `repeat_while()` när en jämförelse med en tillståndsnyckel är för begränsad.

```php
namespace Queuety\Contracts;

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

### `Contracts\StateAction`

Gränssnitt för köade åtgärder vid inträde i tillstånd.

```php
namespace Queuety\Contracts;

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

`$payload` förmedlar den strukturerade `payload` från åtgärdsdefinitionen, om maskinen definierades med en sådan. Returnera uppdateringar av det publika tillståndet. Inkludera `_event` och eventuellt `_event_payload` när åtgärden ska utlösa en omedelbar övergång.

Tillståndsåtgärder kan även ha en valfri metod `config()`. Queuety läser `concurrency_group`, `concurrency_limit` och `cost_units` från den när åtgärden vid inträde läggs i kön.

### `Contracts\StateGuard`

Gränssnitt för övergångsvillkor i tillståndsmaskiner.

```php
namespace Queuety\Contracts;

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

### `Contracts\Job`

Gränssnitt för självständiga jobbklasser som kan skickas iväg. Jobbklasser kapslar in sin nyttolast som publika egenskaper och exekveringslogik i `handle()`.

```php
namespace Queuety\Contracts;

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

Jobbklasser kan valfritt definiera en metod `middleware()` som returnerar en array med instanser av `Contracts\Middleware`.

### `Contracts\Cache`

Gränssnitt för cachebackendlösningar. Se [Cachelagring](https://queuety.inline0.dev/sv/docs/features/caching) för inbyggda implementationer och anpassade backendlösningar.

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

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `get( $key )` | `mixed` | Hämta ett värde. Returnerar `null` om det inte hittas eller har löpt ut. |
| `set( $key, $value, $ttl )` | `void` | Lagra ett värde. TTL på 0 innebär att värdet inte löper ut. |
| `delete( $key )` | `void` | Ta bort ett värde. |
| `has( $key )` | `bool` | Kontrollera om en nyckel finns och inte har löpt ut. |
| `add( $key, $value, $ttl )` | `bool` | Atomisk ange-om-den-inte-finns. Returnerar `true` om värdet angavs. |
| `flush()` | `void` | Ta bort alla objekt från cachen. |

### `WorkflowEventLog`

Registrerar övergångar mellan arbetsflödessteg med fullständig spårningskontext. Åtkomst via `Queuety::workflow_events()`.

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `record_event( array $event )` | `void` | Registrera en rå spårningshändelse |
| `record_step_started( ... )` | `void` | Registrera en step_started-händelse med indata och tillståndet före körningen |
| `record_step_completed( ... )` | `void` | Registrera en step_completed-händelse med indata, utdata, tillstånd före och tillstånd efter |
| `record_step_failed( ... )` | `void` | Registrera en step_failed-händelse med spårningskontext och strukturerade feldetaljer |
| `get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )` | `array` | Hämta arbetsflödets spårningshändelser i ordning, med valfri sidindelning |
| `get_trace( int $workflow_id )` | `array` | Hämta ett normaliserat spårningspaket |
| `get_state_at_step( int $workflow_id, int $step_index )` | `array\|null` | Hämta det publika tillståndet efter att ett specifikt steg har slutförts eller återupptagits |
| `prune( int $older_than_days )` | `int` | Ta bort händelser som är äldre än det angivna antalet dagar. Returnerar antalet borttagna rader. |

### `StateMachineEventLog`

Registrerar tillståndsmaskinens livscykel-, åtgärds-, övergångs- och villkorshändelser med samma spårningsfält som arbetsflödeshändelser.

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `record_event( array $event )` | `void` | Registrera en rå händelse i maskinspårningen |
| `get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )` | `array` | Hämta händelser i maskinspårningen i ordning, med valfri sidindelning |
| `get_trace( int $machine_id )` | `array` | Hämta ett normaliserat paket med maskinspårning |
| `get_state_at_event( int $machine_id, int $event_id )` | `array\|null` | Hämta det publika tillståndet efter en viss händelse i maskinspårningen |
| `prune( int $older_than_days )` | `int` | Ta bort händelser som är äldre än det angivna antalet dagar. Returnerar antalet borttagna rader. |

### `Contracts\StreamingStep`

Gränssnitt för hanterare av arbetsflödessteg som producerar en ström av delar. Varje värde som avges sparas omedelbart i databasen. Se [Strömmande steg](https://queuety.inline0.dev/sv/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;
}
```

| Metod | Beskrivning |
|---|---|
| `stream( $state, $existing_chunks )` | Generator som avger strängdelar. Varje avrop utlöser en omedelbar skrivning till databasen. Vid nytt försök innehåller `$existing_chunks` tidigare sparade delar. |
| `on_complete( $chunks, $state )` | Anropas när strömmen är färdig. Returnerar data som ska slås samman med arbetsflödestillståndet. |
| `config()` | Valfri konfiguration. Stöder `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` och `cost_units`. |

### `ChunkStore`

Hanterar sparandet av delar för strömmande steg. Åtkomst via `Queuety::chunk_store()`.

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `get_chunks( int $job_id )` | `string[]` | Hämta alla delar för ett jobb, sorterade efter delindex |
| `append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )` | `void` | Lägg till en enskild del |
| `clear_chunks( int $job_id )` | `void` | Ta bort alla delar för ett jobb |
| `chunk_count( int $job_id )` | `int` | Räkna delarna för ett jobb |
| `get_accumulated( int $job_id )` | `string` | Sammanfoga alla delar till en sträng |

### `Heartbeat`

Statisk hjälpfunktion för att skicka aktivitetslivstecken inifrån steghanterare och strömmande steg. Se [Livstecken](https://queuety.inline0.dev/sv/docs/features/heartbeats).

| Metod | Beskrivning |
|---|---|
| `Heartbeat::init( int $job_id, Connection $conn )` | Ange jobbkontexten. Anropas automatiskt av arbetaren. |
| `Heartbeat::beat( array $progress = [] )` | Skicka ett livstecken. Uppdaterar `reserved_at` och sparar vid behov förloppsdata i `heartbeat_data`. |
| `Heartbeat::clear()` | Rensa jobbkontexten. Anropas automatiskt av arbetaren. |
| `Heartbeat::current_job_id()` | Hämta det aktuella jobb-ID:t (för testning). |

### `Contracts\Middleware`

Gränssnitt för jobb-middleware. Middleware omsluter jobbkörningen i en pipeline utformad som en lök.

```php
namespace Queuety\Contracts;

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

## Egenskaper

### `Dispatchable`

Tillhandahåller statiska utsändningsmetoder för jobbklasser som implementerar `Contracts\Job`. Konstruktörens argument skickas vidare när jobbinstansen skapas.

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

| Metod | Returnerar | Beskrivning |
|---|---|---|
| `dispatch( ...$args )` | `PendingJob` | Skapa en instans och skicka ut den |
| `dispatch_if( bool $condition, ...$args )` | `PendingJob\|null` | Skicka endast ut om `$condition` är sant |
| `dispatch_unless( bool $condition, ...$args )` | `PendingJob\|null` | Skicka endast ut om `$condition` är falskt |
| `with_chain( array $jobs )` | `ChainBuilder` | Starta en kedja från den här jobbklassen |

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

### Jobbegenskaper

Jobbklasser kan deklarera publika egenskaper som arbetaren läser via reflection för att åsidosätta beteendet för nya försök och tidsgränser.

| Egenskap | Typ | Beskrivning |
|---|---|---|
| `$tries` | `int` | Maximalt antal försök innan jobbet begravs |
| `$timeout` | `int` | Maximal körtid i sekunder (kräver `pcntl`) |
| `$backoff` | `array` | Ökande fördröjningsvärden i sekunder för varje nytt försök |

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

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

    // ...
}
```

### Hooken `failed()`

När ett jobb begravs efter att alla nya försök har förbrukats anropar arbetaren en metod `failed()` på jobbinstansen, om en sådan har definierats.

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

## Inbyggd middleware

Alla middlewareklasser implementerar `Contracts\Middleware` och finns i namnrymden `Queuety\Middleware`.

| Klass | Beskrivning |
|---|---|
| `RateLimited( int $max, int $window )` | Upprätthåll en hastighetsgräns på `$max` körningar per `$window` sekunder |
| `Timeout( int $seconds )` | Avsluta jobbet efter `$seconds` sekunder (kräver `pcntl`) |
| `UniqueJob( ?string $key )` | Förhindra samtidig körning med ett databaslås |
| `WithoutOverlapping( string $key, int $release_after )` | Förhindra överlappande körningar med automatisk låsexpiration |
| `ThrottlesExceptions( int $max_attempts, int $decay_minutes )` | Begränsa undantag för att förhindra jobbfloder när en extern tjänst ligger nere |

Se [Middleware](https://queuety.inline0.dev/sv/docs/features/middleware) för användningsdetaljer och exempel.

## Uppräkningar

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

Se [Schemaläggning](https://queuety.inline0.dev/sv/docs/features/scheduling) för information om hur varje policy fungerar.

## Attribut

### `#[QueuetyHandler]`

PHP 8-attribut för automatisk registrering. Se [PHP Attribut](https://queuety.inline0.dev/sv/docs/features/attributes).

```php
use Queuety\Attributes\QueuetyHandler;

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

## CLI-brygga

### `Queuety::cli_command()`

Returnerar det publicerade WP-CLI-rotkommandonamnet.

Standardrotkommandot är `queuety`. Definiera `QUEUETY_CLI_COMMAND` innan Queuety startar om kommandot ska publiceras under ett annat namn.

### `Queuety::cli_command_map()`

Returnerar katalogen Queuety CLI som kan serialiseras, för testmiljöer som behöver förstå vilka kommandon som levereras utan att genomsöka klasserna WP-CLI.

Varje post innehåller:
- ett stabilt åtgärds-ID
- den relativa sökvägen CLI
- hanterarklassen och metoden WP-CLI
- möjliga körningsmål
- adaptern som normaliserar råa argument CLI till en körningsplan

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

Omvandlar ett parsad CLI-anrop till körningsplanen som testmiljön ska köra.

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

Körningsplaner är utformade med hänsyn till transporten:
- kommandon löses upp till publika anropsbara PHP med normaliserade argument
- katalogen listar alla möjliga körningsmål i förväg, medan `callable` och `transport` anger vilken gren som valts för den parsade indata

Detta är standarden Queuety använder för agenttestmiljöer: stabilt åtgärds-ID, publikt API-mål och adapterägd normalisering av sådant som bara gäller CLI, till exempel standardvärden för köer, avkodning av nyttolaster JSON, förgrening av arbetarpooler och hantering av exportfiler för arbetsflöden.