# Začetek

## Namestitev

### Zahteve

- PHP 8.2 ali novejši in WordPress 6.4 ali novejši
- MySQL 8.0+ ali MariaDB 10.6+. Delavci prevzemajo opravila in zapadle razporede z `SELECT ... FOR UPDATE SKIP LOCKED`, ki ga starejši strežniki zavrnejo s skladenjsko napako.
- `mysqli` ali `pdo_mysql` (glejte spodaj)
- WP-CLI na strežniku, če uporabljate namenske delavce z `wp queuety work`
- Razširitvi `pcntl` in `posix` PHP, če uporabljate sklade delavcev z `--workers` ali `--min-workers`/`--max-workers`

Queuety zahteva bodisi `mysqli` bodisi `pdo_mysql` v izvajalnem okolju PHP, ki naloži WordPress in WP-CLI. Gonilnik izbere samodejno: za izvajalna okolja WordPress daje prednost `mysqli`, medtem ko `pdo_mysql` ostane na voljo za samostojno oziroma neposredno uporabo izvajalnega okolja.

Če želite izvajalno okolje, podprto z zbirko podatkov, brez plasti vtičnika WordPress, glejte [Samostojna uporaba](https://queuety.inline0.dev/sl/docs/features/standalone-use). Ta pot uporablja iste povezave in tabele izvajalnega okolja, vendar ne vključuje mostov kavljev WordPress ali registracije WP-CLI.

### Iz arhiva izdaje

Vsaka izdaja [GitHub](https://github.com/inline0/queuety/releases) vsebuje datoteko `queuety.zip`: vtičnik z že nameščenimi odvisnostmi Composer. Najnovejšo namestite z WP-CLI:

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

Lahko pa prenesete arhiv zip in ga naložite prek Vtičniki > Dodaj novega > Naloži vtičnik. To je najpreprostejša možnost za običajno spletno mesto WordPress.

### Prek Composer za Composer, ki ga upravlja WordPress

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

Nato aktivirajte vtičnik:

```bash
wp plugin activate queuety
```

Vrsta paketa je `wordpress-plugin`. Composer ga namesti v imenik vtičnikov samo, kadar projekt zahteva `composer/installers` in to vrsto preslika na pot namestitvenega programa, kot to počne Bedrock, projekt pa mora naložiti svoj `vendor/autoload.php` (to počne tudi Bedrock). Brez `composer/installers` ga Composer namesti v `vendor/queuety/queuety`, kjer ga WordPress ne najde, zato pri navadni namestitvi WordPress uporabite zip arhiv izdaje.

### Iz izvorne kode med razvojem

Repozitorij postavite v `wp-content/plugins/queuety`, nato namestite odvisnosti PHP:

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

Ob aktivaciji Queuety ustvari svoje tabele zbirke podatkov (`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`), da lahko delavci prevzemajo opravila neposredno iz MySQL.

Vtičnik privzeto vsako minuto prek WordPress cron razporedi tudi enkratnega delavca za čakalno vrsto `default`. Tako dobite osnovno možnost izvajanja opravil in potekov dela brez lupine, ki ostanejo na `default`, če se sproža WordPress cron. Vsak zagon obdela največ eno opravilo; ne sproža ponavljajočih se urnikov, ne obnovi zastalih opravil in ne preverja rokov potekov dela. Te funkcije se izvajajo samo v dolgotrajnem procesu `wp queuety work` ([#14](https://github.com/inline0/queuety/issues/14)). Za lastne čakalne vrste, ponavljajoče se urnike, manjšo zakasnitev ali večje obremenitve uporabite namenske procese `wp queuety work`.

## Konfiguracija

Vse konstante so neobvezne. Določite jih v `wp-config.php`, preden se naloži vtičnik, ali preden se zažene Queuety pri vdelani namestitvi v slogu teme:

| Konstanta | Privzeto | Opis |
|---|---|---|
| `QUEUETY_RETENTION_DAYS` | `7` | Privzeta starost v dnevih za `wp queuety purge` in `Queuety::purge()`. Samodejno se nič ne izbriše |
| `QUEUETY_LOG_RETENTION_DAYS` | `0` | Bere jo `Config::log_retention_days()`, vendar še ni uporabljena; dnevniki se hranijo, dokler ne pokličete `Queuety::purge_logs()` ([#15](https://github.com/inline0/queuety/issues/15)) |
| `QUEUETY_MAX_EXECUTION_TIME` | `300` | Največje število sekund na opravilo pred časovno omejitvijo (še se ne uveljavlja, glejte [Opravila](https://queuety.inline0.dev/sl/docs/jobs#timeout)) |
| `QUEUETY_WORKER_SLEEP` | `1` | Število sekund mirovanja, ko je čakalna vrsta prazna |
| `QUEUETY_WORKER_MAX_JOBS` | `1000` | Največje število opravil pred ponovnim zagonom delavca |
| `QUEUETY_WORKER_MAX_MEMORY` | `128` | Največje število MB pred ponovnim zagonom delavca |
| `QUEUETY_RETRY_BACKOFF` | `exponential` | Strategija čakanja pred ponovnim poskusom: `exponential`, `linear` ali `fixed` |
| `QUEUETY_STALE_TIMEOUT` | `600` | Število sekund pred obnovitvijo zataknjenih opravil |
| `QUEUETY_CACHE_TTL` | `5` | Privzeti TTL predpomnilnika v sekundah |
| `QUEUETY_DEBUG` | `false` | Omogoči podrobno beleženje delavca |
| `QUEUETY_CLI_COMMAND` | `queuety` | Ime korenskega ukaza WP-CLI |
| `QUEUETY_TABLE_PREFIX` | `queuety_` | Skupno osnovno ime za vse tabele Queuety za predpono zbirke podatkov WordPress |
| `QUEUETY_TABLE_JOBS` | `queuety_jobs` | Ime tabele opravil |
| `QUEUETY_TABLE_WORKFLOWS` | `queuety_workflows` | Ime tabele potekov dela |
| `QUEUETY_TABLE_LOGS` | `queuety_logs` | Ime tabele dnevnikov |
| `QUEUETY_TABLE_SCHEDULES` | `queuety_schedules` | Ime tabele urnikov |
| `QUEUETY_TABLE_SIGNALS` | `queuety_signals` | Ime tabele signalov |
| `QUEUETY_TABLE_WORKFLOW_DEPENDENCIES` | `queuety_workflow_dependencies` | Ime tabele čakanj na odvisnosti potekov dela |
| `QUEUETY_TABLE_WORKFLOW_DISPATCH_KEYS` | `queuety_workflow_dispatch_keys` | Ime tabele idempotentnosti trajnih potekov dela |
| `QUEUETY_TABLE_CHUNKS` | `queuety_chunks` | Ime tabele pretočnih kosov |
| `QUEUETY_TABLE_QUEUE_STATES` | `queuety_queue_states` | Ime tabele stanj čakalnih vrst |
| `QUEUETY_TABLE_WEBHOOKS` | `queuety_webhooks` | Ime tabele spletnih kavljev |
| `QUEUETY_TABLE_LOCKS` | `queuety_locks` | Ime tabele zaklepanj |
| `QUEUETY_TABLE_BATCHES` | `queuety_batches` | Ime tabele paketov opravil |
| `QUEUETY_TABLE_WORKFLOW_EVENTS` | `queuety_workflow_events` | Ime tabele dnevnika dogodkov potekov dela |
| `QUEUETY_TABLE_ARTIFACTS` | `queuety_artifacts` | Ime tabele artefaktov potekov dela |
| `QUEUETY_TABLE_STATE_MACHINES` | `queuety_state_machines` | Ime tabele avtomatov stanj |
| `QUEUETY_TABLE_STATE_MACHINE_EVENTS` | `queuety_state_machine_events` | Ime tabele dnevnika dogodkov avtomatov stanj |
| `QUEUETY_DB_DRIVER` | `auto` | Gonilnik MySQL: `auto`, `mysqli` ali `pdo`. `auto` daje prednost `mysqli`, kadar je naložen WordPress, sicer `pdo_mysql`, nato `mysqli` |

Konstanti za sprejemanje virov in prilagodljive skupine (`QUEUETY_RESOURCE_*`, `QUEUETY_WORKER_POOL_*`) sta navedeni na strani [Delavci](https://queuety.inline0.dev/sl/docs/features/workers).

`QUEUETY_TABLE_PREFIX` spremeni samo del imen tabel Queuety. Predpona zbirke podatkov WordPress še vedno obdaja rezultat, zato `$wpdb->prefix = 'wp_'` in `QUEUETY_TABLE_PREFIX = 'themequeue_'` ustvarita tabele, kot je `wp_themequeue_jobs`. Izrecno določene konstante `QUEUETY_TABLE_*` imajo še vedno prednost pri posameznih tabelah.

Samostojne povezave lahko za vsako povezavo nastavijo tudi predpono tabele Queuety:

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

Tako ostane predpona zbirke podatkov WordPress nedotaknjena, spremeni pa se samo segment tabele Queuety.

## Vaše prvo opravilo

Ustvarite razred za obravnavo, ki implementira vmesnik `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,
        ];
    }
}
```

Registrirajte ga in pošljite v izvajanje:

```php
use Queuety\Queuety;

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

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

Lahko uporabite tudi sodobni razred opravila, ki ga je mogoče poslati v izvajanje:

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

## Vaš prvi potek dela

Določite obravnavalnike korakov, ki implementirajo vmesnik `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 [];
    }
}
```

Pošljite potek dela v izvajanje:

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

## Zaženite delavca

```bash
wp queuety work
```

Delavec preverja, ali so na voljo čakajoča opravila, jih izvede, napreduje skozi poteke dela in miruje, ko je čakalna vrsta prazna. Za zaustavitev pritisnite `Ctrl+C`; proces se takoj konča, tudi sredi opravila (glejte [Delavci](https://queuety.inline0.dev/sl/docs/features/workers#worker-lifecycle)).

Zgornji `SendEmailHandler` pošilja svoja opravila v čakalno vrsto `emails` prek `config()`, zato jih delavec na `default` ne prevzame. Navedite vsako čakalno vrsto, ki jo uporabljate:

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

Če ne uporabljate namenskega delavca, ima Queuety še vedno privzeti nadomestni način WordPress cron, opisan zgoraj: zažene se enkrat na minuto, omejen je na čakalno vrsto `default` in obdela eno opravilo na zagon. Namenski delavec omogoča večjo prepustnost in manjšo zakasnitev.

Za produkcijsko okolje zaženite več delavcev:

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

Obdelujte več čakalnih vrst po prednostnem vrstnem redu:

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

## Kaj sledi

- [Opravila](https://queuety.inline0.dev/sl/docs/jobs) za celoten vodnik po pošiljanju v izvajanje in obravnavalnikih
- [Poteki dela](https://queuety.inline0.dev/sl/docs/workflows) za verige, vzporedne korake, pogojno razvejanje in izvajanje potekov dela
- [Vmesna programska oprema](https://queuety.inline0.dev/sl/docs/features/middleware) za omejevanje hitrosti, dušenje in logiko po meri v cevovodu
- [Paketna obdelava](https://queuety.inline0.dev/sl/docs/features/batching) za pošiljanje skupin opravil v izvajanje s povratnimi klici
- [Pretočni koraki](https://queuety.inline0.dev/sl/docs/workflows/streaming) za shranjevanje pretočnih podatkov po posameznih kosih
- [Načrtovanje](https://queuety.inline0.dev/sl/docs/features/scheduling) za ponavljajoča se opravila
- [Predpomnjenje](https://queuety.inline0.dev/sl/docs/features/caching) za razširljivo plast predpomnilnika
- [Testiranje](https://queuety.inline0.dev/sl/docs/features/testing) za QueueFake in preverjanja v testih
- [CLI Referenca](https://queuety.inline0.dev/sl/docs/cli) za vse razpoložljive ukaze
- [PHP API](https://queuety.inline0.dev/sl/docs/api) za programski dostop