Przejdź do treści

Cron

System cron pozwala definiować zaplanowane zadania uruchamiane w tle w regularnych odstępach czasu. Dodaj plik cron.php do katalogu bloku, a Blockstudio zarejestruje zadania za pomocą WordPress Cron i będzie zarządzać ich cyklem życia. Samodzielne instalacje wtyczki usuwają zadania podczas dezaktywacji. Instalacje Composer dołączone do motywu lub innej wtyczki wymagają czyszczenia po stronie hosta albo wp bs teardown przed dezaktywacją, zmianą lub usunięciem hosta.

To ostatni element pełnego wzorca bloku: blok może mieć UI (index.twig), logikę serwerową (rpc.php), trwałe dane (db.php), a teraz także przetwarzanie w tle (cron.php).

Jak to działa

  1. Tworzysz cron.php w katalogu bloku
  2. Zwraca ono tablicę asocjacyjną nazwanych zadań
  3. Przy każdym wczytaniu strony Blockstudio sprawdza, czy zadania są zaplanowane
  4. Brakujące harmonogramy są rejestrowane za pomocą wp_schedule_event()
  5. WordPress Cron uruchamia funkcje zwrotne w określonych odstępach czasu
  6. Podczas dezaktywacji samodzielnej wtyczki Blockstudio wszystkie zdarzenia Blockstudio cron są usuwane z harmonogramu; instalacje dołączone do hosta korzystają z opisanych niżej ścieżek czyszczenia
Kod
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

Definiowanie zadań

Zwróć tablicę asocjacyjną zadań. Każde zadanie może być bezpośrednią funkcją zwrotną (domyślnie daily) lub tablicą z schedule i 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());
    },
];

Definicje natywne PHP

cron.php może również zwrócić obiekt z metodami przypisanymi do atrybutów. Zapewnia to przejrzystszy interfejs natywny dla PHP, zachowując dotychczasową składnię tablicy.

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

Domyślnie nazwy metod są normalizowane do zapisu snake_case małymi literami, więc cleanupOldEntries() zmienia się w cleanup_old_entries. Użyj name:, aby podać jawną nazwę zadania.

Harmonogramy

Wbudowane

WordPress udostępnia od razu następujące harmonogramy:

Harmonogram Odstęp
hourly Co godzinę
twicedaily Co 12 godzin
daily Co 24 godziny
weekly Co 7 dni

Niestandardowe odstępy

Zarejestruj niestandardowe odstępy za pomocą filtra WordPress cron_schedules, a następnie odwołaj się do nich w 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 () { /* ... */ },
    ],
];

Typowe zastosowania

Konserwacja danych

Usuwaj stare rekordy, kończ okresy próbne i archiwizuj nieaktywne wpisy:

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

Synchronizacja zewnętrznego API

Pobieraj dane z usług zewnętrznych według harmonogramu:

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

Powiadomienia i zestawienia

Wysyłaj okresowe raporty lub e-maile z powiadomieniami:

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

Dezaktywacja

Gdy Blockstudio jest zainstalowane jako samodzielna wtyczka, jej dezaktywacja automatycznie usuwa z harmonogramu wszystkie zdarzenia Blockstudio cron.

Instalacja Composer w motywie lub innej wtyczce nie ma własnego haka dezaktywacji. Dezaktywacja wtyczki hosta, zmiana motywu hosta lub usunięcie dołączonego kodu pozostawi zaplanowane zdarzenia, chyba że host przeprowadzi czyszczenie. Uruchom polecenie demontażu przed wykonaniem którejkolwiek z tych czynności:

Powłoka
wp bs teardown

Usuwa ono z harmonogramu każde zdarzenie Blockstudio cron i usuwa statyczny stan prerenderowania należący do tej instalacji. Szczegóły znajdziesz w CLIprzewodniku.

Polecenie jest dostępne tylko wtedy, gdy Blockstudio jest nadal załadowane. Zamiast tego wtyczka hosta może zarejestrować czyszczenie w swoim głównym pliku wtyczki:

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

Motyw dołączający pakiet może użyć tego samego wywołania zwrotnego w switch_theme. Zarejestruj je, gdy stary motyw jest załadowany, a nie w funkcji haka after_switch_theme następnego motywu:

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

Cron::unschedule_all() usuwa wszystkie zdarzenia Blockstudio cron, a nie tylko zadania z jednego bloku lub hosta. Te haki nie usuwają statycznego stanu prerenderowania; użyj wp bs teardown przy wycofywaniu całej instalacji. Bez czyszczenia cykliczne zdarzenia pozostają w WordPress i mogą zostać wznowione po ponownym zainstalowaniu kodu bloku.

Filtr

Modyfikuj lub wyłącz zadania programowo:

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

Debugowanie

WordPress Cron jest uruchamiane podczas odwiedzin strony, a nie przez systemowy harmonogram. Na stronach o małym ruchu zadania mogą nie uruchamiać się dokładnie zgodnie z harmonogramem. Aby zapewnić niezawodne działanie, skonfiguruj rzeczywisty systemowy cron, który odpytuje wp-cron.php:

Powłoka
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

Następnie wyłącz wbudowany wyzwalacz cron w wp-config.php dla WordPress:

PHP
define('DISABLE_WP_CRON', true);

Aby sprawdzić zaplanowane zdarzenia, użyj WP-CLI:

Powłoka
wp cron event list | grep blockstudio