انتقل إلى المحتوى

المعالجة على دفعات

تتيح لك الدفعات إرسال مجموعة من المهام وتتبعها كوحدة واحدة. يمكنك تسجيل عمليات استدعاء تُنفّذ عند اكتمال الدفعة، أو فشل أي مهمة، أو انتهاء الدفعة أيًا كانت النتيجة. يتتبع 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 معرّفات المهام التي فشلت
$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. احذف المهام بنفسك إذا كان يجب ألا تُنفّذ.

العثور على الدفعات

ابحث عن دفعة باستخدام معرّفها:

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. ولا تُنظّف الدفعات النشطة مطلقًا.