# Planavimas

Queuety turi integruotą pasikartojančių užduočių palaikymą. Užuot pasikliaujant `wp_cron`, tvarkaraščiai saugomi duomenų bazėje ir maždaug kartą per minutę vertinami ilgai veikiančiame `wp queuety work` procese (arba vykdytojų grupės tėviniame procese). `wp queuety work --once`, `wp queuety flush` ir įskiepio integruotas WP-Cron atsarginis mechanizmas tvarkaraščių nevertina ([#14](https://github.com/inline0/queuety/issues/14)); jei ilgai veikiančio vykdytojo nėra, paleiskite `wp queuety schedule run` patys.

## Planavimas pagal intervalą

Paprastiems intervalais pagrįstiems tvarkaraščiams naudokite `every()`. Išraiška gali būti bet kuri eilutė, suderinama su PHP `DateTimeImmutable::modify()`:

```php
use Queuety\Queuety;

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

Queuety::schedule( 'sync_inventory' )
    ->every( '30 minutes' )
    ->on_queue( 'sync' );

Queuety::schedule( 'daily_report', [ 'type' => 'summary' ] )
    ->every( '1 day' );
```

## Planavimas pagal Cron

Standartinėms 5 laukų cron išraiškoms naudokite `cron()`:

```php
// Every day at 3am
Queuety::schedule( 'nightly_cleanup' )
    ->cron( '0 3 * * *' );

// Every Monday at 9am
Queuety::schedule( 'weekly_digest' )
    ->cron( '0 9 * * 1' )
    ->on_queue( 'emails' );

// Every 15 minutes
Queuety::schedule( 'health_check' )
    ->cron( '*/15 * * * *' );
```

## Tvarkaraščio parinktys

`PendingSchedule` kūrimo priemonė palaiko šiuos metodus:

| Metodas | Aprašymas |
|---|---|
| `every( string $interval )` | Nustatyti intervalo išraišką |
| `cron( string $expression )` | Nustatyti cron išraišką |
| `on_queue( string $queue )` | Nustatyti tikslinę eilę (numatytoji: `'default'`) |
| `overlap( OverlapPolicy $policy )` | Nustatyti persidengimo politiką (numatytoji: `Allow`) |

Prieš išsiunčiant užduotį pagal tvarkaraštį, būtina iškviesti arba `every()`, arba `cron()`. Jei nenustatytas nė vienas, išmetama `RuntimeException`.

## Persidengimo politika

Jei kitos žymos suveikimo metu suplanuota užduotis vis dar vykdoma (laukiama arba apdorojama), persidengimo politika nustato, kas bus daroma. Nustatykite ją naudodami metodą `overlap()`:

```php
use Queuety\Queuety;
use Queuety\Enums\OverlapPolicy;

Queuety::schedule( 'sync_inventory' )
    ->every( '5 minutes' )
    ->overlap( OverlapPolicy::Skip )
    ->on_queue( 'sync' );
```

`OverlapPolicy` sąrašas turi tris parinktis:

| Politika | Reikšmė | Veikimas |
|---|---|---|
| `OverlapPolicy::Allow` | `allow` | Visada išsiunčiama nauja užduotis, net jei ankstesnis vykdymas vis dar aktyvus. Tai numatytoji parinktis. |
| `OverlapPolicy::Skip` | `skip` | Praleidžiama dabartinė žyma, jei apdorojimo komponentas turi laukiančių arba apdorojamų užduočių. `next_run` atnaujinamas įprastai, todėl tvarkaraščio ritmas išlaikomas. |
| `OverlapPolicy::Buffer` | `buffer` | Kaip ir „Skip“ atveju, žyma neišsiunčiama, o `next_run` pereina prie kito reguliaraus įvykio. Skirtingai nei „Skip“ atveju, `last_run` neatnaujinamas. |

### Allow (numatytoji parinktis)

Vienu metu gali veikti keli to paties apdorojimo komponento egzemplioriai. Naudokite šią parinktį idempotentiniams apdorojimo komponentams, kurių persidengimas nekenkia.

```php
Queuety::schedule( 'send_heartbeat_ping' )
    ->every( '1 minute' )
    ->overlap( OverlapPolicy::Allow );
```

### Skip

Žyma tyliai praleidžiama, jei apdorojimo komponentas vis dar veikia. Naudokite šią parinktį, kai antras egzempliorius būtų nenaudingas arba sukeltų konfliktų.

```php
Queuety::schedule( 'rebuild_search_index' )
    ->every( '10 minutes' )
    ->overlap( OverlapPolicy::Skip );
```

### Buffer

Šiuo metu veikia taip pat kaip „Skip“: jei apdorojimo komponentas turi laukiančią arba apdorojamą užduotį, žyma neišsiunčiama, o `next_run` pereina prie kito reguliaraus įvykio. Skiriasi tik tuo, kad „Buffer“ palieka `last_run` nepakeistą, o „Skip“ įrašo praleistą žymą kaip paskutinį vykdymą.

```php
Queuety::schedule( 'sync_inventory' )
    ->every( '5 minutes' )
    ->overlap( OverlapPolicy::Buffer );
```

## Kaip tai veikia

Sukūrus tvarkaraštį, Queuety išsaugo jį lentelėje `queuety_schedules` kartu su išraiška, apdorojimo komponentu, duomenimis ir kitu apskaičiuotu vykdymo laiku.

Per kiekvieną planuoklio žymą (maždaug kartą per minutę ilgai veikiančiame vykdytojuje arba paleidus `wp queuety schedule run`) planuoklis patikrina, kurių tvarkaraščių `next_run` laikas jau atėjo. Kiekvienam suėjusiam tvarkaraščiui išsiunčiama nauja užduotis, o `next_run` atnaujinamas iki kito įvykio.

## Tvarkaraščių valdymas per CLI

```bash
# List all schedules
wp queuety schedule list

# Add a recurring schedule
wp queuety schedule add cleanup_handler --every="1 hour"
wp queuety schedule add nightly_report --cron="0 3 * * *" --queue=reports

# Remove a schedule
wp queuety schedule remove cleanup_handler

# Manually trigger the scheduler
wp queuety schedule run
```

## Tvarkaraščių valdymas per PHP

```php
// Get the scheduler instance
$scheduler = Queuety::scheduler();

// List all schedules
$schedules = $scheduler->list();

// Remove a schedule by handler name
$scheduler->remove( 'cleanup_handler' );

// Manually trigger a tick
$count = $scheduler->tick();
```

## Duomenys

Tvarkaraščiuose gali būti statinių duomenų, kurie perduodami kiekvienai išsiųstai užduočiai:

```php
Queuety::schedule( 'generate_report', [ 'type' => 'daily', 'format' => 'pdf' ] )
    ->every( '1 day' )
    ->on_queue( 'reports' );
```

Kaskart suveikus tvarkaraščiui, išsiunčiama nauja užduotis su šiais duomenimis.