Zum Inhalt springen

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

  1. Du erstellst cron.php in deinem Blockverzeichnis
  2. Sie gibt ein assoziatives Array benannter Jobs zurück
  3. Bei jedem Seitenaufruf prüft Blockstudio, ob die Jobs geplant sind
  4. Fehlende Zeitpläne werden bei wp_schedule_event() registriert
  5. WordPress Cron führt die Callbacks im festgelegten Intervall aus
  6. Bei der Deaktivierung eines eigenständigen Blockstudio-Plugins werden alle Blockstudio-cron-Ereignisse entfernt; eingebundene Installationen verwenden die unten beschriebenen Bereinigungswege
Code
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:

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-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
<?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:

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 () { /* ... */ },
    ],
];

Häufige Anwendungsfälle

Datenpflege

Bereinige alte Datensätze, lass Testzeiträume ablaufen und archiviere inaktive Einträge:

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']);
                }
            }
        },
    ],
];

Synchronisierung externer API

Rufe regelmäßig Daten von Drittanbieterdiensten ab:

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

Benachrichtigungen und Zusammenfassungen

Versende regelmäßige Berichte oder Benachrichtigungs-E-Mails:

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");
        },
    ],
];

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:

Shell
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:

PHP
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:

PHP
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:

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

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:

Shell
*/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:

PHP
define('DISABLE_WP_CRON', true);

Geplante Ereignisse kannst du mit WP-CLI prüfen:

Shell
wp cron event list | grep blockstudio