PHP API

عرض بتنسيق Markdown التعديل على GitHub التوثيق في 2cc7b2b

يمكن الوصول إلى كل شيء في Queuety عبر الفئة الثابتة Queuety\Queuety. وهي نقطة الدخول الوحيدة لإرسال المهام، وبناء مسارات العمل، وتشغيل آلات الحالة، وإدارة قوائم الانتظار، والوصول إلى الأنظمة الفرعية الداخلية.

PHP

use Queuety\Queuety;

الوصول المستقل إلى النواة

يمكن تهيئة بيئة التشغيل المدعومة بقاعدة بيانات الخاصة بـ Queuety خارج WordPress.

هذا المسار المستقل مخصص لنواة التنسيق:

المهام والعاملون (تحتاج مجموعات العاملين أيضًا إلى الثوابت DB_HOST وDB_NAME وDB_USER وDB_PASSWORD، راجع أدناه)
تدفقات العمل والإشارات
آلات الحالات والأحداث
العناصر الأثرية والسجلات والمقاييس والجداول الزمنية

لا يُعد بديلًا عن المحوّل WordPress. لا يزال كل من Queuety::on_action() وreplace_wp_cron() وتهيئة الإضافة ومسار تسجيل wp queuety ... الفعلي يتطلب WordPress.

`Queuety::init( Connection $conn )`

هيّئ Queuety باتصال مباشر مدعوم بقاعدة بيانات.

PHP

use Queuety\Connection;
use Queuety\Queuety;

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
);

Queuety::init( $conn );

تغيّر الوسيطة الاختيارية table_prefix الجزء Queuety من أسماء جداول بيئة التشغيل لكل اتصال:

PHP

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
    table_prefix: 'themequeue_',
);

يحوّل ذلك جداول مثل queuety_jobs إلى wp_themequeue_jobs.

`Queuety::ensure_schema()`

تأكد من وجود جداول بيئة التشغيل Queuety للاتصال النشط.

PHP

Queuety::init( $conn );
Queuety::ensure_schema();

للاطلاع على النموذج الكامل وحدود WordPress، راجع الاستخدام المستقل.

المهام

`Queuety::dispatch( $handler, $payload )`

أرسل مهمة. يقبل اسم معالج كسلسلة نصية أو مثيلًا من Contracts\Job. ويُرجع منشئًا PendingJob لتسلسل الخيارات.

PHP

// Handler name + payload (original API)
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

// Contracts\Job instance (v0.6.0+)
Queuety::dispatch( new SendEmailJob( to: 'user@example.com' ) );

// With options
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] )
    ->on_queue( 'emails' )
    ->with_priority( Priority::High )
    ->delay( 300 )
    ->max_attempts( 5 )
    ->rate_limit( 10, 60 )
    ->unique()
    ->after( $other_job_id );

// Get the job ID
$job_id = Queuety::dispatch( 'send_email', $payload )->id();

عند تمرير مثيل من Contracts\Job، يستخرج المُسلسِل FQCN بوصفه اسم المعالج والخصائص العامة بوصفها الحمولة. ويتم تجاهل المعامل $payload عندما تكون $handler مثيلًا من Job.

طرق `PendingJob`

الطريقة	الوصف
`on_queue( string $queue )`	تعيين قائمة الانتظار المستهدفة
`with_priority( Priority $priority )`	تعيين مستوى الأولوية
`delay( int $seconds )`	التأخير قبل إتاحة المهمة
`max_attempts( int $max )`	الحد الأقصى لمحاولات إعادة المحاولة
`rate_limit( int $max, int $window )`	تحديد المعدل: الحد الأقصى للتنفيذات خلال نافذة زمنية بالثواني
`unique()`	منع الإرسال المكرر
`after( int $job_id )`	انتظار اكتمال مهمة أخرى أولًا
`concurrency_group( string $group, int $limit )`	وضع المهمة ضمن مجموعة مشتركة لقبول العاملين
`cost_units( int $units )`	إرفاق بيانات وصفية للتكلفة النسبية للتنفيذ بعملية الإرسال
`id()`	فرض الإرسال وإرجاع معرّف المهمة

يدعم كل من concurrency_group() وcost_units() نموذج إدارة الموارد الأوسع، ما يتيح لعملية الإرسال نفسها المشاركة في حدود التزامن القائمة على العدد، وميزانيات قوائم الانتظار أو مزوّدي الخدمة الموزونة، وأساليب الاستدلال لقبول العاملين.

`Queuety::dispatch_sync( $handler, $payload )`

نفّذ مهمة بشكل متزامن في العملية الحالية دون إضافتها إلى قائمة الانتظار.

PHP

// With a Job instance
Queuety::dispatch_sync( new SendEmailJob( to: 'user@example.com', subject: 'Hi', body: 'Hello' ) );

// With a handler name and payload
Queuety::dispatch_sync( 'send_email', [ 'to' => 'user@example.com' ] );

يُستدعى أسلوب handle() الخاص بالمهمة مباشرة. لا يُنشأ أي سجل في قاعدة البيانات، ولا يُستخدم أي عامل، ولا تُطبّق البرمجيات الوسيطة.

`Queuety::batch( $jobs )`

أرسل عدة مهام في تعليمة INSERT واحدة متعددة الصفوف.

PHP

$job_ids = Queuety::batch( [
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'a@example.com' ], 'queue' => 'emails' ],
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'b@example.com' ], 'priority' => 2 ],
] );

`Queuety::create_batch( $jobs )`

أنشئ BatchBuilder لإرسال مجموعة من المهام مع عمليات الاستدعاء وتتبع التقدم. راجع التجميع للاطلاع على التفاصيل الكاملة.

PHP

$batch = Queuety::create_batch( [
    new ImportUsersJob( $chunk_1 ),
    new ImportUsersJob( $chunk_2 ),
] )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->allow_failures()
    ->on_queue( 'imports' )
    ->dispatch();

طرق `BatchBuilder`

الطريقة	القيمة المُعادة	الوصف
`name( string $name )`	`self`	تعيين اسم للمجموعة
`on_queue( string $queue )`	`self`	تعيين قائمة الانتظار لجميع مهام المجموعة
`then( string $handler_class )`	`self`	معالج يُستدعى عند اكتمال المجموعة بنجاح
`catch( string $handler_class )`	`self`	معالج يُستدعى عند فشل أول مهمة في المجموعة
`finally( string $handler_class )`	`self`	معالج يُستدعى عند انتهاء المجموعة، سواء بالنجاح أو الفشل
`allow_failures()`	`self`	السماح باستدعاء `then` حتى عند وجود إخفاقات
`dispatch()`	`Batch`	إنشاء سجل المجموعة وجميع المهام، وإرجاع كائن القيمة `Batch`

`Queuety::find_batch( $id )`

اعثر على مجموعة حسب المعرّف. يُرجع كائن قيمة Batch أو null.

PHP

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

if ( null !== $batch ) {
    echo $batch->progress() . '% complete';
}

التحكم بالعاملين

`Queuety::run_worker( $queue = 'default', $once = false )`

شغّل حلقة عامل واحدة مباشرة.

PHP

Queuety::run_worker( 'default' );
Queuety::run_worker( 'critical,default', true );

`Queuety::run_worker_pool( $workers, $queue = 'default' )`

