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

Cron

يتيح لك نظام cron تعريف مهام مجدولة تعمل في الخلفية على فترات متكررة. أضف ملف cron.php إلى مجلد الكتلة، ويتولى Blockstudio تسجيل المهام باستخدام WordPress Cron وإدارة دورة حياتها. تنظف عمليات تثبيت الإضافة المستقلة مهامها عند إلغاء تفعيلها. أما عمليات تثبيت Composer المضمّنة داخل قالب أو إضافة أخرى، فتحتاج إلى تنظيف من جهة المضيف أو إلى wp bs teardown قبل إلغاء تفعيل المضيف أو تبديله أو إزالته.

هذا هو الجزء الأخير من نمط الكتل المتكامل: يمكن أن تتضمن كتلتك UI (index.twig) ومنطق الخادم (rpc.php) والبيانات الدائمة (db.php) ومعالجة المهام في الخلفية (cron.php).

طريقة العمل

  1. أنشئ cron.php في مجلد الكتلة
  2. يعيد مصفوفة ترابطية بالمهام المسماة
  3. عند كل تحميل للصفحة، يتحقق Blockstudio مما إذا كانت المهام مجدولة
  4. تُسجّل الجداول المفقودة باستخدام wp_schedule_event()
  5. يشغّل WordPress Cron دوال الاستدعاء وفق الفاصل الزمني المحدد
  6. عند إلغاء تفعيل إضافة Blockstudio المستقلة، تُلغى جدولة جميع أحداث Blockstudio cron؛ أما عمليات التثبيت المضمّنة فتستخدم مسارات التنظيف أدناه
الكود
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

تعريف المهام

أعِد مصفوفة ترابطية من المهام. يمكن أن تكون كل مهمة استدعاءً راجعًا مباشرًا (افتراضيًا إلى daily) أو مصفوفة تحتوي على schedule وcallback:

PHP
return [
    // Expanded format with custom schedule
    'cleanup' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // runs every hour
        },
    ],

    // Shorthand: just a callback, defaults to daily
    'heartbeat' => function () {
        update_option('my_block_last_heartbeat', time());
    },
];

تعريفات أصلية لـ PHP

يمكن أن يعيد cron.php أيضًا كائنًا بأساليب ذات سمات. يمنحك ذلك واجهة أنظف وأقرب إلى PHP مع الحفاظ على صيغة المصفوفة الحالية.

PHP
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
        update_option('my_block_last_heartbeat', time());
    }

    #[Cron]
    public function cleanupOldEntries(): void {
        // defaults to daily
    }
};

تُحوّل أسماء الأساليب افتراضيًا إلى أحرف صغيرة بصيغة snake case، لذا يصبح cleanupOldEntries() cleanup_old_entries. استخدم name: عندما تريد اسمًا صريحًا للمهمة.

الجداول الزمنية

المضمنة

يوفر WordPress الجداول الزمنية التالية جاهزة للاستخدام:

الجدول الزمني الفاصل الزمني
hourly كل ساعة
twicedaily كل 12 ساعة
daily كل 24 ساعة
weekly كل 7 أيام

فواصل زمنية مخصصة

سجّل فواصل زمنية مخصصة عبر مرشح WordPress cron_schedules، ثم أشر إليها في cron.php:

PHP
add_filter('cron_schedules', function ($schedules) {
    $schedules['every_five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes',
    ];
    $schedules['every_fifteen_minutes'] = [
        'interval' => 900,
        'display'  => 'Every 15 Minutes',
    ];
    return $schedules;
});
PHP
return [
    'check_external_api' => [
        'schedule' => 'every_five_minutes',
        'callback' => function () { /* ... */ },
    ],
];

أنماط شائعة

صيانة البيانات

نظّف السجلات القديمة، وأنهِ صلاحية الفترات التجريبية، وأرشف الإدخالات غير النشطة:

PHP
use Blockstudio\Db;

