# Ομαδοποίηση

Οι ομάδες σάς επιτρέπουν να αποστέλλετε ένα σύνολο εργασιών και να τις παρακολουθείτε ως ενιαία μονάδα. Μπορείτε να καταχωρίσετε επανακλήσεις που ενεργοποιούνται όταν ολοκληρωθεί η ομάδα, όταν αποτύχει οποιαδήποτε εργασία ή όταν ολοκληρωθεί η ομάδα ανεξάρτητα από το αποτέλεσμα. Το Queuety παρακολουθεί αυτόματα την πρόοδο, τις αποτυχίες και την κατάσταση ακύρωσης.

## Δημιουργία ομάδας

Χρησιμοποιήστε το `Queuety::create_batch()` για να ξεκινήσετε μια `BatchBuilder`. Περάστε έναν πίνακα από στιγμιότυπα `Contracts\Job` και καλέστε το `dispatch()` για να δημιουργήσετε την εγγραφή της ομάδας και όλες τις εργασίες.

```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()` επιστρέφει ένα αντικείμενο τιμής `Batch` με την κατάσταση της ομάδας.

Μπορείτε επίσης να περάσετε πίνακες handler+payload αντί για στιγμιότυπα εργασιών:

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

## Επανακλήσεις

Καταχωρίστε κλάσεις διαχειριστών που θα καλούνται σε διαφορετικά σημεία του κύκλου ζωής της ομάδας. Κάθε κλάση διαχειριστή πρέπει να διαθέτει μέθοδο `handle( Batch $batch )`.

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

| Μέθοδος | Πότε ενεργοποιείται |
|---|---|
| `then( $handler_class )` | Όλες οι εργασίες ολοκληρώθηκαν επιτυχώς (ή έχει οριστεί το `allow_failures()`) |
| `catch( $handler_class )` | Αποτυγχάνει η πρώτη εργασία της ομάδας |
| `finally( $handler_class )` | Η ομάδα ολοκληρώνεται, είτε επιτύχει είτε αποτύχει |

### Σύνταξη χειριστή επανάκλησης

```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.
    }
}
```

## Επιτρέπονται αποτυχίες

Από προεπιλογή, η επανάκληση `then` ενεργοποιείται μόνο αν επιτύχουν όλες οι εργασίες της ομάδας. Καλέστε το `allow_failures()` για να επιτρέψετε στην επανάκληση `then` να ενεργοποιείται ακόμη κι όταν αποτύχουν ορισμένες εργασίες.

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

## Παρακολούθηση προόδου

Το αντικείμενο τιμής `Batch` παρέχει ιδιότητες και μεθόδους για την παρακολούθηση της προόδου.

```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
```

| Μέθοδος/Ιδιότητα | Τύπος | Περιγραφή |
|---|---|---|
| `progress()` | `int` | Ποσοστό ολοκλήρωσης από 0 έως 100 |
| `finished()` | `bool` | Αν η ομάδα έχει ολοκληρωθεί (όλες οι εργασίες ολοκληρώθηκαν ή απέτυχαν) |
| `has_failures()` | `bool` | Αν απέτυχε κάποια εργασία της ομάδας |
| `cancelled()` | `bool` | Αν η ομάδα ακυρώθηκε |
| `$total_jobs` | `int` | Συνολικός αριθμός εργασιών στην ομάδα |
| `$pending_jobs` | `int` | Αριθμός εργασιών που εκκρεμούν ακόμη |
| `$failed_jobs` | `int` | Αριθμός εργασιών που απέτυχαν |
| `$failed_job_ids` | `array` | Τα ID των εργασιών που απέτυχαν |
| `$name` | `string\|null` | Προαιρετικό όνομα ομάδας |
| `$created_at` | `DateTimeImmutable` | Πότε δημιουργήθηκε η ομάδα |
| `$finished_at` | `DateTimeImmutable\|null` | Πότε ολοκληρώθηκε η ομάδα |
| `$cancelled_at` | `DateTimeImmutable\|null` | Πότε ακυρώθηκε η ομάδα |

## Ακύρωση

Ακυρώστε μια ομάδα μέσω του `BatchManager`. Η ακύρωση μιας ομάδας ορίζει τα `cancelled_at` και `finished_at` και ενεργοποιεί την επανάκληση `finally`.

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

Η ακύρωση επισημαίνει την ομάδα ως ακυρωμένη και ολοκληρωμένη και ενεργοποιεί την επανάκλησή της `finally`. Δεν επηρεάζει τις εργασίες: οι εκκρεμείς εργασίες σε μια ακυρωμένη ομάδα εξακολουθούν να εκτελούνται, αλλά τα αποτελέσματά τους δεν ενημερώνουν πλέον τους μετρητές της ομάδας ούτε ενεργοποιούν τα `then`, `catch` ή `finally`. Διαγράψτε μόνοι σας τις εργασίες αν δεν πρέπει να εκτελεστούν.

## Εύρεση ομάδων

Αναζητήστε μια ομάδα βάσει του ID της:

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

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

## Εκκαθάριση παλιών ομάδων

Αφαιρέστε ολοκληρωμένες ομάδες παλαιότερες από έναν καθορισμένο αριθμό ημερών:

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

Διαγράφονται μόνο ομάδες με μη μηδενική χρονική σήμανση `finished_at`. Οι ενεργές ομάδες δεν εκκαθαρίζονται ποτέ.