شغّل مجموعة عاملين مباشرة بحجم ثابت. يتطلب امتدادي pcntl وposix. تقرأ المجموعة ثوابت WordPress وDB_HOST وDB_NAME وDB_USER وDB_PASSWORD لاتصالاتها الفرعية (ولا تأتي من الاتصال المُهيّأ سوى بادئات الجداول)، لذا عرّفها عند تشغيل مجموعة خارج WordPress (#5).

PHP

Queuety::run_worker_pool( 4, 'providers' );

`Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )`

شغّل مجموعة عاملين تكيفية مباشرة. تنطبق المتطلبات نفسها على run_worker_pool().

PHP

Queuety::run_auto_scaling_worker_pool( 2, 6, 'providers' );

كائن القيمة `Batch`

الطريقة/الخاصية	النوع	الوصف
`$id`	`int`	معرّف المجموعة
`$name`	`string\|null`	اسم المجموعة، اختياري
`$total_jobs`	`int`	إجمالي عدد المهام في المجموعة
`$pending_jobs`	`int`	المهام التي لا تزال قيد الانتظار
`$failed_jobs`	`int`	عدد المهام الفاشلة
`$failed_job_ids`	`array`	معرّفات المهام الفاشلة
`$created_at`	`DateTimeImmutable`	وقت إنشاء المجموعة
`$finished_at`	`DateTimeImmutable\|null`	وقت انتهاء المجموعة
`$cancelled_at`	`DateTimeImmutable\|null`	وقت إلغاء المجموعة
`progress()`	`int`	نسبة الاكتمال (0-100)
`finished()`	`bool`	ما إذا كانت المجموعة قد انتهت
`has_failures()`	`bool`	ما إذا كانت أي مهمة قد فشلت
`cancelled()`	`bool`	ما إذا كانت المجموعة قد أُلغيت

`Queuety::chain( $jobs )`

أنشئ ChainBuilder لتنفيذ المهام بالتتابع. تعتمد كل مهمة على اكتمال المهمة السابقة بنجاح.

PHP

$first_job_id = Queuety::chain( [
    new FetchDataJob( $url ),
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )
    ->on_queue( 'pipeline' )
    ->catch( ChainFailedHandler::class )
    ->dispatch();

طرق `ChainBuilder`

الطريقة	القيمة المُعادة	الوصف
`on_queue( string $queue )`	`self`	تعيين قائمة الانتظار لجميع مهام السلسلة
`catch( string $handler_class )`	`self`	معالج يُستدعى عند دفن أي مهمة في السلسلة نهائيًا
`dispatch()`	`int`	إنشاء جميع المهام مع تبعيات متسلسلة، وإرجاع معرّف المهمة الأولى

`Queuety::retry( $job_id )`

أعِد محاولة مهمة محددة. وتُعاد حالتها إلى pending.

PHP

Queuety::retry( 42 );

`Queuety::retry_buried()`

أعِد محاولة جميع المهام المدفونة. يُرجع عدد المهام التي أُعيدت محاولتها.

PHP

$count = Queuety::retry_buried();

`Queuety::purge( $older_than_days )`

احذف المهام المكتملة. يُرجع عدد المهام المحذوفة.

PHP

$count = Queuety::purge();     // uses QUEUETY_RETENTION_DAYS
$count = Queuety::purge( 30 ); // purge jobs older than 30 days

قوائم الانتظار

`Queuety::stats( $queue )`

احصل على أعداد المهام مجمّعة حسب الحالة.

PHP

$stats = Queuety::stats();          // all queues
$stats = Queuety::stats( 'emails' ); // specific queue
// ['pending' => 12, 'processing' => 3, 'completed' => 150, 'failed' => 2, 'buried' => 1]

`Queuety::buried( $queue )`

احصل على جميع المهام المدفونة.

PHP

$jobs = Queuety::buried();
$jobs = Queuety::buried( 'emails' );

`Queuety::pause( $queue )`

أوقف قائمة انتظار مؤقتًا كي يتجاوزها العاملون.

PHP

Queuety::pause( 'emails' );

`Queuety::resume( $queue )`

استأنف قائمة انتظار متوقفة مؤقتًا.

PHP

Queuety::resume( 'emails' );

`Queuety::is_paused( $queue )`

تحقق مما إذا كانت قائمة الانتظار متوقفة مؤقتًا.

PHP

if ( Queuety::is_paused( 'emails' ) ) {
    // Queue is paused
}

تدفقات العمل

`Queuety::workflow( $name )`

ابدأ إنشاء تدفق عمل. يُرجع WorkflowBuilder.

PHP

$workflow_id = Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

طرق `WorkflowBuilder`

الطريقة	الوصف
`then( string $handler_class, ?string $name = null )`	إضافة خطوة متسلسلة. اسم اختياري للتفرع الشرطي.
`parallel( array $handler_classes )`	إضافة مجموعة خطوات متوازية.
`for_each( string $items_key, string $handler_class, ?string $result_key = null, ForEachMode $mode = ForEachMode::All, ?int $quorum = null, ?string $reducer_class = null, ?string $name = null )`	إضافة خطوة ديناميكية للتكرار على العناصر، تنشئ مهمة فرعية لكل عنصر في حالة تدفق العمل.
`repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	الرجوع إلى خطوة مسماة سابقة ما دام مفتاح حالة عام أو صنف `RepeatCondition` مطابقًا.
`repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	الرجوع إلى خطوة مسماة سابقة إلى أن يطابق مفتاح حالة عام أو صنف `RepeatCondition`.
`run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )`	إضافة خطوة لتشغيل تدفق عمل.
`delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	إضافة خطوة تأخير دائم. تُجمع مدد التأخير كلها.
`wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )`	إضافة خطوة انتظار إشارة. يتيح لك كل من `match_payload` و`correlation_key` اختياريًا تجاهل الأحداث غير المرتبطة.
`wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	انتظار كل الإشارات أو بعضها، مع مطابقة اختيارية للحمولة وربطها.
`wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	انتظار إشارة موافقة بشرية.
`wait_for_decision( string $approve_signal = 'approved', string $reject_signal = 'rejected', ?string $result_key = 'decision', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	انتظار الموافقة أو الرفض، وتخزين حمولة قرار منظّمة.
`wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	انتظار إشارة إدخال بشري.
`wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )`	انتظار اكتمال معرّف تدفق عمل واحد أو معرّف مخزّن في الحالة العامة.
`wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )`	انتظار اكتمال جميع تدفقات العمل أو بعضها أو النصاب المطلوب منها.
`wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )`	انتظار مجموعة تدفقات عمل بدأت سابقًا باستخدام مفتاح المجموعة الداخلي.
`start_workflows( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'started_workflow_ids', string $payload_key = 'item', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	إرسال تدفق عمل رئيسي واحد لكل عنصر في بيئة التشغيل، مع خيار وسم المجموعة التي بدأ تشغيلها بمفتاح مجموعة دائم.
`start_agents( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'agent_workflow_ids', string $payload_key = 'agent_task', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	اسم بديل موجّه للوكلاء لـ `start_workflows()`.
`wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )`	اسم بديل موجّه للوكلاء لـ `wait_for_workflows()`.
`wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )`	اسم بديل موجّه للوكلاء لـ `wait_for_workflow_group()`.
`version( string $version )`	وسم تعريف تدفق العمل بإصدار على مستوى التطبيق لتسهيل الفحص والتصدير.
`idempotency_key( string $key )`	جعل إرسال تدفق العمل دائمًا باستخدام مفتاح يقدمه المستدعي. يؤدي الإرسال مجددًا بالمفتاح نفسه إلى إرجاع معرّف تدفق العمل الأصلي.
`max_transitions( int $max )`	إخفاق تدفق العمل إذا اكتمل أكثر من `$max` انتقالات للخطوات.
`max_for_each_items( int $max )`	إخفاق تدفق العمل إذا حاولت خطوة `for_each()` توسيع أكثر من `$max` عنصرًا.
`max_state_bytes( int $bytes )`	إخفاق تدفق العمل إذا تجاوز حجم الحالة العامة `$bytes`.
`max_cost_units( int $max )`	إخفاق تدفق العمل إذا استهلكت الخطوات المكتملة أكثر من `$max` وحدة تكلفة.
`max_started_workflows( int $max )`	إخفاق تدفق العمل قبل إرسال أكثر من `$max` من تدفقات العمل الفرعية.
`compensate_with( string $handler_class )`	إرفاق معالج تعويض بآخر خطوة أُضيفت.
`compensate_on_failure()`	تشغيل عمليات تعويض الخطوات المكتملة تلقائيًا عند إخفاق تدفق العمل.
`on_queue( string $queue )`	تعيين قائمة الانتظار لجميع الخطوات.
`with_priority( Priority $priority )`	تعيين الأولوية لجميع الخطوات.
`max_attempts( int $max )`	تعيين الحد الأقصى لمحاولات إعادة المحاولة لكل خطوة.
`on_cancel( string $handler_class )`	تسجيل صنف معالج للتنظيف عند الإلغاء. راجع الإلغاء.
`prune_state_after( int $steps = 2 )`	تفعيل تشذيب الحالة تلقائيًا. يزيل مخرجات الخطوات الأقدم من الحد الزمني. راجع تشذيب الحالة.
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	تعيين موعد نهائي لتدفق العمل. تُجمع مدد التأخير كلها. راجع المواعيد النهائية.
`on_deadline( string $handler_class )`	تسجيل معالج يُستدعى عند تجاوز الموعد النهائي لتدفق العمل. راجع المواعيد النهائية.
`dispatch( array $initial_payload = [] )`	إرسال تدفق العمل. يُرجع معرّفه.

`Queuety::workflow_status( $workflow_id )`

احصل على حالة تدفق العمل. يُرجع كائنًا WorkflowState أو null.

PHP

$state = Queuety::workflow_status( $workflow_id );
echo $state->name;          // 'generate_report'
echo $state->status->value; // 'running'
echo $state->current_step;  // 1
echo $state->total_steps;   // 3
print_r( $state->state );   // accumulated public state array
echo $state->wait_type;     // 'signal' or 'workflow' while blocked
echo $state->wait_mode;     // 'all', 'any', or 'quorum'
echo $state->definition_version; // 'research.v2'
echo $state->definition_hash;    // '4c7a...'
echo $state->idempotency_key;    // 'brief:42:research'
echo $state->artifact_count;     // 2
print_r( $state->budget );       // configured workflow budget + current usage
print_r( $state->wait_details ); // matched/remaining blockers, result key, correlation info
print_r( $state->artifact_keys ); // ['draft', 'citations']

يكشف WorkflowState أيضًا عن:

waiting_for: أسماء الإشارات أو معرّفات تدفقات العمل التي تعيق التشغيل حاليًا
current_step_name: الاسم المُعدّ للخطوة الحالية، إن وُجد
wait_mode: وضع الانتظار الحالي (all أو any أو quorum) أثناء التعليق
wait_details: بيانات فحص إضافية، مثل العوائق المطابقة والمتبقية
definition_version: القيمة التي عيّنها version()، إن وُجدت
definition_hash: تجزئة حتمية لتعريف تدفق العمل
idempotency_key: مفتاح الإرسال الدائم، إن وُجد
budget: الحدود المُعدّة والاستخدام الحالي، إذا كانت ضوابط الحماية مفعّلة
artifact_count: عدد العناصر الأثرية المخزّنة لتدفق العمل
artifact_keys: مفاتيح العناصر الأثرية المخزّنة لسرعة الفحص

`Queuety::retry_workflow( $workflow_id )`

أعِد محاولة تدفق عمل فاشل بدءًا من الخطوة التي أخفقت.

PHP

Queuety::retry_workflow( $workflow_id );

يرمي RuntimeException إذا كان قد تم تعويض تدفق العمل بالفعل بعد إخفاق.

`Queuety::pause_workflow( $workflow_id )`

أوقف تدفق عمل قيد التشغيل مؤقتًا. قد يكتمل العمل المُدرج مسبقًا للخطوة الحالية، لكن لن تُدرج خطوات لاحقة حتى تستأنف تدفق العمل.

PHP

Queuety::pause_workflow( $workflow_id );

`Queuety::resume_workflow( $workflow_id )`

استأنف تدفق عمل متوقفًا مؤقتًا.

PHP

Queuety::resume_workflow( $workflow_id );

`Queuety::cancel_workflow( $workflow_id )`

ألغِ تدفق عمل وشغّل أي معالجات تنظيف مسجلة. يعيّن الحالة إلى cancelled ويدفن جميع المهام المعلّقة وقيد المعالجة الخاصة بتدفق العمل.

PHP

Queuety::cancel_workflow( $workflow_id );

يرمي RuntimeException إذا كان تدفق العمل بالفعل completed أو cancelled. راجع الإلغاء للاطلاع على التفاصيل.

`Queuety::rewind_workflow( $workflow_id, $to_step )`

أعِد تدفق العمل إلى خطوة سابقة وأعِد تشغيله من هناك. تُستعاد الحالة من سجل الأحداث state_after للخطوة المحددة، وتُدرج الخطوة التالية في قائمة الانتظار.

PHP

Queuety::rewind_workflow( $workflow_id, to_step: 1 );

يرمي RuntimeException إذا لم توجد حالة مسجلة للخطوة المستهدفة. يتطلب سجل أحداث تدفق العمل. راجع السفر عبر الزمن للاطلاع على التفاصيل.

`Queuety::fork_workflow( $workflow_id )`

أنشئ نسخة مستقلة من تدفق عمل قيد التشغيل عند حالته الحالية. يُرجع معرّف تدفق العمل الجديد.

PHP

$forked_id = Queuety::fork_workflow( $workflow_id );

يحصل تدفق العمل المتفرّع على معرّف خاص به ويعمل بشكل مستقل عن التدفق الأصلي. راجع التفرّع للاطلاع على التفاصيل.

`Queuety::export_workflow( $workflow_id )`

صدّر سجل التنفيذ الكامل لتدفق العمل كمصفوفة قابلة للتسلسل بصيغة JSON. تتضمن سجل تدفق العمل وجميع المهام وأحداث تدفق العمل ومدخلات السجل.

PHP

$data = Queuety::export_workflow( $workflow_id );

راجع التصدير وإعادة التشغيل للاطلاع على بنية JSON وحالات الاستخدام.

`Queuety::replay_workflow( $data )`

أعِد تشغيل تدفق عمل مُصدّر في البيئة الحالية. ينشئ تدفق عمل جديدًا من بيانات التصدير ويُرجع معرّفه.

PHP

$new_id = Queuety::replay_workflow( $data );

راجع التصدير وإعادة التشغيل للاطلاع على التفاصيل.

`Queuety::replace_wp_cron()`

استبدل نظام WordPress cron المدمج بجدول المواعيد الخاص بـ Queuety. يعترض wp_schedule_event() وwp_unschedule_event() وwp_get_scheduled_event()، ويوجّه الأحداث المتكررة عبر العامل Queuety.

PHP

Queuety::replace_wp_cron();

لا يعمل إلا عند تحميل WordPress. راجع استبدال WP-Cron للاطلاع على التفاصيل.

`Queuety::restore_wp_cron()`

استعد السلوك الافتراضي لـ WordPress cron بإزالة خطّافات الجسر Queuety cron.

PHP

Queuety::restore_wp_cron();

راجع استبدال WP-Cron لمعرفة القيود.

`Queuety::signal( $workflow_id, $name, $data )`

أرسل إشارة إلى تدفق عمل. إذا كان تدفق العمل ينتظر هذه الإشارة حاليًا، فسيُستأنف فورًا. وإلا، تُخزّن الإشارة وتُلتقط عندما يصل تدفق العمل إلى خطوة wait_for_signal المقابلة.

PHP

Queuety::signal( $workflow_id, 'approved' );

// With data merged into workflow state
Queuety::signal( $workflow_id, 'approved', [
    'approved_by' => 'admin@example.com',
] );

راجع إشارات تدفق العمل للاطلاع على التفاصيل.

`Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )`

غلاف دلالي حول signal() لتدفقات الموافقة.

PHP

Queuety::approve_workflow( $workflow_id, [
    'reviewer' => 'editor@example.com',
] );

`Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )`

غلاف دلالي حول signal() لتدفقات الرفض.

PHP

Queuety::reject_workflow( $workflow_id, [
    'reason' => 'needs citations',
] );

`Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )`

غلاف دلالي حول signal() للإدخال البشري المنظّم.

PHP

Queuety::submit_workflow_input( $workflow_id, [
    'notes' => 'Ship after legal review',
] );

`Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )`

خزّن عنصرًا أثريًا دائمًا واحدًا لتدفق عمل.

PHP

Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    [ 'summary' => 'done' ],
    'json',
    metadata: [ 'source' => 'agent' ],
);

`Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )`

خزّن عنصرًا أثريًا واحدًا لخطوة تدفق العمل الجاري تنفيذها.

PHP

Queuety::put_current_artifact(
    'draft',
    [ 'status' => 'ready' ],
    'json',
);

`Queuety::workflow_artifact( $workflow_id, $artifact_key )`

اجلب عنصرًا أثريًا مخزّنًا واحدًا لتدفق عمل.

PHP

$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

`Queuety::workflow_artifacts( $workflow_id, $include_content = false )`

اعرض قائمة العناصر الأثرية لتدفق عمل.

PHP

$artifacts = Queuety::workflow_artifacts( $workflow_id );

`Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )`

احذف عنصرًا أثريًا واحدًا لتدفق عمل.

PHP

Queuety::delete_workflow_artifact( $workflow_id, 'draft' );

آلات الحالات

`Queuety::machine( $name )`

ابدأ إنشاء آلة حالات. يُرجع StateMachineBuilder.

PHP

use Queuety\Enums\StateMachineStatus;

$machine_id = Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

طرق `StateMachineBuilder`

الطريقة	الوصف
`initial( string $state_name )`	تعيين الحالة الأولية صراحةً.
`state( string $state_name, ?StateMachineStatus $terminal_status = null )`	بدء إعداد حالة واحدة.
`action( string\|array $action_class )`	تسجيل إجراء دخول إلى الحالة الحالية في قائمة الانتظار. مرّر اسم صنف أو تعريفًا منظّمًا يتضمن `class` و`payload` و`config`؛ وتصل `payload` إلى `StateAction::handle()` بصفتها `$payload`.
`on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )`	تسجيل انتقال واحد لحدث من الحالة الحالية. يقبل شرط الحراسة الصيغة المنظّمة نفسها التي يقبلها `action()`.
`on_queue( string $queue )`	تعيين قائمة الانتظار المستخدمة لإجراءات الحالة المؤجلة.
`with_priority( Priority $priority )`	تعيين أولوية إجراءات الحالة المؤجلة.
`max_attempts( int $max_attempts )`	تعيين حد إعادة المحاولة لإجراءات الحالة المؤجلة.
`version( string $version )`	إرفاق إصدار على مستوى التطبيق بتعريف الآلة.
`idempotency_key( string $key )`	جعل الإرسال دائمًا لمفتاح يقدمه المستدعي. يؤدي الإرسال مجددًا بالمفتاح نفسه إلى إرجاع معرّف الآلة الأصلي.
`dispatch( array $initial_state = [] )`	إرسال الآلة وإرجاع معرّفها.

يمكن لأصناف إجراءات دخول الحالة أيضًا توفير طريقة اختيارية config() بمفاتيح سياسة الموارد نفسها التي تدعمها خطوات سير العمل: concurrency_group وconcurrency_limit وcost_units.

`Queuety::dispatch_state_machine_definition( $definition, $initial_state = [], $options = [] )`

إرسال حزمة تعريف آلة حالات متسلسلة. ينبغي لمعظم تعليمات التطبيق البرمجية استخدام machine()->dispatch(). أُنشئت هذه الطريقة منخفضة المستوى كي تتمكن المحوّلات من بدء آلة دون الاعتماد مباشرةً على أداة الإنشاء.

PHP

$machine_id = Queuety::dispatch_state_machine_definition(
    $definition,
    [ 'thread_id' => 42 ],
    [ 'idempotency_key' => 'thread:42' ],
);

`Queuety::machine_status( $machine_id )`

الحصول على حالة الآلة الحالية. تُرجع كائن StateMachineState أو null.

PHP

$status = Queuety::machine_status( $machine_id );

echo $status->name;               // 'agent_session'
echo $status->status->value;      // 'waiting_event'
echo $status->current_state;      // 'awaiting_review'
print_r( $status->state );        // public machine state
print_r( $status->available_events ); // valid incoming events in the current state

توفّر StateMachineState أيضًا:

definition_version
definition_hash
idempotency_key
error_message
current_action
terminal_status

`Queuety::machine_event( $machine_id, $event_name, $payload = [] )`

إرسال حدث خارجي واحد إلى آلة في حالة انتظار.

PHP

Queuety::machine_event(
    $machine_id,
    'approve',
    [
        'approved' => true,
        'reviewer' => 'editor@example.com',
    ]
);

تكون الحمولة متاحة لشروط الانتقال، وتُدمج في حالة الآلة العامة عند قبول الحدث.

`Queuety::list_machines( $limit = 50, $status = null )`

عرض صفوف الآلات المحفوظة لفحصها.

PHP

$machines = Queuety::list_machines();
$waiting  = Queuety::list_machines( status: 'waiting_event' );

يتضمن كل صف معرّف الآلة واسمها وحالتها والحالة الراهنة وإصدار التعريف وبصمة التعريف ومفتاح منع التكرار والطوابع الزمنية لدورة الحياة.

`Queuety::machine_timeline( $machine_id, $limit = 100, $offset = 0 )`

الحصول على سجل الأحداث الدائم لآلة واحدة.

PHP

$timeline = Queuety::machine_timeline( $machine_id );
$page_two = Queuety::machine_timeline( $machine_id, 100, 100 );

يحتوي كل صف حدث على: id وmachine_id وjob_id وstate_name وhandler وevent وevent_name وtransition_name وqueue وattempt وinput وoutput وstate_before وstate_after وcontext وartifacts وchunks وerror وduration_ms وcreated_at.

`Queuety::machine_trace( $machine_id )`

الحصول على حزمة تتبّع موحّدة لمصحّح آلة الحالات UI.

PHP

$trace = Queuety::machine_trace( $machine_id );

يحتوي التتبّع على machine وstates مجمّعة وevents خام وjobs للإجراء المرتبط وlogs وartifacts وchunks.

`Queuety::machine_state_at( $machine_id, $event_id )`

الحصول على الحالة العامة بعد حدث تتبّع محدد للآلة، أو null إذا لم يُعثر عليه.

PHP

$state = Queuety::machine_state_at( $machine_id, $event_id );

راجع آلات الحالات للاطلاع على نموذج دورة الحياة وأنماط الاستخدام.

قوالب سير العمل

`Queuety::define_workflow( $name )`

إنشاء أداة إنشاء سير عمل لاستخدامها قالبًا.

PHP

$builder = Queuety::define_workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class );

`Queuety::register_workflow_template( $builder )`

تسجيل قالب سير عمل.

PHP

Queuety::register_workflow_template( $builder );

`Queuety::run_workflow( $name, $payload, $options = [] )`

إرسال قالب سير عمل مسجّل باسمه. يُرجع معرّف سير العمل.

PHP

$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );

$workflow_id = Queuety::run_workflow(
    'onboarding',
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

يُطلق RuntimeException إذا لم يكن القالب مسجّلًا.

`Queuety::dispatch_workflow_definition( $definition, $payload, $options = [] )`

إرسال سير عمل انطلاقًا من حزمة تعريف وقت التشغيل.

ينبغي لمعظم تعليمات التطبيق البرمجية استخدام run_workflow() أو workflow()->dispatch(). أُنشئت هذه الطريقة منخفضة المستوى كي تتمكن المحوّلات القابلة لإعادة الاستخدام من إرسال تعريف سير عمل متسلسل دون الاعتماد على الطرق الداخلية لمدير سير العمل.

PHP

$workflow_id = Queuety::dispatch_workflow_definition(
    $definition,
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

`Queuety::on_action( $hook, $workflow, $map = null, $when = null, $idempotency_key = null, $priority = 10, $accepted_args = null )`

تسجيل إجراء WordPress يرسل سير عمل.

PHP

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);

يمكن أن يكون $workflow أحد ما يلي:

اسم قالب سير عمل مسجّل
WorkflowBuilder مضمن

يعمل map وwhen وidempotency_key بشكل متزامن ضمن طلب WordPress الحالي. وحدها خطوات سير العمل نفسها تعمل بشكل غير متزامن بعد الإرسال.

راجع مشغّلات الإجراءات للاطلاع على الدليل الكامل.

`Queuety::workflow_templates()`

الحصول على سجل قوالب سير العمل.

PHP

$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null

`Queuety::load_workflows( $directory, $recursive )`

تحميل جميع ملفات سير العمل من دليل وتسجيلها. ينبغي لكل ملف .php إرجاع WorkflowBuilder. تُرجع الطريقة عدد مسارات العمل المسجّلة.

PHP

$count = Queuety::load_workflows( __DIR__ . '/workflows/' );
$count = Queuety::load_workflows( __DIR__ . '/workflows/', recursive: true );

`Queuety::load_workflow_file( $file_path )`

تحميل ملف سير عمل واحد وتسجيله. تُرجع WorkflowTemplate أو null إذا لم يُرجع الملف أداة إنشاء.

PHP

$template = Queuety::load_workflow_file( __DIR__ . '/workflows/onboard-user.php' );

الجدولة

`Queuety::schedule( $handler, $payload )`

إنشاء جدول متكرر. تُرجع أداة إنشاء PendingSchedule.

PHP

Queuety::schedule( 'cleanup_handler' )
    ->every( '1 hour' )
    ->on_queue( 'maintenance' );

Queuety::schedule( 'nightly_report' )
    ->cron( '0 3 * * *' )
    ->on_queue( 'reports' );

طرق `PendingSchedule`

الطريقة	الوصف
`every( string $interval )`	تعيين تعبير فترة زمنية (e.g، `1 hour`، `30 minutes`)
`cron( string $expression )`	تعيين تعبير cron من 5 حقول
`overlap( OverlapPolicy $policy )`	تعيين سياسة التداخل (الافتراضي: `Allow`). راجع الجدولة.
`on_queue( string $queue )`	تعيين قائمة الانتظار المستهدفة (الافتراضي: `default`)
`id()`	فرض الإرسال وإرجاع معرّف الجدول

`Queuety::scheduler()`

الحصول على مثيل Scheduler الداخلي.

PHP

$scheduler = Queuety::scheduler();
$schedules = $scheduler->list();
$scheduler->remove( 'handler_name' );
$count = $scheduler->tick(); // manually trigger

تسجيل المعالجات

`Queuety::register( $name, $class )`

تسجيل صنف معالج باسم.

PHP

Queuety::register( 'send_email', SendEmailHandler::class );

`Queuety::discover_handlers( $directory, $namespace )`

اكتشاف أصناف المعالجات في دليل وتسجيلها تلقائيًا. تُرجع الطريقة عدد المعالجات المسجّلة.

PHP

$count = Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );

`Queuety::registry()`

الحصول على سجل المعالجات.

PHP

$registry = Queuety::registry();

قابلية المراقبة

`Queuety::logger()`

الحصول على مثيل Logger للاستعلام عن إدخالات السجل.

PHP

$logger = Queuety::logger();
$logs   = $logger->for_job( 42 );
$logs   = $logger->for_workflow( 7 );
$logs   = $logger->for_handler( 'send_email', 50 );
$logs   = $logger->for_event( LogEvent::Failed, 50 );
$logs   = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
$count  = $logger->purge( 30 );

`Queuety::metrics()`

الحصول على مثيل Metrics.

PHP

$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes

`Queuety::webhook_notifier()`

الحصول على مثيل WebhookNotifier.

PHP

$notifier = Queuety::webhook_notifier();
$id       = $notifier->register( 'job.buried', 'https://hooks.slack.com/...' );
$webhooks = $notifier->list();
$notifier->remove( $id );

`Queuety::rate_limiter()`

الحصول على مثيل RateLimiter.

PHP

$limiter = Queuety::rate_limiter();
$limiter->register( 'call_openai', 60, 60 );

التخزين المؤقت

`Queuety::cache()`

الحصول على مثيل خلفية التخزين المؤقت النشطة.

PHP

$cache = Queuety::cache();
$cache->set( 'my_key', 'my_value', 60 );
$value = $cache->get( 'my_key' );

`Queuety::set_cache( $cache )`

تجاوز خلفية التخزين المؤقت. استدعِ هذه الطريقة قبل Queuety::init() لاستخدام تنفيذ مخصص.

PHP

Queuety::set_cache( new RedisCache() );
Queuety::init( $connection );

`QUEUETY_CACHE_TTL`

مدة البقاء الافتراضية للتخزين المؤقت بالثواني (الافتراضي: 5). عيّن هذا الثابت في wp-config.php لتغيير مدة البقاء الافتراضية التي تستخدمها عمليات التخزين المؤقت الداخلية.

PHP

define( 'QUEUETY_CACHE_TTL', 10 );

راجع التخزين المؤقت لمعرفة التفاصيل حول الخلفيات والاكتشاف التلقائي.

سجل أحداث آلة الحالات

`Queuety::machine_events()`

الحصول على مثيل StateMachineEventLog.

PHP

$log = Queuety::machine_events();

سجل أحداث سير العمل

`Queuety::workflow_events()`

الحصول على مثيل WorkflowEventLog.

PHP

$log = Queuety::workflow_events();

`Queuety::workflow_timeline( $workflow_id, $limit = 100, $offset = 0 )`

الحصول على التسلسل الزمني الكامل لأحداث سير العمل. تُرجع الطريقة مصفوفة من صفوف الأحداث مرتبة حسب المعرّف.

PHP

$events = Queuety::workflow_timeline( $workflow_id );
$next   = Queuety::workflow_timeline( $workflow_id, 100, 100 );

يحتوي كل صف حدث على: id وworkflow_id وjob_id وparent_event_id وstep_index وstep_name وstep_type وhandler وevent وqueue وattempt وinput وoutput وstate_before وstate_after وcontext وartifacts وchunks وerror وerror_message (منسوخ من error.message) وduration_ms وcreated_at.

`Queuety::workflow_trace( $workflow_id )`

الحصول على حزمة تتبّع موحّدة لمصحّح سير العمل UI.

PHP

$trace = Queuety::workflow_trace( $workflow_id );

يحتوي التتبّع على workflow وsteps مجمّعة وevents خام وjobs وlogs وartifacts وchunks وsignals وwait_dependencies.

`Queuety::trace_input( $input )`

تعيين مدخل على مستوى التطبيق لخطوة سير العمل الجاري تنفيذها.

`Queuety::trace_output( $output )`

تعيين مخرج على مستوى التطبيق لخطوة سير العمل الجاري تنفيذها.

`Queuety::trace_context( array $context )`

دمج سياق على مستوى التطبيق في خطوة سير العمل الجاري تنفيذها.

`Queuety::workflow_state_at( $workflow_id, $step_index )`

الحصول على الحالة العامة بعد إكمال خطوة محددة من سير العمل أو استئنافها، أو null إذا لم يُعثر عليها.

PHP

$state = Queuety::workflow_state_at( $workflow_id, 2 );

راجع سجل أحداث سير العمل للاطلاع على حالات الاستخدام وأوامر CLI.

المثيلات الداخلية

تُرجع هذه الطرق مثيلات داخلية لحالات الاستخدام المتقدمة.

الطريقة	تُرجع	الوصف
`Queuety::queue()`	`Queue`	عمليات قائمة الانتظار (المطالبة، والتحرير، والدفن)
`Queuety::worker()`	`Worker`	التحكم في عملية العامل
`Queuety::workflow_manager()`	`Workflow`	تنسيق سير العمل
`Queuety::machines()`	`StateMachine`	إدارة دورة حياة آلة الحالات
`Queuety::connection()`	`Connection`	اتصال قاعدة البيانات
`Queuety::batch_manager()`	`BatchManager`	إدارة دورة حياة الدفعات (الإلغاء، والتقليم)
`Queuety::chunk_store()`	`ChunkStore`	حفظ الأجزاء لخطوات البث
`Queuety::machine_events()`	`StateMachineEventLog`	أحداث تتبّع آلة الحالات وحزم التتبّع الموحّدة
`Queuety::workflow_events()`	`WorkflowEventLog`	أحداث تتبّع سير العمل وحزم التتبّع الموحّدة
`Queuety::resource_manager()`	`ResourceManager`	ملفات قبول العامل، والميزانيات الموزونة، وفحص ذاكرة النظام
`Queuety::cache()`	`Cache`	مثيل خلفية التخزين المؤقت

الاختبار

`Queuety::fake()`

استبدال قائمة الانتظار بمحاكاة زائفة داخل الذاكرة للاختبار. تُرجع الطريقة مثيل QueueFake يسجّل المهام المرسلة دون الاتصال بقاعدة البيانات. يسجّل create_batch() أيضًا بيانات وصفية زائفة للدفعات؛ ويُتحقق من السلاسل عبر المهام الفردية التي ترسلها.

PHP

$fake = Queuety::fake();
SendEmailJob::dispatch( 'user@example.com', 'Hello', 'Hi!' );
$fake->assert_pushed( SendEmailJob::class );

`Queuety::reset()`

إعادة ضبط كل الحالة الداخلية، بما فيها محاكاة قائمة الانتظار الزائفة. استدعِها في tearDown().

PHP

Queuety::reset();

طرق `QueueFake`

الطريقة	الوصف
`assert_pushed( string $class, ?Closure $callback )`	التحقق من إرسال صنف مهمة. يرشّح ردّ النداء الاختياري بيانات المهمة.
`assert_pushed_times( string $class, int $count )`	التحقق من إرسال المهمة N مرة بالضبط.
`assert_not_pushed( string $class )`	التحقق من عدم إرسال أي مهمة.
`assert_nothing_pushed()`	التحقق من عدم إرسال أي مهام على الإطلاق.
`assert_batched( ?Closure $callback )`	التحقق من إرسال دفعة. يرشّح ردّ النداء الاختياري بيانات الدفعة.
`pushed( string $class )`	الحصول على كل عمليات الإرسال المسجّلة لصنف. تُرجع مصفوفة.
`batches()`	الحصول على كل الدفعات المسجّلة. تُرجع مصفوفة.
`reset()`	مسح كل المهام والدفعات المسجّلة.

راجع الاختبار للاطلاع على أمثلة كاملة.

الواجهات

`Handler`

واجهة لمعالجات المهام البسيطة.

PHP

interface Handler {
    public function handle( array $payload ): void;
    public function config(): array;
}

يمكن أن تُرجع config() أيًا من queue وmax_attempts وbackoff وrate_limit وconcurrency_group وconcurrency_limit وcost_units.

`Step`

واجهة لمعالجات خطوات سير العمل.

PHP

interface Step {
    public function handle( array $state ): array;
    public function config(): array;
}

يمكن أن تُرجع config() أيًا من max_attempts وbackoff وconcurrency_group وconcurrency_limit وcost_units.

`Contracts\ForEachHandler`

واجهة لمعالجات فروع التكرار الديناميكية.

PHP

namespace Queuety\Contracts;

interface ForEachHandler {
    public function handle_item( array $state, mixed $item, int $index ): array;
    public function config(): array;
}

يمكن أن تُرجع config() أيًا من max_attempts وbackoff وrate_limit وconcurrency_group وconcurrency_limit وcost_units.

`Contracts\ForEachReducer`

مُخفِّض اختياري لنتائج التكرار.

PHP

namespace Queuety\Contracts;

interface ForEachReducer {
    public function reduce( array $state, array $for_each ): array;
}

`Contracts\Compensation`

واجهة لمعالجات التعويض عن الخطوات.

PHP

namespace Queuety\Contracts;

interface Compensation {
    public function handle( array $state ): void;
}

`Contracts\RepeatCondition`

واجهة لشروط الحلقات المستخدمة بواسطة repeat_until() وrepeat_while() عندما تكون مقارنة مفاتيح الحالة محدودة أكثر من اللازم.

PHP

namespace Queuety\Contracts;

interface RepeatCondition {
    public function matches( array $state ): bool;
}

`Contracts\StateAction`

واجهة لإجراءات دخول الحالة الموضوعة في قائمة الانتظار.

PHP

namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}

يتلقى $payload قيمة payload المنظّمة من تعريف الإجراء، إذا كانت الآلة معرّفة بها. أرجِع تحديثات الحالة العامة. أدرج _event و_event_payload اختياريًا عندما ينبغي للإجراء تنفيذ انتقال فوري.

يمكن لإجراءات الحالة أيضًا تعريف طريقة اختيارية config(). يقرأ Queuety منها concurrency_group وconcurrency_limit وcost_units عند وضع إجراء الدخول في قائمة الانتظار.

`Contracts\StateGuard`

واجهة لشروط الحراسة الخاصة بانتقالات آلة الحالات.

PHP

namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}

`Contracts\Job`

واجهة لأصناف المهام القابلة للإرسال المستقلة. تخزّن أصناف المهام حمولتها كخصائص عامة ومنطق التنفيذ في handle().

PHP

namespace Queuety\Contracts;

interface Job {
    public function handle(): void;
}

يمكن لأصناف المهام اختياريًا تعريف طريقة middleware() تُرجع مصفوفة من مثيلات Contracts\Middleware.

`Contracts\Cache`

واجهة لخلفيات التخزين المؤقت. راجع التخزين المؤقت للاطلاع على عمليات التنفيذ المضمّنة والخلفيات المخصصة.

PHP

namespace Queuety\Contracts;

interface Cache {
    public function get( string $key ): mixed;
    public function set( string $key, mixed $value, int $ttl = 0 ): void;
    public function delete( string $key ): void;
    public function has( string $key ): bool;
    public function add( string $key, mixed $value, int $ttl = 0 ): bool;
    public function flush(): void;
}

الطريقة	تُرجع	الوصف
`get( $key )`	`mixed`	استرجاع قيمة. تُرجع `null` إذا لم يُعثر عليها أو انتهت صلاحيتها.
`set( $key, $value, $ttl )`	`void`	تخزين قيمة. تعني مدة بقاء قدرها 0 عدم انتهاء الصلاحية.
`delete( $key )`	`void`	إزالة قيمة.
`has( $key )`	`bool`	التحقق من وجود مفتاح وعدم انتهاء صلاحيته.
`add( $key, $value, $ttl )`	`bool`	تعيين ذري إذا لم يكن المفتاح موجودًا. تُرجع `true` إذا عُيّنت القيمة.
`flush()`	`void`	إزالة جميع العناصر من التخزين المؤقت.

`WorkflowEventLog`

يسجّل انتقالات خطوات سير العمل مع سياق التتبّع الكامل. يُتاح عبر Queuety::workflow_events().

الطريقة	تُرجع	الوصف
`record_event( array $event )`	`void`	تسجيل حدث تتبّع خام
`record_step_started( ... )`	`void`	تسجيل حدث step_started مع المدخل والحالة قبل التنفيذ
`record_step_completed( ... )`	`void`	تسجيل حدث step_completed مع المدخل والمخرج والحالة قبل التنفيذ وبعده
`record_step_failed( ... )`	`void`	تسجيل حدث step_failed مع سياق التتبّع وتفاصيل الخطأ المنظّمة
`get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )`	`array`	الحصول على أحداث تتبّع سير العمل بالترتيب، مع إمكانية تقسيم النتائج إلى صفحات
`get_trace( int $workflow_id )`	`array`	الحصول على حزمة تتبّع موحّدة
`get_state_at_step( int $workflow_id, int $step_index )`	`array\|null`	الحصول على الحالة العامة بعد إكمال خطوة محددة أو استئنافها
`prune( int $older_than_days )`	`int`	حذف الأحداث الأقدم من عدد الأيام المحدد. تُرجع عدد الصفوف المحذوفة.

`StateMachineEventLog`

يسجّل دورة حياة آلة الحالات وإجراءاتها وانتقالاتها وأحداث شروط الحراسة، باستخدام حقول التتبّع نفسها لأحداث سير العمل.

الطريقة	تُرجع	الوصف
`record_event( array $event )`	`void`	تسجيل حدث تتبّع خام للآلة
`get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )`	`array`	الحصول على أحداث تتبّع الآلة بالترتيب، مع إمكانية تقسيم النتائج إلى صفحات
`get_trace( int $machine_id )`	`array`	الحصول على حزمة تتبّع موحّدة للآلة
`get_state_at_event( int $machine_id, int $event_id )`	`array\|null`	الحصول على الحالة العامة بعد حدث تتبّع محدد للآلة
`prune( int $older_than_days )`	`int`	حذف الأحداث الأقدم من عدد الأيام المحدد. تُرجع عدد الصفوف المحذوفة.

`Contracts\StreamingStep`

واجهة لمعالجات خطوات سير العمل التي تنتج تدفقًا من الأجزاء. يُحفظ كل عنصر مولّد في قاعدة البيانات فورًا. راجع خطوات البث.

PHP

namespace Queuety\Contracts;

interface StreamingStep {
    public function stream( array $state, array $existing_chunks = [] ): \Generator;
    public function on_complete( array $chunks, array $state ): array;
    public function config(): array;
}

الطريقة	الوصف
`stream( $state, $existing_chunks )`	مولّد ينتج أجزاء نصية. يؤدي كل إنتاج إلى كتابة فورية في قاعدة البيانات. عند إعادة المحاولة، يحتوي `$existing_chunks` على الأجزاء المحفوظة سابقًا.
`on_complete( $chunks, $state )`	يُستدعى بعد انتهاء التدفق. يُرجع بيانات لدمجها في حالة سير العمل.
`config()`	إعداد اختياري. يدعم `max_attempts` و`backoff` و`concurrency_group` و`concurrency_limit` و`cost_units`.

`ChunkStore`

يدير حفظ الأجزاء لخطوات البث. يُتاح عبر Queuety::chunk_store().

الطريقة	تُرجع	الوصف
`get_chunks( int $job_id )`	`string[]`	جلب كل أجزاء مهمة بترتيب فهرس الجزء
`append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )`	`void`	إلحاق جزء واحد
`clear_chunks( int $job_id )`	`void`	حذف كل أجزاء مهمة
`chunk_count( int $job_id )`	`int`	عدّ أجزاء مهمة
`get_accumulated( int $job_id )`	`string`	ضم كل الأجزاء في سلسلة نصية واحدة

`Heartbeat`

مساعد ثابت لإرسال نبضات النشاط من داخل معالجات الخطوات وخطوات البث. راجع نبضات النشاط.

الطريقة	الوصف
`Heartbeat::init( int $job_id, Connection $conn )`	تعيين سياق المهمة. يستدعيها العامل تلقائيًا.
`Heartbeat::beat( array $progress = [] )`	إرسال نبضة نشاط. تحدّث `reserved_at` وتخزّن بيانات التقدّم اختياريًا في `heartbeat_data`.
`Heartbeat::clear()`	مسح سياق المهمة. يستدعيها العامل تلقائيًا.
`Heartbeat::current_job_id()`	الحصول على معرّف المهمة الحالي (للاختبار).

`Contracts\Middleware`

واجهة للبرمجيات الوسيطة الخاصة بالمهام. تحيط البرمجيات الوسيطة بتنفيذ المهمة ضمن مسار يشبه طبقات البصلة.

PHP

namespace Queuety\Contracts;

interface Middleware {
    public function handle( object $job, \Closure $next ): void;
}

السمات

`Dispatchable`

توفّر طرق إرسال ثابتة لأصناف المهام التي تنفّذ Contracts\Job. وتُمرّر وسيطات المُنشئ لإنشاء مثيل المهمة.

PHP

use Queuety\Contracts\Job;
use Queuety\Dispatchable;

class SendEmailJob implements Job {
    use Dispatchable;
    // ...
}

// Dispatches a new SendEmailJob instance
SendEmailJob::dispatch( 'user@example.com', 'Subject', 'Body' );

الطريقة	تُرجع	الوصف
`dispatch( ...$args )`	`PendingJob`	إنشاء مثيل وإرساله
`dispatch_if( bool $condition, ...$args )`	`PendingJob\|null`	الإرسال فقط إذا كانت `$condition` صحيحة
`dispatch_unless( bool $condition, ...$args )`	`PendingJob\|null`	الإرسال فقط إذا كانت `$condition` خاطئة
`with_chain( array $jobs )`	`ChainBuilder`	بدء سلسلة من صنف المهمة هذا

PHP

// Conditional dispatch
SendEmailJob::dispatch_if( $user->wants_email, $user->email, 'Hello', 'Hi!' );
SendEmailJob::dispatch_unless( $maintenance_mode, $user->email, 'Hello', 'Hi!' );

// Chain from a job class
FetchDataJob::with_chain( [
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )->dispatch();

خصائص المهمة

يمكن لأصناف المهام تعريف خصائص عامة يقرأها العامل عبر الاستبطان لتجاوز سلوك إعادة المحاولة والمهلة الزمنية.

الخاصية	النوع	الوصف
`$tries`	`int`	الحد الأقصى للمحاولات قبل دفن المهمة
`$timeout`	`int`	الحد الأقصى لوقت التنفيذ بالثواني (يتطلب `pcntl`)
`$backoff`	`array`	قيم التأخير المتزايدة بالثواني لكل محاولة إعادة

PHP

class ImportProductsJob implements Job {
    use Dispatchable;

    public int $tries = 5;
    public int $timeout = 120;
    public array $backoff = [ 10, 30, 60, 120 ];

    // ...
}

خطاف `failed()`

عندما تُدفن مهمة بعد استنفاد جميع محاولات الإعادة، يستدعي العامل طريقة failed() على مثيل المهمة إذا كانت معرّفة.

PHP

public function failed( \Throwable $exception ): void {
    error_log( "Job failed: {$exception->getMessage()}" );
}

البرمجيات الوسيطة المضمّنة

تنفّذ جميع أصناف البرمجيات الوسيطة Contracts\Middleware، وتقع ضمن مساحة الأسماء Queuety\Middleware.

الفئة	الوصف
`RateLimited( int $max, int $window )`	فرض حد لمعدل `$max` عملية تنفيذ لكل `$window` ثانية
`Timeout( int $seconds )`	إنهاء المهمة بعد `$seconds` ثانية (يتطلب `pcntl`)
`UniqueJob( ?string $key )`	منع التنفيذ المتزامن باستخدام قفل قاعدة بيانات
`WithoutOverlapping( string $key, int $release_after )`	منع تداخل عمليات التنفيذ مع انتهاء صلاحية القفل تلقائيًا
`ThrottlesExceptions( int $max_attempts, int $decay_minutes )`	الحد من الاستثناءات لمنع تدفق المهام عند تعطل خدمة خارجية

اطّلع على Middleware لمعرفة تفاصيل الاستخدام والأمثلة.

التعدادات

`Priority`

PHP

enum Priority: int {
    case Low    = 0;
    case Normal = 1;
    case High   = 2;
    case Urgent = 3;
}

`JobStatus`

PHP

enum JobStatus: string {
    case Pending    = 'pending';
    case Processing = 'processing';
    case Completed  = 'completed';
    case Failed     = 'failed';
    case Buried     = 'buried';
}

`WorkflowStatus`

PHP

enum WorkflowStatus: string {
    case Running        = 'running';
    case Completed      = 'completed';
    case Failed         = 'failed';
    case Paused         = 'paused';
    case WaitingForSignal  = 'waiting_for_signal';
    case WaitingForWorkflows = 'waiting_for_workflows';
    case Cancelled      = 'cancelled';
}

`StateMachineStatus`

PHP

enum StateMachineStatus: string {
    case Running = 'running';
    case WaitingEvent = 'waiting_event';
    case Completed = 'completed';
    case Failed = 'failed';
    case Paused = 'paused';
    case Cancelled = 'cancelled';
}

`BackoffStrategy`

PHP

enum BackoffStrategy: string {
    case Fixed       = 'fixed';
    case Linear      = 'linear';
    case Exponential = 'exponential';
}

`ForEachMode`

PHP

enum ForEachMode: string {
    case All = 'all';
    case FirstSuccess = 'first_success';
    case Quorum = 'quorum';
}

`WaitMode`

PHP

enum WaitMode: string {
    case All    = 'all';
    case Any    = 'any';
    case Quorum = 'quorum';
}

`LogEvent`

PHP

enum LogEvent: string {
    case Started                  = 'started';
    case Completed                = 'completed';
    case Failed                   = 'failed';
    case Buried                   = 'buried';
    case Retried                  = 'retried';
    case WorkflowStarted          = 'workflow_started';
    case WorkflowCompleted        = 'workflow_completed';
    case WorkflowFailed           = 'workflow_failed';
    case WorkflowPaused           = 'workflow_paused';
    case WorkflowResumed          = 'workflow_resumed';
    case WorkflowCancelled        = 'workflow_cancelled';
    case WorkflowRewound          = 'workflow_rewound';
    case WorkflowForked           = 'workflow_forked';
    case WorkflowDeadlineExceeded = 'workflow_deadline_exceeded';
    case Debug                    = 'debug';
}

`OverlapPolicy`

PHP

enum OverlapPolicy: string {
    case Allow  = 'allow';
    case Skip   = 'skip';
    case Buffer = 'buffer';
}

اطّلع على Scheduling لمعرفة تفاصيل آلية عمل كل سياسة.

السمات

`#[QueuetyHandler]`

