# Začínáme

## Instalace

### Požadavky

- PHP 8.2 nebo novější a WordPress 6.4 nebo novější
- MySQL 8.0+ nebo MariaDB 10.6+. Pracovní procesy si přebírají úlohy a splatné plány pomocí `SELECT ... FOR UPDATE SKIP LOCKED`, které starší servery odmítají kvůli syntaktické chybě.
- `mysqli` nebo `pdo_mysql` (viz níže)
- WP-CLI na serveru, pokud používáte vyhrazené pracovní procesy s `wp queuety work`
- Rozšíření `pcntl` a `posix` PHP, pokud používáte fondy pracovních procesů s `--workers` nebo `--min-workers`/`--max-workers`

Queuety vyžaduje v běhovém prostředí PHP, které načítá WordPress a WP-CLI, buď `mysqli`, nebo `pdo_mysql`. Ovladač vybírá automaticky: v běhových prostředích WordPress upřednostňuje `mysqli` a pro samostatné či přímé použití ponechává k dispozici `pdo_mysql`.

Pokud chcete běhové prostředí založené na databázi bez vrstvy pluginu WordPress, podívejte se na [Samostatné použití](https://queuety.inline0.dev/cs/docs/features/standalone-use). Využívá stejné připojení a tabulky běhového prostředí, ale neobsahuje mosty hooků WordPress ani registraci WP-CLI.

### Z archivu vydání

Každé [vydání GitHub](https://github.com/inline0/queuety/releases) obsahuje soubor `queuety.zip`: plugin s již nainstalovanými závislostmi Composer. Nejnovější verzi nainstalujete pomocí WP-CLI:

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

Nebo stáhněte archiv ZIP a nahrajte jej v části Pluginy > Přidat nový > Nahrát plugin. Pro běžný web WordPress je to nejjednodušší postup.

### Pomocí Composer pro Composer spravovaný systém WordPress

```bash
composer require queuety/queuety
```

Poté plugin aktivujte:

```bash
wp plugin activate queuety
```

Typ balíčku je `wordpress-plugin`. Composer jej umístí do adresáře pluginů pouze tehdy, když projekt vyžaduje `composer/installers` a přiřadí tento typ k cestě instalace, jako to dělá Bedrock; projekt také musí načíst vlastní `vendor/autoload.php` (stejně jako Bedrock). Bez `composer/installers` jej Composer nainstaluje do `vendor/queuety/queuety`, kde jej WordPress nenajde. Při běžné instalaci WordPress proto použijte archiv ZIP z vydání.

### Ze zdrojového kódu během vývoje

Umístěte repozitář do `wp-content/plugins/queuety` a potom nainstalujte závislosti PHP:

```bash
composer install
wp plugin activate queuety
```

Při aktivaci Queuety vytvoří své databázové tabulky (`queuety_jobs`, `queuety_workflows`, `queuety_logs`, `queuety_schedules`, `queuety_queue_states`, `queuety_webhooks`, `queuety_locks`, `queuety_signals`, `queuety_workflow_dependencies`, `queuety_workflow_dispatch_keys`, `queuety_batches`, `queuety_chunks`, `queuety_workflow_events`, `queuety_artifacts`, `queuety_state_machines`, `queuety_state_machine_events`), aby pracovní procesy mohly přebírat úlohy přímo z MySQL.

Ve výchozím nastavení plugin také každou minutu plánuje jednorázový pracovní proces přes WordPress cron pro frontu `default`. Získáte tak základní řešení bez shellu pro úlohy a pracovní postupy běžící na `default`, pokud se spouští WordPress cron. Každé spuštění zpracuje nejvýše jednu úlohu a nespouští opakované plány, neobnovuje zastaralé úlohy ani nekontroluje termíny pracovních postupů; tyto činnosti probíhají pouze v dlouho běžícím procesu `wp queuety work` ([#14](https://github.com/inline0/queuety/issues/14)). U vlastních front, opakovaných plánů, nižší latence nebo větší zátěže přejděte na vyhrazené procesy `wp queuety work`.

## Konfigurace

Všechny konstanty jsou nepovinné. Definujte je v `wp-config.php` před načtením pluginu, případně před spuštěním Queuety při instalaci vložené do šablony:

| Konstanta | Výchozí hodnota | Popis |
|---|---|---|
| `QUEUETY_RETENTION_DAYS` | `7` | Výchozí stáří v dnech pro `wp queuety purge` a `Queuety::purge()`. Automatické mazání neprobíhá |
| `QUEUETY_LOG_RETENTION_DAYS` | `0` | Čte ji `Config::log_retention_days()`, zatím se však nepoužívá; protokoly se uchovávají, dokud nezavoláte `Queuety::purge_logs()` ([#15](https://github.com/inline0/queuety/issues/15)) |
| `QUEUETY_MAX_EXECUTION_TIME` | `300` | Maximální počet sekund na úlohu před vypršením časového limitu (zatím se nevynucuje, viz [Úlohy](https://queuety.inline0.dev/cs/docs/jobs#timeout)) |
| `QUEUETY_WORKER_SLEEP` | `1` | Počet sekund čekání, když je fronta prázdná |
| `QUEUETY_WORKER_MAX_JOBS` | `1000` | Maximální počet úloh před restartem pracovního procesu |
| `QUEUETY_WORKER_MAX_MEMORY` | `128` | Maximální počet MB před restartem pracovního procesu |
| `QUEUETY_RETRY_BACKOFF` | `exponential` | Strategie prodlevy mezi pokusy: `exponential`, `linear` nebo `fixed` |
| `QUEUETY_STALE_TIMEOUT` | `600` | Počet sekund do obnovení zaseknutých úloh |
| `QUEUETY_CACHE_TTL` | `5` | Výchozí TTL mezipaměti v sekundách |
| `QUEUETY_DEBUG` | `false` | Zapnutí podrobného protokolování pracovních procesů |
| `QUEUETY_CLI_COMMAND` | `queuety` | Název hlavního příkazu WP-CLI |
| `QUEUETY_TABLE_PREFIX` | `queuety_` | Základní sdílený název všech tabulek Queuety za databázovým prefixem WordPress |
| `QUEUETY_TABLE_JOBS` | `queuety_jobs` | Název tabulky úloh |
| `QUEUETY_TABLE_WORKFLOWS` | `queuety_workflows` | Název tabulky pracovních postupů |
| `QUEUETY_TABLE_LOGS` | `queuety_logs` | Název tabulky protokolů |
| `QUEUETY_TABLE_SCHEDULES` | `queuety_schedules` | Název tabulky plánů |
| `QUEUETY_TABLE_SIGNALS` | `queuety_signals` | Název tabulky signálů |
| `QUEUETY_TABLE_WORKFLOW_DEPENDENCIES` | `queuety_workflow_dependencies` | Název tabulky čekání na závislosti pracovních postupů |
| `QUEUETY_TABLE_WORKFLOW_DISPATCH_KEYS` | `queuety_workflow_dispatch_keys` | Název tabulky idempotence trvalých pracovních postupů |
| `QUEUETY_TABLE_CHUNKS` | `queuety_chunks` | Název tabulky datových bloků streamu |
| `QUEUETY_TABLE_QUEUE_STATES` | `queuety_queue_states` | Název tabulky stavů front |
| `QUEUETY_TABLE_WEBHOOKS` | `queuety_webhooks` | Název tabulky webhooků |
| `QUEUETY_TABLE_LOCKS` | `queuety_locks` | Název tabulky zámků |
| `QUEUETY_TABLE_BATCHES` | `queuety_batches` | Název tabulky dávek |
| `QUEUETY_TABLE_WORKFLOW_EVENTS` | `queuety_workflow_events` | Název tabulky protokolů událostí pracovních postupů |
| `QUEUETY_TABLE_ARTIFACTS` | `queuety_artifacts` | Název tabulky artefaktů pracovních postupů |
| `QUEUETY_TABLE_STATE_MACHINES` | `queuety_state_machines` | Název tabulky stavových automatů |
| `QUEUETY_TABLE_STATE_MACHINE_EVENTS` | `queuety_state_machine_events` | Název tabulky protokolů událostí stavových automatů |
| `QUEUETY_DB_DRIVER` | `auto` | Ovladač MySQL: `auto`, `mysqli` nebo `pdo`. `auto` upřednostňuje `mysqli`, když je načteno WordPress, jinak `pdo_mysql` a poté `mysqli` |

Konstanty pro přijímání úloh podle dostupných zdrojů a adaptivní fondy (`QUEUETY_RESOURCE_*`, `QUEUETY_WORKER_POOL_*`) najdete na stránce [Pracovní procesy](https://queuety.inline0.dev/cs/docs/features/workers).

`QUEUETY_TABLE_PREFIX` mění pouze část názvů tabulek Queuety. Databázový prefix WordPress se k výsledku stále připojí, takže `$wpdb->prefix = 'wp_'` a `QUEUETY_TABLE_PREFIX = 'themequeue_'` vytvoří tabulky, například `wp_themequeue_jobs`. Pro jednotlivé tabulky mají přednost explicitní konstanty `QUEUETY_TABLE_*`.

Samostatná připojení mohou také nastavit prefix tabulek Queuety pro každé připojení:

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

Tím zůstane databázový prefix WordPress zachován a změní se pouze část názvu tabulky Queuety.

## Vaše první úloha

Vytvořte třídu obslužné rutiny, která implementuje rozhraní `Handler`:

```php
use Queuety\Handler;

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

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

Zaregistrujte ji a odešlete úlohu:

```php
use Queuety\Queuety;

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

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

Nebo použijte moderní třídu úlohy, kterou lze odesílat:

```php
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

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

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

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

## Váš první pracovní postup

Definujte obslužné rutiny kroků, které implementují rozhraní `Step`:

```php
use Queuety\Step;

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

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

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

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

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

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

Odešlete pracovní postup:

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

## Spuštění pracovního procesu

```bash
wp queuety work
```

Pracovní proces vyhledává čekající úlohy, spouští je, posouvá pracovní postupy dál a při prázdné frontě čeká. Zastavíte jej stisknutím `Ctrl+C`; proces se ukončí okamžitě, i uprostřed úlohy (viz [Pracovní procesy](https://queuety.inline0.dev/cs/docs/features/workers#worker-lifecycle)).

Výše uvedená úloha `SendEmailHandler` se pomocí `config()` odesílá do fronty `emails`, takže ji pracovní proces naslouchající na `default` nepřevezme. Uveďte název každé používané fronty:

```bash
wp queuety work --queue=emails,default
```

Pokud nespustíte vyhrazený pracovní proces, Queuety stále nabízí výše popsané záložní řešení WordPress cron, které se ve výchozím nastavení spouští jednou za minutu. Je omezeno na frontu `default` a jednu úlohu na spuštění. Vyhrazený pracovní proces nabízí vyšší propustnost a nižší latenci.

Pro produkční prostředí spusťte více pracovních procesů:

```bash
wp queuety work --workers=4
```

Zpracovávejte více front v pořadí podle priority:

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

## Další kroky

- [Úlohy](https://queuety.inline0.dev/cs/docs/jobs) – kompletní průvodce odesíláním úloh a obslužnými rutinami
- [Pracovní postupy](https://queuety.inline0.dev/cs/docs/workflows) – řetězce, paralelní kroky, podmíněné větvení a spouštění pracovních postupů
- [Middleware](https://queuety.inline0.dev/cs/docs/features/middleware) – omezování rychlosti, throttling a vlastní logika zpracování
- [Dávkové zpracování](https://queuety.inline0.dev/cs/docs/features/batching) – odesílání skupin úloh se zpětnými voláními
- [Streamované kroky](https://queuety.inline0.dev/cs/docs/workflows/streaming) – trvalé ukládání streamovaných dat po jednotlivých blocích
- [Plánování](https://queuety.inline0.dev/cs/docs/features/scheduling) – opakované úlohy
- [Ukládání do mezipaměti](https://queuety.inline0.dev/cs/docs/features/caching) – připojitelná vrstva mezipaměti
- [Testování](https://queuety.inline0.dev/cs/docs/features/testing) – QueueFake a aserce v testech
- [Referenční příručka CLI](https://queuety.inline0.dev/cs/docs/cli) – všechny dostupné příkazy
- [PHP API](https://queuety.inline0.dev/cs/docs/api) – programový přístup