Cron
Das cron-System ermöglicht dir, wiederkehrende Aufgaben zu planen, die in regelmäßigen Abständen im Hintergrund ausgeführt werden. Füge eine cron.php-Datei zu deinem Blockverzeichnis hinzu. Blockstudio registriert die Jobs bei WordPress Cron und verwaltet ihren Lebenszyklus. Bei eigenständigen Plugin-Installationen werden die Jobs bei der Deaktivierung bereinigt. Composer-Installationen, die in einem Theme oder einem anderen Plugin eingebunden sind, benötigen eine Bereinigung durch den Host oder wp bs teardown, bevor der Host deaktiviert, gewechselt oder entfernt wird.
Damit ist das Full-Stack-Blockmuster vollständig: Dein Block kann ein UI (index.twig), serverseitige Logik (rpc.php), persistente Daten (db.php) und jetzt auch Hintergrundverarbeitung (cron.php) enthalten.
So funktioniert es
- Du erstellst
cron.phpin deinem Blockverzeichnis - Sie gibt ein assoziatives Array benannter Jobs zurück
- Bei jedem Seitenaufruf prüft Blockstudio, ob die Jobs geplant sind
- Fehlende Zeitpläne werden bei
wp_schedule_event()registriert - WordPress Cron führt die Callbacks im festgelegten Intervall aus
- Bei der Deaktivierung eines eigenständigen Blockstudio-Plugins werden alle Blockstudio-cron-Ereignisse entfernt; eingebundene Installationen verwenden die unten beschriebenen Bereinigungswege
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← custom endpoints
├── db.php ← data model
├── cron.php ← background tasks
└── style.css
Jobs definieren
Gib ein assoziatives Array mit Jobs zurück. Jeder Job kann ein direkter Callback sein (Standard ist daily) oder ein Array mit schedule und 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-native Definitionen
cron.php kann auch ein Objekt mit Attributmethoden zurückgeben. So erhältst du eine übersichtlichere PHP-native Oberfläche, während die bestehende Array-Syntax erhalten bleibt.
<?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
}
};
Methodennamen werden standardmäßig in kleingeschriebene Snake-Case-Namen umgewandelt, sodass cleanupOldEntries() zu cleanup_old_entries wird. Verwende name:, wenn du einen expliziten Jobnamen festlegen möchtest.
Zeitpläne
Vordefiniert
WordPress bietet standardmäßig folgende Zeitpläne:
| Zeitplan | Intervall |
|---|---|
hourly |
Jede Stunde |
twicedaily |
Alle 12 Stunden |
daily |
Alle 24 Stunden |
weekly |
Alle 7 Tage |
Benutzerdefinierte Intervalle
Registriere benutzerdefinierte Intervalle über den Filter WordPress cron_schedules und verweise anschließend in cron.php darauf:
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 () { /* ... */ },
],
];
Häufige Anwendungsfälle
Datenpflege
Bereinige alte Datensätze, lass Testzeiträume ablaufen und archiviere inaktive Einträge:
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']);
}
}
},
],
];
Synchronisierung externer API
Rufe regelmäßig Daten von Drittanbieterdiensten ab:
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);
}
}
},
],
];
Benachrichtigungen und Zusammenfassungen
Versende regelmäßige Berichte oder Benachrichtigungs-E-Mails:
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");
},
],
];
Deaktivierung
Wenn Blockstudio als eigenständiges Plugin installiert ist, werden bei der Deaktivierung des Plugins automatisch alle Blockstudio-cron-Ereignisse aus der Planung entfernt.
Eine Composer-Installation in einem Theme oder einem anderen Plugin hat keinen eigenen Deaktivierungs-Hook. Wird das Host-Plugin deaktiviert, das Host-Theme gewechselt oder der eingebundene Code entfernt, bleiben die Ereignisse geplant, sofern der Host keine Bereinigung durchführt. Führe den Teardown-Befehl vor einem dieser Schritte aus:
wp bs teardown
Damit werden alle Blockstudio cron-Ereignisse aus der Planung entfernt und der statische Prerendering-Status gelöscht, der der Installation gehört. Details findest du unter CLI.
Der Befehl ist nur verfügbar, solange Blockstudio noch geladen ist. Ein Host-Plugin kann die Bereinigung stattdessen in seiner Haupt-Plugin-Datei registrieren:
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Ein einbindendes Theme kann denselben Callback bei switch_theme verwenden. Registriere ihn, solange das alte Theme geladen ist, nicht beim after_switch_theme-Hook des nächsten Themes:
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Cron::unschedule_all() entfernt alle Blockstudio-cron-Ereignisse, nicht nur Jobs eines Blocks oder Hosts. Diese Hooks entfernen keinen statischen Prerender-Status; verwende wp bs teardown, wenn du die gesamte Installation stilllegst. Ohne Bereinigung bleiben wiederkehrende Ereignisse in WordPress bestehen und können erneut starten, wenn der Blockcode wieder installiert wird.
Filter
Jobs programmgesteuert ändern oder deaktivieren:
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;
});
Debugging
WordPress Cron wird durch Seitenaufrufe ausgelöst, nicht durch einen Scheduler auf Systemebene.
Auf Websites mit wenig Traffic werden Jobs möglicherweise nicht genau zum geplanten Zeitpunkt ausgeführt. Richte für zuverlässiges Timing einen echten System-cron ein, der wp-cron.php aufruft:
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
Deaktiviere anschließend den integrierten cron-Trigger von WordPress in wp-config.php:
define('DISABLE_WP_CRON', true);
Geplante Ereignisse kannst du mit WP-CLI prüfen:
wp cron event list | grep blockstudio