return [
    'expire_trials' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db     = Db::get('my-theme/app', 'subscribers');
            $trials = $db->list(['plan' => 'trial']);

            foreach ($trials as $trial) {
                if (strtotime($trial['created_at']) < strtotime('-14 days')) {
                    $db->update((int) $trial['id'], ['plan' => 'expired']);
                }
            }
        },
    ],
    'purge_old_logs' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'activity_log');
            $logs = $db->list();

            foreach ($logs as $log) {
                if (strtotime($log['created_at']) < strtotime('-90 days')) {
                    $db->delete((int) $log['id']);
                }
            }
        },
    ],
];

مزامنة API خارجي

اجلب البيانات من خدمات الجهات الخارجية وفق جدول زمني:

PHP
return [
    'sync_products' => [
        'schedule' => 'hourly',
        'callback' => function () {
            $response = wp_remote_get('https://api.example.com/products');

            if (is_wp_error($response)) {
                return;
            }

            $products = json_decode(wp_remote_retrieve_body($response), true);
            $db       = \Blockstudio\Db::get('my-theme/shop', 'products');

            foreach ($products as $product) {
                $existing = $db->list(['external_id' => $product['id']]);

                if (empty($existing)) {
                    $db->create($product);
                } else {
                    $db->update((int) $existing[0]['id'], $product);
                }
            }
        },
    ],
];

الإشعارات والملخصات

أرسل تقارير دورية أو رسائل بريد إلكتروني للإشعارات:

PHP
use Blockstudio\Db;

return [
    'weekly_digest' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'subscribers');
            $new  = count($db->list(['status' => 'active']));
            $admin = get_option('admin_email');

            wp_mail($admin, 'Weekly Digest', "Active subscribers: $new");
        },
    ],
];

التعطيل

عند تثبيت Blockstudio كإضافة مستقلة، يؤدي إلغاء تفعيلها تلقائيًا إلى إلغاء جدولة جميع أحداث Blockstudio cron.

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

سطر الأوامر
wp bs teardown

يلغي جدولة كل حدث Blockstudio cron ويزيل حالة العرض المسبق الثابتة التي يملكها التثبيت. راجع CLI لمزيد من التفاصيل.

لا يتوفر الأمر إلا ما دام Blockstudio محمّلًا. ويمكن للإضافة المضيفة بدلًا من ذلك تسجيل التنظيف من ملف الإضافة الرئيسي:

PHP
register_deactivation_hook(__FILE__, function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

يمكن للقالب الذي يضم الحزمة استخدام دالة الاستدعاء نفسها عند switch_theme. سجّلها أثناء تحميل القالب القديم، لا عند خطاف after_switch_theme الخاص بالقالب التالي:

PHP
add_action('switch_theme', function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

يزيل Cron::unschedule_all() جميع أحداث Blockstudio cron، وليس المهام التابعة لكتلة أو مضيف واحد فقط. ولا تزيل هذه الخطافات حالة العرض المسبق الثابتة؛ استخدم wp bs teardown عند إيقاف التثبيت بالكامل. من دون التنظيف، تظل الأحداث المتكررة في WordPress وقد تستأنف عملها إذا ثُبّتت شيفرة الكتلة مجددًا.

التصفية

تعديل المهام أو تعطيلها برمجيًا:

PHP
add_filter('blockstudio/cron', function (array $jobs): array {
    // Disable a specific job
    unset($jobs['my-theme/app']['cleanup']);

    // Change a schedule
    if (isset($jobs['my-theme/app']['sync'])) {
        $jobs['my-theme/app']['sync']['schedule'] = 'twicedaily';
    }

    return $jobs;
});

تصحيح الأخطاء

WordPress يُشغَّل Cron عند زيارة الصفحات، وليس بواسطة مجدول على مستوى النظام. في المواقع ذات الزيارات المنخفضة، قد لا تُنفَّذ المهام في موعدها تمامًا. لضمان توقيت موثوق، أعِد إعداد cron نظام حقيقي يستدعي wp-cron.php:

سطر الأوامر
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

بعدها عطّل مُشغِّل cron المدمج في WordPress ضمن wp-config.php:

PHP
define('DISABLE_WP_CRON', true);

للتحقق من الأحداث المجدولة، استخدم WP-CLI:

سطر الأوامر
wp cron event list | grep blockstudio