سمة PHP 8 للتسجيل التلقائي. راجع PHP Attributes.

PHP

use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    // ...
}

جسر CLI

`Queuety::cli_command()`

يعيد اسم الأمر الجذر المنشور لـ WP-CLI.

الأمر الجذر الافتراضي هو queuety. عرّف QUEUETY_CLI_COMMAND قبل بدء Queuety إذا أردت نشر الأمر تحت اسم مختلف.

`Queuety::cli_command_map()`

يعيد فهرسًا متسلسلًا من Queuety CLI للأدوات التي تحتاج إلى معرفة سطح الأوامر المتاح دون فحص أصناف WP-CLI.

يتضمن كل إدخال:

معرّف عملية ثابتًا
مسار CLI نسبيًا
صنف المعالج وطريقته في WP-CLI
أهداف التنفيذ المحتملة
المهايئ الذي يطبّع وسائط CLI الخام إلى خطة تنفيذ

`Queuety::resolve_cli_command( $path, $args, $assoc_args )`

يحوّل استدعاء CLI محللًا إلى خطة التنفيذ التي ينبغي للأداة تشغيلها.

PHP

$plan = Queuety::resolve_cli_command(
    [ 'workflow', 'export' ],
    [ '42' ],
    [ 'output' => '/tmp/workflow.json' ]
);

