Aller au contenu

Traitement par lots

Afficher au format Markdown Modifier sur GitHub Documentation de 2cc7b2b

Les lots vous permettent de déclencher un groupe de tâches et de le suivre comme une seule unité. Vous pouvez enregistrer des callbacks qui se déclenchent lorsque le lot est terminé, lorsqu’une tâche échoue ou lorsque le lot se termine quel que soit le résultat. Queuety suit automatiquement la progression, les échecs et l’état d’annulation.

Créer un lot

Utilisez Queuety::create_batch() pour démarrer un BatchBuilder. Transmettez un tableau d’instances Contracts\Job, puis appelez dispatch() pour créer l’entrée du lot et toutes les tâches.

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() renvoie un objet valeur Batch contenant l’état du lot.

Vous pouvez également transmettre des tableaux gestionnaire + charge utile à la place des instances de tâche :

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

Callbacks

Enregistrez des classes de gestionnaire à appeler à différentes étapes du cycle de vie du lot. Chaque classe de gestionnaire doit avoir une méthode handle( Batch $batch ).

PHP
$batch = Queuety::create_batch( $jobs )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->dispatch();
Méthode Déclenchement
then( $handler_class ) Toutes les tâches sont terminées avec succès (ou allow_failures() est défini)
catch( $handler_class ) La première tâche du lot échoue
finally( $handler_class ) Le lot se termine, qu’il ait réussi ou échoué

Écrire un gestionnaire de callback

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

Autoriser les échecs

Par défaut, le callback then ne se déclenche que si toutes les tâches du lot réussissent. Appelez allow_failures() pour autoriser le déclenchement du callback then même en cas d’échec de certaines tâches.

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

Suivi de la progression

L’objet valeur Batch fournit des propriétés et des méthodes pour suivre la progression.

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
Méthode/Propriété Type Description
progress() int Pourcentage d’achèvement de 0 à 100
finished() bool Indique si le lot est terminé (toutes les tâches sont achevées ou ont échoué)
has_failures() bool Indique si des tâches du lot ont échoué
cancelled() bool Indique si le lot a été annulé
$total_jobs int Nombre total de tâches du lot
$pending_jobs int Nombre de tâches encore en attente
$failed_jobs int Nombre de tâches ayant échoué
$failed_job_ids array ID des tâches ayant échoué
$name string|null Nom facultatif du lot
$created_at DateTimeImmutable Date de création du lot
$finished_at DateTimeImmutable|null Date de fin du lot
$cancelled_at DateTimeImmutable|null Date d’annulation du lot

Annulation

Annulez un lot via le BatchManager. L’annulation d’un lot définit cancelled_at et finished_at, puis déclenche le callback finally.

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

L’annulation marque le lot comme annulé et terminé, puis déclenche son callback finally. Elle ne touche pas aux tâches : celles en attente dans un lot annulé s’exécutent quand même, mais leurs résultats ne mettent plus à jour les compteurs du lot et ne déclenchent plus then, catch ou finally. Supprimez vous-même les tâches si elles ne doivent pas s’exécuter.

Rechercher des lots

Recherchez un lot par son ID :

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

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

Supprimer les anciens lots

Supprimez les lots terminés depuis plus d’un nombre donné de jours :

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

Seuls les lots dont l’horodatage finished_at n’est pas nul sont supprimés. Les lots actifs ne sont jamais purgés.