# Grupēšana

Paketes ļauj izsūtīt uzdevumu grupu un sekot tai kā vienai vienībai. Varat reģistrēt atzvanus, kas tiek izsaukti, kad pakete ir pabeigta, kad neizdodas kāds uzdevums vai kad pakete tiek pabeigta neatkarīgi no iznākuma. Queuety automātiski seko progresam, kļūmēm un atcelšanas statusam.

## Paketes izveide

Izmantojiet `Queuety::create_batch()`, lai sāktu `BatchBuilder`. Padodiet `Contracts\Job` eksemplāru masīvu un pēc tam izsauciet `dispatch()`, lai izveidotu paketes ierakstu un visus uzdevumus.

```php
use Queuety\Queuety;

$batch = Queuety::create_batch( [
    new ImportUsersJob( $csv_chunk_1 ),
    new ImportUsersJob( $csv_chunk_2 ),
    new ImportUsersJob( $csv_chunk_3 ),
] )
    ->name( 'Import users' )
    ->on_queue( 'imports' )
    ->dispatch();

echo $batch->id; // The batch ID
```

`dispatch()` atgriež `Batch` vērtības objektu ar paketes stāvokli.

Uzdevumu eksemplāru vietā varat padot arī apstrādātāja un satura masīvus:

```php
$batch = Queuety::create_batch( [
    [ 'handler' => 'import_users', 'payload' => [ 'chunk' => 1 ] ],
    [ 'handler' => 'import_users', 'payload' => [ 'chunk' => 2 ] ],
] )->dispatch();
```

## Atzvani

Reģistrējiet apstrādātāju klases, ko izsaukt dažādos paketes dzīves cikla brīžos. Katrā apstrādātāja klasē jābūt metodei `handle( Batch $batch )`.

```php
$batch = Queuety::create_batch( $jobs )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->dispatch();
```

| Metode | Izsaukšanas brīdis |
|---|---|
| `then( $handler_class )` | Visi uzdevumi ir veiksmīgi pabeigti (vai ir iestatīts `allow_failures()`) |
| `catch( $handler_class )` | Neizdodas pirmais paketes uzdevums |
| `finally( $handler_class )` | Pakete tiek pabeigta neatkarīgi no tā, vai tā izdevās vai ne |

### Atzvana apstrādātāja izveide

```php
use Queuety\Batch;

class ImportCompleteHandler {
    public function handle( Batch $batch ): void {
        // All users imported. Send a notification.
        error_log( "Batch {$batch->id} completed: {$batch->total_jobs} jobs processed." );
    }
}

class ImportFailedHandler {
    public function handle( Batch $batch ): void {
        error_log( "Batch {$batch->id} had a failure. Failed jobs: {$batch->failed_jobs}" );
    }
}

class ImportCleanupHandler {
    public function handle( Batch $batch ): void {
        // Runs regardless of outcome. Clean up temp files, etc.
    }
}
```

## Kļūmju pieļaušana

Pēc noklusējuma atzvans `then` tiek izsaukts tikai tad, ja visi paketes uzdevumi izdodas. Izsauciet `allow_failures()`, lai atzvans `then` tiktu izsaukts arī tad, ja daži uzdevumi neizdodas.

```php
$batch = Queuety::create_batch( $jobs )
    ->then( ReportHandler::class )
    ->allow_failures()
    ->dispatch();
```

## Progresa uzskaite

Vērtības objekts `Batch` nodrošina rekvizītus un metodes progresa uzskaitei.

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

$batch->progress();      // 0-100 percentage
$batch->finished();      // true if all jobs are done
$batch->has_failures();  // true if any job failed
$batch->cancelled();     // true if the batch was cancelled

$batch->total_jobs;      // Total number of jobs
$batch->pending_jobs;    // Jobs still pending
$batch->failed_jobs;     // Number of failed jobs
$batch->failed_job_ids;  // Array of failed job IDs
```

| Metode/rekvizīts | Tips | Apraksts |
|---|---|---|
| `progress()` | `int` | Pabeigšanas procentuālā daļa no 0 līdz 100 |
| `finished()` | `bool` | Vai pakete ir pabeigta (visi uzdevumi ir izpildīti vai neizdevušies) |
| `has_failures()` | `bool` | Vai kāds paketes uzdevums nav izdevies |
| `cancelled()` | `bool` | Vai pakete ir atcelta |
| `$total_jobs` | `int` | Kopējais uzdevumu skaits paketē |
| `$pending_jobs` | `int` | Vēl neizpildīto uzdevumu skaits |
| `$failed_jobs` | `int` | Neizdevušos uzdevumu skaits |
| `$failed_job_ids` | `array` | Neizdevušos uzdevumu ID |
| `$name` | `string\|null` | Neobligāts paketes nosaukums |
| `$created_at` | `DateTimeImmutable` | Paketes izveides laiks |
| `$finished_at` | `DateTimeImmutable\|null` | Paketes pabeigšanas laiks |
| `$cancelled_at` | `DateTimeImmutable\|null` | Paketes atcelšanas laiks |

## Atcelšana

Atceliet paketi, izmantojot `BatchManager`. Atceļot paketi, tiek iestatīti `cancelled_at` un `finished_at`, kā arī izsaukts atzvans `finally`.

```php
Queuety::batch_manager()->cancel( $batch_id );
```

Atcelšana atzīmē paketi kā atceltu un pabeigtu, kā arī izsauc tās atzvanu `finally`. Tā neietekmē uzdevumus: neizpildītie uzdevumi atceltā paketē joprojām tiek izpildīti, taču to rezultāti vairs neatjaunina paketes skaitītājus un neizraisa `then`, `catch` vai `finally` izsaukšanu. Ja uzdevumi nedrīkst tikt izpildīti, izdzēsiet tos paši.

## Paketju atrašana

Meklējiet paketi pēc tās ID:

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

if ( null === $batch ) {
    // Batch not found.
}
```

## Vecu pakešu iztīrīšana

Noņemiet pabeigtās paketes, kas ir vecākas par norādīto dienu skaitu:

```php
$deleted = Queuety::batch_manager()->prune( 30 ); // Delete batches finished > 30 days ago
```

Tiek dzēstas tikai paketes, kurām ir laikspiedols `finished_at`, kas nav null. Aktīvās paketes nekad netiek iztīrītas.