البدء

التثبيت

المتطلبات

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

يتطلب Queuety إما mysqli أو pdo_mysql في بيئة تشغيل PHP التي تحمّل WordPress وWP-CLI. يختار المشغل تلقائيًا، مع تفضيل mysqli لبيئات تشغيل WordPress وإبقاء pdo_mysql متاحًا للاستخدام المستقل أو المباشر.

إذا أردت بيئة تشغيل مدعومة بقاعدة البيانات من دون طبقة إضافة WordPress، راجع الاستخدام المستقل. يستخدم هذا المسار الاتصال نفسه وجداول بيئة التشغيل، لكنه لا يتضمن جسور خطافات WordPress أو تسجيل WP-CLI.

من ملف الإصدار المضغوط

يتضمن كل إصدار من GitHub ملف queuety.zip: الإضافة مع تثبيت تبعيات Composer مسبقًا. ثبّت أحدث إصدار باستخدام WP-CLI:

wp plugin install https://github.com/inline0/queuety/releases/latest/download/queuety.zip --activate

أو نزّل الملف المضغوط وارفعه من الإضافات > أضف إضافة جديدة > رفع إضافة. هذا أبسط مسار لموقع WordPress عادي.

عبر Composer لمواقع WordPress التي تدير تبعياتها باستخدام Composer

composer require queuety/queuety

ثم فعّل الإضافة:

wp plugin activate queuety

نوع الحزمة هو wordpress-plugin. لا يضع Composer الحزمة في مجلد الإضافات إلا عندما يتطلب المشروع composer/installers ويربط ذلك النوع بمسار تثبيت، كما يفعل Bedrock، ويجب أن يحمّل المشروع ملف vendor/autoload.php الخاص به (وهذا ما يفعله Bedrock أيضًا). من دون composer/installers، يثبتها Composer في vendor/queuety/queuety، حيث لا يعثر عليها WordPress، لذا استخدم ملف الإصدار المضغوط في تثبيت WordPress عادي.

من المصدر أثناء التطوير

ضع المستودع في wp-content/plugins/queuety، ثم ثبّت تبعيات PHP:

composer install
wp plugin activate queuety

عند التفعيل، ينشئ Queuety جداول قاعدة البيانات الخاصة به (queuety_jobs، queuety_workflows، queuety_logs، queuety_schedules، queuety_queue_states، queuety_webhooks، queuety_locks، queuety_signals، queuety_workflow_dependencies، queuety_workflow_dispatch_keys، queuety_batches، queuety_chunks، queuety_workflow_events، queuety_artifacts، queuety_state_machines، queuety_state_machine_events) كي يتمكن العمال من المطالبة بالمهام مباشرةً من MySQL.

