مقدمة

Queuety إضافة WordPress توفر صف انتظار سريعًا للمهام ومحرك سير عمل دائمًا ووقت تشغيل دائمًا لآلة الحالات. يطالب العمال بالمهام مباشرة من MySQL ويعالجونها ضمن عملية WP-CLI طويلة التشغيل. يحتاج وقت التشغيل PHP الذي يحمّل WordPress وWP-CLI إلى mysqli أو pdo_mysql.

لماذا Queuety؟

لا يوفّر WordPress نظامًا حقيقيًا للمهام في الخلفية. ولا يعمل wp_cron إلا عند زيارة الصفحات. يعتمد المشغّل الافتراضي لـ Action Scheduler على WP-Cron وطلبات رجوع إلى الموقع HTTP، ويعالج كل منها دفعات لمدة لا تتجاوز 30 ثانية. يستغرق استدعاء API لـ LLM مدة 60 ثانية، فتُنهيه مهلة PHP البالغة 30 ثانية. ولا توجد طريقة لتشغيل عمليات متعددة الخطوات تصمد أمام الأعطال وتستأنف من حيث توقفت.

يعالج Queuety هذه المشكلة باستخدام ثلاث وحدات أساسية:

1. المهام لأعمال الخلفية التي تُرسل دون انتظار نتيجة
2. سير العمل للعمليات متعددة الخطوات ذات الحالة الدائمة
3. آلات الحالات لحالات دورة الحياة طويلة الأمد والمبنية على الأحداث

مثال سريع

أرسل مهمة باستخدام API الحديث:

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

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

أو استخدم النهج الكلاسيكي القائم على اسم المعالج:

use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

شغّل سير عمل دائمًا:

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

مثّل جلسة طويلة الأمد باستخدام آلة حالات:

use Queuety\Enums\StateMachineStatus;

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 ] );

ابدأ عاملًا:

wp queuety work

إذا كنت تبني نظامًا بأسلوب الوكلاء، فابدأ بـ Agent Orchestration. يوضح كيف تتكامل تدفقات المخطّط والمنفّذ وبوابات المراجعة البشرية وحالات الانتظار بين مسارات سير العمل.

إذا كان النظام طويل الأمد ومبنيًا على الأحداث، فابدأ بـ State Machines إلى جانب سير العمل.

للاطلاع على أمثلة تكامل شاملة، راجع Examples، التي تتضمن الآن أنماطًا قائمة على Neuron لتبديل المزوّد والبث والذاكرة التي تعيد دورات المراجعة وسير العمل التابع.

إذا أردت بدء سير العمل انطلاقًا من أحداث المجال في WordPress مثل save_post، فراجع Action Triggers.

إذا أردت استخدام وقت التشغيل المدعوم بقاعدة بيانات خارج WordPress، فراجع Standalone Use.

أبرز المزايا

