Batchverarbeitung

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 2cc7b2b

Mit Batches kannst du eine Gruppe von Jobs auslösen und als Einheit verfolgen. Du kannst Rückrufe registrieren, die beim Abschluss des Batches, beim Fehlschlagen eines beliebigen Jobs oder beim Ende des Batches unabhängig vom Ergebnis ausgeführt werden. Queuety erfasst Fortschritt, Fehler und den Abbruchstatus automatisch.

Batch erstellen

Verwende Queuety::create_batch(), um einen BatchBuilder zu starten. Übergib ein Array mit Instanzen von Contracts\Job und rufe dann dispatch() auf, um den Batch-Eintrag und alle Jobs zu erstellen.

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() gibt ein Batch-Wertobjekt mit dem Batch-Status zurück.

Du kannst statt Job-Instanzen auch Arrays mit Handler und Nutzdaten übergeben:

PHP

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

Rückrufe

Registriere Handler-Klassen, die an verschiedenen Punkten im Lebenszyklus des Batches aufgerufen werden. Jede Handler-Klasse muss über eine Methode handle( Batch $batch ) verfügen.

PHP

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

Methode	Zeitpunkt der Ausführung
`then( $handler_class )`	Alle Jobs wurden erfolgreich abgeschlossen (oder `allow_failures()` ist gesetzt)
`catch( $handler_class )`	Der erste Job im Batch schlägt fehl
`finally( $handler_class )`	Der Batch endet, unabhängig davon, ob er erfolgreich war oder fehlschlug

Einen Rückruf-Handler schreiben

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

Fehler zulassen

Standardmäßig wird der Rückruf then nur ausgeführt, wenn alle Jobs im Batch erfolgreich sind. Rufe allow_failures() auf, damit der Rückruf then auch bei fehlgeschlagenen Jobs ausgeführt wird.

PHP

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

Fortschritt verfolgen

Das Wertobjekt Batch stellt Eigenschaften und Methoden zur Fortschrittsverfolgung bereit.

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

Methode/Eigenschaft	Typ	Beschreibung
`progress()`	`int`	Fortschritt in Prozent von 0 bis 100
`finished()`	`bool`	Gibt an, ob der Batch beendet ist (alle Jobs abgeschlossen oder fehlgeschlagen)
`has_failures()`	`bool`	Gibt an, ob Jobs im Batch fehlgeschlagen sind
`cancelled()`	`bool`	Gibt an, ob der Batch abgebrochen wurde
`$total_jobs`	`int`	Gesamtzahl der Jobs im Batch
`$pending_jobs`	`int`	Anzahl der noch ausstehenden Jobs
`$failed_jobs`	`int`	Anzahl der fehlgeschlagenen Jobs
`$failed_job_ids`	`array`	IDs der fehlgeschlagenen Jobs
`$name`	`string\|null`	Optionaler Batchname
`$created_at`	`DateTimeImmutable`	Zeitpunkt der Batcherstellung
`$finished_at`	`DateTimeImmutable\|null`	Zeitpunkt des Batchabschlusses
`$cancelled_at`	`DateTimeImmutable\|null`	Zeitpunkt des Batchabbruchs

Abbrechen

Brich einen Batch über BatchManager ab. Dadurch werden cancelled_at und finished_at gesetzt und der Rückruf finally ausgeführt.

PHP

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

Beim Abbrechen wird der Batch als abgebrochen und beendet markiert und sein Rückruf finally ausgeführt. Die Jobs bleiben unberührt: Ausstehende Jobs eines abgebrochenen Batches werden weiterhin ausgeführt, ihre Ergebnisse aktualisieren jedoch nicht mehr die Batch-Zähler und lösen then, catch oder finally nicht aus. Lösche die Jobs selbst, wenn sie nicht ausgeführt werden sollen.

Batches finden

Einen Batch anhand seiner ID suchen:

PHP

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

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

Alte Batches bereinigen

Beendete Batches löschen, die älter als eine bestimmte Anzahl von Tagen sind:

PHP

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

Gelöscht werden nur Batches mit einem Zeitstempel für finished_at, der nicht null ist. Aktive Batches werden nie bereinigt.