افتراضيًا، يجدول المكون الإضافي أيضًا عاملًا لمرة واحدة عبر WordPress cron كل دقيقة لطابور default. يوفّر هذا خيارًا أساسيًا بلا صدفة للمهام ومسارات العمل التي تعمل على default، ما دامت WordPress cron تعمل. تعالج كل عملية تشغيل مهمة واحدة كحد أقصى، ولا تشغّل الجداول المتكررة أو تسترد المهام القديمة أو تتحقق من المواعيد النهائية لسير العمل؛ فهذه المهام لا تعمل إلا ضمن عملية wp queuety work طويلة التشغيل (#14). للطوابير المخصصة أو الجداول المتكررة أو زمن استجابة أقل أو أعباء العمل الأكبر، انتقل إلى عمليات wp queuety work مخصصة.

الإعداد

كل الثوابت اختيارية. عرّفها في wp-config.php قبل تحميل الإضافة، أو قبل بدء Queuety في تثبيت مضمّن بأسلوب القوالب:

تُسرد ثوابت قبول الموارد والمجمع التكيفي (QUEUETY_RESOURCE_* وQUEUETY_WORKER_POOL_*) في صفحة Workers.

يغيّر QUEUETY_TABLE_PREFIX الجزء Queuety فقط من أسماء الجداول. تظل بادئة قاعدة البيانات WordPress مضافة إلى الناتج، لذا ينتج عن $wpdb->prefix = 'wp_' وQUEUETY_TABLE_PREFIX = 'themequeue_' جداول مثل wp_themequeue_jobs. وتظل للثوابت الصريحة QUEUETY_TABLE_* الأولوية في الجداول الفردية.

يمكن للاتصالات المستقلة أيضًا تعيين بادئة الجدول Queuety لكل اتصال:

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

يحافظ ذلك على بادئة قاعدة البيانات WordPress كما هي، ولا يغيّر سوى مقطع الجدول Queuety.

مهمتك الأولى

أنشئ فئة معالج تنفّذ الواجهة Handler:

use Queuety\Handler;

class SendEmailHandler implements Handler {
    public function handle( array $payload ): void {
        wp_mail( $payload['to'], $payload['subject'], $payload['body'] );
    }

    public function config(): array {
        return [
            'queue'           => 'emails',
            'max_attempts'    => 5,
        ];
    }
}

سجّلها وأرسل المهمة:

use Queuety\Queuety;

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

Queuety::dispatch( 'send_email', [
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'body'    => 'Hello from Queuety!',
] );

أو استخدم فئة المهمة الحديثة القابلة للإرسال:

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!' );

أول سير عمل لك

عرّف معالجات الخطوات التي تنفّذ الواجهة Step:

use Queuety\Step;

class FetchDataHandler implements Step {
    public function handle( array $state ): array {
        $user = get_user_by( 'ID', $state['user_id'] );
        return [ 'user_name' => $user->display_name ];
    }

    public function config(): array {
        return [];
    }
}

class CallLLMHandler implements Step {
    public function handle( array $state ): array {
        $response = wp_remote_post( 'https://api.openai.com/v1/chat/completions', [
            'body' => json_encode( [ 'prompt' => "Generate report for {$state['user_name']}" ] ),
        ] );
        return [ 'llm_response' => wp_remote_retrieve_body( $response ) ];
    }

    public function config(): array {
        return [ 'max_attempts' => 5 ];
    }
}

class FormatOutputHandler implements Step {
    public function handle( array $state ): array {
        $url = save_report( $state['user_name'], $state['llm_response'] );
        return [ 'report_url' => $url ];
    }

    public function config(): array {
        return [];
    }
}

أرسل سير العمل:

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

بدء عامل

wp queuety work

يستطلع العامل المهام المعلّقة، وينفذها، ويدفع سير العمل إلى الأمام، وينتظر عندما يكون صف الانتظار فارغًا. اضغط Ctrl+C لإيقافه؛ ينهي ذلك العملية فورًا، حتى في منتصف تنفيذ مهمة (راجع Workers).

يرسل SendEmailHandler أعلاه مهامه إلى صف الانتظار emails عبر config()، لذا لن يلتقطها عامل يعمل على default. سمِّ كل صف انتظار تستخدمه:

wp queuety work --queue=emails,default

إذا لم تشغّل عاملًا مخصصًا، فسيظل Queuety يستخدم آلية الرجوع الافتراضية WordPress cron التي تعمل مرة كل دقيقة كما هو موضح أعلاه، وتقتصر على صف الانتظار default ومهمة واحدة في كل تشغيل. العامل المخصص هو الخيار الأعلى إنتاجية والأقل زمنًا للاستجابة.

لبيئة الإنتاج، شغّل عدة عمال:

wp queuety work --workers=4

عالج عدة صفوف انتظار مع ترتيب حسب الأولوية:

wp queuety work --queue=high,default,low

الخطوات التالية

• Jobs للاطلاع على الدليل الكامل لإرسال المهام ومعالجتها
• Workflows للاطلاع على السلاسل والخطوات المتوازية والتفرع الشرطي وتشغيل سير العمل
• Middleware للاطلاع على تحديد معدل الطلبات والخنق ومنطق مسار المعالجة المخصص
• Batching لإرسال مجموعات من المهام مع دوال رد الاتصال
• Streaming Steps لحفظ بيانات البث جزءًا بعد جزء
• Scheduling للمهام المتكررة
• Caching لطبقة التخزين المؤقت القابلة للتبديل
• Testing لاستخدام QueueFake وعمليات التأكيد في الاختبارات
• CLI Reference للاطلاع على جميع الأوامر المتاحة
• PHP API للوصول البرمجي