Cron
يتيح لك نظام cron تعريف مهام مجدولة تعمل في الخلفية على فترات متكررة. أضف ملف cron.php إلى مجلد الكتلة، ويتولى Blockstudio تسجيل المهام باستخدام WordPress Cron وإدارة دورة حياتها. تنظف عمليات تثبيت الإضافة المستقلة مهامها عند إلغاء تفعيلها. أما عمليات تثبيت Composer المضمّنة داخل قالب أو إضافة أخرى، فتحتاج إلى تنظيف من جهة المضيف أو إلى wp bs teardown قبل إلغاء تفعيل المضيف أو تبديله أو إزالته.
هذا هو الجزء الأخير من نمط الكتل المتكامل: يمكن أن تتضمن كتلتك UI (index.twig) ومنطق الخادم (rpc.php) والبيانات الدائمة (db.php) ومعالجة المهام في الخلفية (cron.php).
طريقة العمل
- أنشئ
cron.phpفي مجلد الكتلة - يعيد مصفوفة ترابطية بالمهام المسماة
- عند كل تحميل للصفحة، يتحقق Blockstudio مما إذا كانت المهام مجدولة
- تُسجّل الجداول المفقودة باستخدام
wp_schedule_event() - يشغّل WordPress Cron دوال الاستدعاء وفق الفاصل الزمني المحدد
- عند إلغاء تفعيل إضافة 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:
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
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:
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;
});
return [
'check_external_api' => [
'schedule' => 'every_five_minutes',
'callback' => function () { /* ... */ },
],
];
أنماط شائعة
صيانة البيانات
نظّف السجلات القديمة، وأنهِ صلاحية الفترات التجريبية، وأرشف الإدخالات غير النشطة:
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 خارجي
اجلب البيانات من خدمات الجهات الخارجية وفق جدول زمني:
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);
}
}
},
],
];
الإشعارات والملخصات
أرسل تقارير دورية أو رسائل بريد إلكتروني للإشعارات:
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 محمّلًا. ويمكن للإضافة المضيفة بدلًا من ذلك تسجيل التنظيف من ملف الإضافة الرئيسي:
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
يمكن للقالب الذي يضم الحزمة استخدام دالة الاستدعاء نفسها عند switch_theme. سجّلها أثناء تحميل القالب القديم، لا عند خطاف after_switch_theme الخاص بالقالب التالي:
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
يزيل Cron::unschedule_all() جميع أحداث Blockstudio cron، وليس المهام التابعة لكتلة أو مضيف واحد فقط. ولا تزيل هذه الخطافات حالة العرض المسبق الثابتة؛ استخدم wp bs teardown عند إيقاف التثبيت بالكامل. من دون التنظيف، تظل الأحداث المتكررة في WordPress وقد تستأنف عملها إذا ثُبّتت شيفرة الكتلة مجددًا.
التصفية
تعديل المهام أو تعطيلها برمجيًا:
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:
define('DISABLE_WP_CRON', true);
للتحقق من الأحداث المجدولة، استخدم WP-CLI:
wp cron event list | grep blockstudio