批处理

以 Markdown 格式查看在 GitHub 上编辑文档位置 2cc7b2b

批次让你能够分派一组任务，并将它们作为一个整体进行跟踪。你可以注册回调，以便在批次完成、任一任务失败或批次无论结果如何结束时触发。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 值对象。

你也可以传入处理程序和载荷数组，而不是任务实例：

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 时间戳的批次才会被删除。活动中的批次永远不会被清理。