• تنفيذ سريع. يستخدم العمال وصولًا مباشرًا إلى صفوف MySQL ويتجنبون نمط cron لكل طلب، الذي يبطئ أعمال الخلفية في WordPress.
• سير عمل دائم. عمليات متعددة الخطوات ذات حالة دائمة تصمد أمام مهل PHP والأعطال وإعادات المحاولة. وحدّ كل خطوة هو معاملة MySQL ذرية.
• آلات حالات صريحة. مثّل جلسات المحادثة والموافقات ودورات الحياة طويلة الأمد الأخرى بحالات مسماة وانتقالات محكومة وإجراءات مجدولة عند دخول الحالة وخطوط زمنية دائمة للأحداث.
• واجهة إرسال حديثة API. فئات مهام مستقلة بذاتها تستخدم السمة Dispatchable، وخصائص منشئ مكتوبة النوع لتكون الحمولة، و$tries/$timeout/$backoff المعرّفة في الفئة. لا يمكن لفئة readonly تعيين قيم افتراضية لهذه الخصائص، لذا عرّفها في فئة عادية باستخدام خصائص منشئ مُرقّاة للقراءة فقط.
• مسار معالجة وسيط. وسائط بأسلوب الطبقات المتداخلة لتحديد معدل الطلبات وخنق الاستثناءات والمهام الفريدة والمنطق المخصص. تُعرّف لكل مهمة عبر الطريقة middleware().
• خطوات البث. تُخرج الواجهة StreamingStep أجزاءً تُحفظ فورًا في قاعدة البيانات. عند إعادة المحاولة، تُمرّر الأجزاء المحفوظة سابقًا لاستئناف البث من موضع التوقف. مثالية لاستجابات LLM والتنزيلات الكبيرة.
• طبقة تخزين مؤقت قابلة للتبديل. يكتشف CacheFactory تلقائيًا APCu أو يعود إلى ذاكرة مؤقتة داخل الذاكرة. تنفّذ الواجهات الخلفية المخصصة Contracts\Cache. تُستخدم داخليًا لعمليات البحث الخاصة بمحدد معدل الطلبات وحالة صف الانتظار.
• التجميع والتسلسل. أرسل مجموعات من المهام مع دوال رد الاتصال then/catch/finally وتتبع التقدم، أو اربط المهام بالتتابع بحيث تعتمد كل منها على اكتمال سابقتها.
• تأخيرات وانتظارات دائمة. يضيف delay() تأخيرات آمنة عند إعادة تشغيل العملية. تتيح wait_for_signal() وwait_for_signals() وwait_for_approval() وwait_for_input() وwait_for_workflow() لسير العمل التوقف انتظارًا لأحداث خارجية أو لعمليات سير عمل أخرى دون إبقاء PHP قيد التشغيل.
• تكرار ديناميكي لكل عنصر. يوسّع for_each() أعمال الفروع المكتشفة أثناء التشغيل انطلاقًا من حالة سير العمل، ويدعم أوضاع الإكمال: نجاح الجميع، أو أول نجاح، أو النصاب.
• تسليم غير متزامن بين مسارات سير العمل. يحوّل start_workflows() العناصر المكتشفة أثناء التشغيل إلى مسارات سير عمل مستقلة من المستوى الأعلى يمكن انتظارها لاحقًا.
• مشغّلات إجراءات WordPress. يربط on_action() خطافات إجراءات النظام الأساسي أو الإضافات بإرسال سير عمل دائم، مع شروط تحكم ومنع للتكرار.
• عناصر دائمة. خزّن مخرجات سير العمل المسماة خارج حزمة الحالة الرئيسية، وأدرجها في فحص الحالة CLI وتصديرها وإعادة تشغيلها.
• ضوابط سير العمل. يسهّل version() وبصمة تعريف حتمية ومفاتيح إرسال تمنع التكرار وميزانيات سير العمل فحص عمليات التشغيل بأسلوب الوكلاء، ويصعّب تكرارها أو استمرارها بلا حدود بصمت.
• إدارة الموارد. تساعد مجموعات التزامن ووحدات التكلفة وميزانيات سير العمل وقبول العامل للمهام على إبقاء العمل المكلف بأسلوب الوكلاء ضمن حدود محددة.
• التعويض عن الخطوات. يوفر compensate_with() وcompensate_on_failure() خطافات للتراجع عن الخطوات المكتملة عند إلغاء سير العمل أو فشله.
• نبضات الحياة. ترسل الخطوات طويلة التشغيل نبضات حياة لمنع نظام استعادة المهام القديمة من استعادة عمل نشط.
• تتبّع سير العمل. يُسجّل كل انتقال بين الخطوات مع المدخلات والمخرجات والحالة قبل التغيير وبعده والسياق والعناصر والأجزاء والأخطاء، مع تصحيح أخطاء عبر الزمن بواسطة workflow_state_at().
• خطوات متوازية. شغّل الخطوات بالتزامن وانتظر اكتمالها جميعًا قبل المتابعة.
• التفرع الشرطي. انتقل إلى خطوات مسماة بناءً على الحالة السابقة باستخدام _next_step.
• تشغيل سير العمل. ابدأ مسارات سير عمل فرعية تعيد نتائجها إلى المسار الأصل.
• صفوف انتظار حسب الأولوية. أربعة مستويات (منخفض، عادي، مرتفع، عاجل) عبر تعدادات PHP الآمنة من حيث الأنواع.
• عمال لصفوف انتظار متعددة. عالج عدة صفوف انتظار بترتيب أولوية صارم في عامل واحد.
• تحديد معدل الطلبات. حدود تنفيذ لكل معالج باستخدام نافذة متحركة.
• مهام متكررة. جدولة بفواصل زمنية أو وفق cron، مع سياسات قابلة للضبط للتداخل (السماح والتخطي والتخزين المؤقت).
• إلغاء سير العمل. ألغِ مسارات سير العمل قيد التشغيل وشغّل معالجات التنظيف المسجلة.
• تنقية الحالة. أزل تلقائيًا مخرجات الخطوات القديمة لتسهيل إدارة حالات سير العمل الكبيرة.
• تزامن العمال. يشغّل --workers=N عمليات متعددة ويعيد تشغيلها تلقائيًا عند التعطل.
• رصد شامل. تسجيل في قاعدة البيانات ومقاييس لكل معالج وخطافات ويب للأحداث.
• أدوات الاختبار. يسجّل QueueFake المهام والدفعات المُرسلة لتأكيدها في اختبارات الوحدات.
• سمات PHP. يتيح #[QueuetyHandler('name')] تسجيل المعالجات دون إعداد.

طريقة العمل

يعمل العمال ضمن عملية WP-CLI طويلة التشغيل ويطالبون بالمهام مباشرة من MySQL. تُخزّن صفوف الانتظار وحالة سير العمل والسجلات والدفعات والإشارات وأجزاء البث جميعها في MySQL، لذا لا تؤدي إعادة تشغيل العامل إلى فقدان حالة التنسيق.

تقسّم مسارات سير العمل المهام طويلة التشغيل إلى خطوات. تحفظ كل خطوة مخرجاتها في حزمة حالة مشتركة في قاعدة البيانات. إذا تعطّل PHP أثناء خطوة ما، يعيد العامل محاولة تلك الخطوة مع بقاء الحالة السابقة كاملة. وحدّ الخطوة معاملة MySQL واحدة: يتم تحديث الحالة وإكمال المهمة وإضافة الخطوة التالية إلى صف الانتظار كلها بشكل ذري.

Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed

المتطلبات

• PHP 8.2 أو أحدث
• WordPress 6.4 أو أحدث
• MySQL 8.0+ أو MariaDB 10.6+، لأن العمال يطالبون بالمهام باستخدام SELECT ... FOR UPDATE SKIP LOCKED
• mysqli أو pdo_mysql ضمن وقت التشغيل PHP الذي يحمّل WordPress وWP-CLI
• WP-CLI لتشغيل عمال مخصصين باستخدام wp queuety work
• الامتدادان pcntl وposix PHP لمجمعات العمال (--workers و--min-workers و--max-workers)

راجع Getting Started للتثبيت.