# Začíname

## Inštalácia

### Požiadavky

- PHP 8.2 alebo novšia verzia a WordPress 6.4 alebo novšia verzia
- MySQL 8.0+ alebo MariaDB 10.6+. Pracovníci si nárokujú úlohy a splatné plány pomocou `SELECT ... FOR UPDATE SKIP LOCKED`, ktoré staršie servery odmietajú so syntaktickou chybou.
- `mysqli` alebo `pdo_mysql` (pozri nižšie)
- Na serveri WP-CLI, ak spúšťate vyhradených pracovníkov pomocou `wp queuety work`
- Rozšírenia `pcntl` a `posix` PHP, ak spúšťate skupiny pracovníkov pomocou `--workers` alebo `--min-workers`/`--max-workers`

Queuety vyžaduje buď `mysqli`, alebo `pdo_mysql` v prostredí PHP, ktoré načítava WordPress a WP-CLI. Ovládač vyberie automaticky: v prostrediach WordPress uprednostňuje `mysqli` a pre samostatné priame použitie prostredia ponecháva k dispozícii `pdo_mysql`.

Ak chcete používať prostredie s databázou bez vrstvy pluginu WordPress, pozrite si [Samostatné použitie](https://queuety.inline0.dev/sk/docs/features/standalone-use). Táto cesta používa rovnaké pripojenie a tabuľky prostredia, ale neobsahuje premostenia hookov WordPress ani registráciu WP-CLI.

### Z archívu zip vydania

Každé vydanie [GitHub](https://github.com/inline0/queuety/releases) obsahuje súbor `queuety.zip`: plugin s už nainštalovanými závislosťami Composer. Najnovšiu verziu nainštalujete pomocou WP-CLI:

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

Alebo si stiahnite archív zip a nahrajte ho cez Plugins > Add New > Upload Plugin. Toto je najjednoduchší postup pre bežnú stránku WordPress.

### Cez Composer pre správu pomocou Composer WordPress

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

Potom plugin aktivujte:

```bash
wp plugin activate queuety
```

Typ balíka je `wordpress-plugin`. Composer ho umiestni do adresára pluginov iba vtedy, keď projekt vyžaduje `composer/installers` a mapuje tento typ na cestu inštalácie, ako to robí Bedrock, a projekt musí načítať vlastný `vendor/autoload.php` (to robí aj Bedrock). Bez `composer/installers` ho Composer nainštaluje do `vendor/queuety/queuety`, kde ho WordPress nenájde, preto pri bežnej inštalácii WordPress použite archív zip vydania.

### Zo zdrojového kódu počas vývoja

Umiestnite repozitár do `wp-content/plugins/queuety` a potom nainštalujte závislosti PHP:

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

Pri aktivácii Queuety vytvorí databázové tabuľky (`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 si pracovníci mohli nárokovať úlohy priamo z MySQL.

Plugin tiež predvolene každú minútu naplánuje cez WordPress cron jednorazového pracovníka pre front `default`. To poskytuje základné riešenie bez shellu pre úlohy a workflowy, ktoré zostávajú na `default`, pokiaľ sa spúšťa WordPress cron. Každé spustenie spracuje najviac jednu úlohu; nespúšťa opakované plány, neobnovuje zastarané úlohy ani nekontroluje termíny workflowov. Tieto činnosti prebiehajú iba v dlho bežiacom procese `wp queuety work` ([#14](https://github.com/inline0/queuety/issues/14)). Pri vlastných frontoch, opakovaných plánoch, nižšej latencii alebo väčšom zaťažení prejdite na vyhradené procesy `wp queuety work`.

## Konfigurácia

Všetky konštanty sú voliteľné. Definujte ich v `wp-config.php` pred načítaním pluginu alebo pred spustením Queuety pri vloženej inštalácii v štýle témy:

| Konštanta | Predvolená hodnota | Opis |
|---|---|---|
| `QUEUETY_RETENTION_DAYS` | `7` | Predvolený vek v dňoch pre `wp queuety purge` a `Queuety::purge()`. Nič sa automaticky nemaže |
| `QUEUETY_LOG_RETENTION_DAYS` | `0` | Načíta ju `Config::log_retention_days()`, zatiaľ sa však nepoužíva; záznamy sa uchovávajú, kým nezavoláte `Queuety::purge_logs()` ([#15](https://github.com/inline0/queuety/issues/15)) |
| `QUEUETY_MAX_EXECUTION_TIME` | `300` | Maximálny počet sekúnd na úlohu pred vypršaním časového limitu (zatiaľ sa nevynucuje, pozri [Úlohy](https://queuety.inline0.dev/sk/docs/jobs#timeout)) |
| `QUEUETY_WORKER_SLEEP` | `1` | Počet sekúnd čakania, keď je front prázdny |
| `QUEUETY_WORKER_MAX_JOBS` | `1000` | Maximálny počet úloh pred reštartovaním pracovníka |
| `QUEUETY_WORKER_MAX_MEMORY` | `128` | Maximálny počet MB pred reštartovaním pracovníka |
| `QUEUETY_RETRY_BACKOFF` | `exponential` | Stratégia postupného predlžovania čakania: `exponential`, `linear` alebo `fixed` |
| `QUEUETY_STALE_TIMEOUT` | `600` | Počet sekúnd pred obnovením zaseknutých úloh |
| `QUEUETY_CACHE_TTL` | `5` | Predvolená životnosť položiek v cache v sekundách |
| `QUEUETY_DEBUG` | `false` | Povoliť podrobné zaznamenávanie pracovníkov |
| `QUEUETY_CLI_COMMAND` | `queuety` | Názov koreňového príkazu WP-CLI |
| `QUEUETY_TABLE_PREFIX` | `queuety_` | Zdieľaný základný názov pre všetky tabuľky Queuety za predponou databázy WordPress |
| `QUEUETY_TABLE_JOBS` | `queuety_jobs` | Názov tabuľky úloh |
| `QUEUETY_TABLE_WORKFLOWS` | `queuety_workflows` | Názov tabuľky workflowov |
| `QUEUETY_TABLE_LOGS` | `queuety_logs` | Názov tabuľky záznamov |
| `QUEUETY_TABLE_SCHEDULES` | `queuety_schedules` | Názov tabuľky plánov |
| `QUEUETY_TABLE_SIGNALS` | `queuety_signals` | Názov tabuľky signálov |
| `QUEUETY_TABLE_WORKFLOW_DEPENDENCIES` | `queuety_workflow_dependencies` | Názov tabuľky čakaní na závislosti workflowov |
| `QUEUETY_TABLE_WORKFLOW_DISPATCH_KEYS` | `queuety_workflow_dispatch_keys` | Názov tabuľky idempotencie trvácnych workflowov |
| `QUEUETY_TABLE_CHUNKS` | `queuety_chunks` | Názov tabuľky streamovaných častí |
| `QUEUETY_TABLE_QUEUE_STATES` | `queuety_queue_states` | Názov tabuľky stavov frontov |
| `QUEUETY_TABLE_WEBHOOKS` | `queuety_webhooks` | Názov tabuľky webhookov |
| `QUEUETY_TABLE_LOCKS` | `queuety_locks` | Názov tabuľky zámkov |
| `QUEUETY_TABLE_BATCHES` | `queuety_batches` | Názov tabuľky dávok |
| `QUEUETY_TABLE_WORKFLOW_EVENTS` | `queuety_workflow_events` | Názov tabuľky denníka udalostí workflowov |
| `QUEUETY_TABLE_ARTIFACTS` | `queuety_artifacts` | Názov tabuľky artefaktov workflowov |
| `QUEUETY_TABLE_STATE_MACHINES` | `queuety_state_machines` | Názov tabuľky stavových automatov |
| `QUEUETY_TABLE_STATE_MACHINE_EVENTS` | `queuety_state_machine_events` | Názov tabuľky denníka udalostí stavových automatov |
| `QUEUETY_DB_DRIVER` | `auto` | Ovládač MySQL: `auto`, `mysqli` alebo `pdo`. `auto` uprednostňuje `mysqli`, keď je načítané WordPress, inak `pdo_mysql` a potom `mysqli` |

Konštanty pre prijímanie zdrojov a prispôsobenie skupiny pracovníkov (`QUEUETY_RESOURCE_*`, `QUEUETY_WORKER_POOL_*`) sú uvedené na stránke [Pracovníci](https://queuety.inline0.dev/sk/docs/features/workers).

`QUEUETY_TABLE_PREFIX` mení iba časť názvov tabuliek Queuety. Predpona databázy WordPress sa stále pridáva pred výsledný názov, takže `$wpdb->prefix = 'wp_'` a `QUEUETY_TABLE_PREFIX = 'themequeue_'` vytvoria tabuľky, napríklad `wp_themequeue_jobs`. Výslovne zadané konštanty `QUEUETY_TABLE_*` majú pri jednotlivých tabuľkách stále prednosť.

V samostatných pripojeniach možno tiež nastaviť predponu tabuliek Queuety pre každé pripojenie:

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

Tým zostane predpona databázy WordPress zachovaná a zmení sa iba
časť názvu tabuľky Queuety.

## Vaša prvá úloha

Vytvorte triedu obslužnej rutiny, ktorá implementuje rozhranie `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 ju a odošlite ú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!',
] );
```

Alebo použite modernú triedu úlohy, ktorú možno odoslať:

```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áš prvý workflow

Definujte obslužné rutiny krokov, ktoré implementujú rozhranie `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 [];
    }
}
```

Odošlite workflow:

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

## Spustenie pracovníka

```bash
wp queuety work
```

Pracovník vyhľadáva čakajúce úlohy, vykonáva ich, posúva workflowy ďalej a pri prázdnom fronte čaká. Stlačením `Ctrl+C` ho zastavíte; proces sa ukončí okamžite, aj uprostred úlohy (pozri [Pracovníci](https://queuety.inline0.dev/sk/docs/features/workers#worker-lifecycle)).

Vyššie uvedený `SendEmailHandler` odosiela svoje úlohy do frontu `emails` cez `config()`, takže pracovník na `default` ich nespracuje. Uveďte každý front, ktorý používate:

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

Ak nespúšťate vyhradeného pracovníka, Queuety stále ponúka vyššie opísanú záložnú možnosť WordPress cron, ktorá sa predvolene spúšťa raz za minútu; obmedzuje sa na front `default` a jednu úlohu na spustenie. Vyhradený pracovník ponúka vyššiu priepustnosť a nižšiu latenciu.

V produkčnom prostredí spúšťajte viacero pracovníkov:

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

Spracúvajte viacero frontov podľa priority:

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

## Čo ďalej

- [Úlohy](https://queuety.inline0.dev/sk/docs/jobs) – kompletný návod na odosielanie úloh a obslužné rutiny
- [Workflowy](https://queuety.inline0.dev/sk/docs/workflows) – reťazce, paralelné kroky, podmienené vetvenie a spúšťanie workflowov
- [Middleware](https://queuety.inline0.dev/sk/docs/features/middleware) – obmedzovanie frekvencie, tlmenie a vlastná logika postupnosti
- [Dávkovanie](https://queuety.inline0.dev/sk/docs/features/batching) – odosielanie skupín úloh s callbackmi
- [Streamované kroky](https://queuety.inline0.dev/sk/docs/workflows/streaming) – trvalé ukladanie streamovaných údajov po jednotlivých častiach
- [Plánovanie](https://queuety.inline0.dev/sk/docs/features/scheduling) – opakované úlohy
- [Ukladanie do cache](https://queuety.inline0.dev/sk/docs/features/caching) – vrstva cache, ktorú možno doplniť
- [Testovanie](https://queuety.inline0.dev/sk/docs/features/testing) – QueueFake a testovacie tvrdenia
- [CLI Referencia ](https://queuety.inline0.dev/sk/docs/cli) – všetky dostupné príkazy
- [PHP API](https://queuety.inline0.dev/sk/docs/api) – programový prístup