echo $plan['callable']; // Queuety\Queuety::export_workflow_to_file
print_r( $plan['arguments'] );

تراعي خطط التنفيذ وسيلة النقل عمدًا:

تُحل الأوامر إلى دوال استدعاء عامة في PHP مع وسائط مطبّعة
يسرد الفهرس كل أهداف التنفيذ المحتملة مسبقًا، بينما يحدد callable وtransport الفرع المختار للمدخل المحلل

هذا هو التنسيق المعتاد الذي تستخدمه Queuety لأدوات الوكلاء: معرّف عملية ثابت، وهدف API عام، وتطبيع يتولاه المهايئ للمسائل الخاصة بـ CLI فقط، مثل القيم الافتراضية لقوائم الانتظار، وفك ترميز حمولة JSON، والتفرع إلى مجموعة العمليات العاملة، والتعامل مع ملفات تصدير سير العمل.

PHP API

الوصول المستقل إلى النواة

Queuety::init( Connection $conn )

Queuety::ensure_schema()

المهام

Queuety::dispatch( $handler, $payload )

طرق PendingJob

Queuety::dispatch_sync( $handler, $payload )

Queuety::batch( $jobs )

Queuety::create_batch( $jobs )

طرق BatchBuilder

Queuety::find_batch( $id )

التحكم بالعاملين

Queuety::run_worker( $queue = 'default', $once = false )

Queuety::run_worker_pool( $workers, $queue = 'default' )

Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )

كائن القيمة Batch

Queuety::chain( $jobs )

طرق ChainBuilder

Queuety::retry( $job_id )

Queuety::retry_buried()

Queuety::purge( $older_than_days )

قوائم الانتظار

Queuety::stats( $queue )

Queuety::buried( $queue )

Queuety::pause( $queue )

Queuety::resume( $queue )

Queuety::is_paused( $queue )

تدفقات العمل

Queuety::workflow( $name )

طرق WorkflowBuilder

Queuety::workflow_status( $workflow_id )

Queuety::retry_workflow( $workflow_id )

Queuety::pause_workflow( $workflow_id )

Queuety::resume_workflow( $workflow_id )

Queuety::cancel_workflow( $workflow_id )

Queuety::rewind_workflow( $workflow_id, $to_step )

Queuety::fork_workflow( $workflow_id )

Queuety::export_workflow( $workflow_id )

Queuety::replay_workflow( $data )

Queuety::replace_wp_cron()

Queuety::restore_wp_cron()

Queuety::signal( $workflow_id, $name, $data )

Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )

Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )

Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )

Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )

Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )

Queuety::workflow_artifact( $workflow_id, $artifact_key )

Queuety::workflow_artifacts( $workflow_id, $include_content = false )

Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )