Lewati ke konten

Cron

Sistem cron memungkinkan Anda menentukan tugas terjadwal yang berjalan di latar belakang secara berkala. Tambahkan file cron.php ke direktori blok Anda, lalu Blockstudio mendaftarkan tugas ke WordPress Cron dan mengelola siklus hidupnya. Instalasi plugin mandiri membersihkan tugasnya saat dinonaktifkan. Instalasi Composer yang disertakan dalam tema atau plugin lain memerlukan pembersihan dari sisi host atau wp bs teardown sebelum host dinonaktifkan, diganti, atau dihapus.

Ini adalah bagian terakhir dari pola blok full-stack: blok Anda dapat memiliki UI (index.twig), logika server (rpc.php), data persisten (db.php), dan kini pemrosesan latar belakang (cron.php).

Cara kerjanya

  1. Anda membuat cron.php di direktori blok
  2. Ini mengembalikan array asosiatif berisi tugas bernama
  3. Pada setiap pemuatan halaman, Blockstudio memeriksa apakah tugas sudah terjadwal
  4. Jadwal yang belum ada didaftarkan dengan wp_schedule_event()
  5. WordPress Cron menjalankan callback pada interval yang ditentukan
  6. Saat plugin Blockstudio mandiri dinonaktifkan, semua event Blockstudio cron dibatalkan jadwalnya; instalasi bundel menggunakan jalur pembersihan di bawah
Kode
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

Menentukan tugas

Kembalikan array asosiatif berisi tugas. Setiap tugas dapat berupa callback langsung (default-nya daily) atau array dengan schedule dan 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());
    },
];

Definisi native PHP

cron.php juga dapat mengembalikan objek dengan metode beratribut. Ini memberikan antarmuka yang lebih rapi dan native PHP tanpa mengubah sintaks array yang sudah ada.

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

Secara default, nama metode dinormalisasi menjadi snake case huruf kecil, jadi cleanupOldEntries() menjadi cleanup_old_entries. Gunakan name: jika Anda menginginkan nama tugas yang ditentukan secara eksplisit.

Jadwal

Bawaan

WordPress menyediakan jadwal berikut secara langsung:

Jadwal Interval
hourly Setiap jam
twicedaily Setiap 12 jam
daily Setiap 24 jam
weekly Setiap 7 hari

Interval kustom

Daftarkan interval kustom melalui filter WordPress cron_schedules, lalu rujuk di 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 () { /* ... */ },
    ],
];

Pola umum

Pemeliharaan data

Bersihkan catatan lama, akhiri masa uji coba, arsipkan entri yang tidak aktif:

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

Sinkronisasi API eksternal

Ambil data dari layanan pihak ketiga sesuai jadwal:

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

Notifikasi dan ringkasan

Kirim laporan berkala atau email notifikasi:

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

Penonaktifan

Saat Blockstudio diinstal sebagai plugin tersendiri, menonaktifkan plugin tersebut otomatis membatalkan jadwal semua event Blockstudio cron.

Instalasi Composer di dalam tema atau plugin lain tidak memiliki hook penonaktifan sendiri. Menonaktifkan plugin host, beralih dari tema host, atau menghapus kode yang disertakan akan membiarkan event tetap terjadwal kecuali host melakukan pembersihan. Jalankan perintah pembongkaran sebelum melakukan salah satunya:

Shell
wp bs teardown

Perintah ini membatalkan jadwal setiap event Blockstudio cron dan menghapus status prerender statis yang dimiliki instalasi tersebut. Lihat CLI untuk detailnya.

Perintah ini hanya tersedia selama Blockstudio masih dimuat. Sebagai gantinya, plugin host dapat mendaftarkan pembersihan dari file plugin utamanya:

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

Tema yang menyertakan bundel dapat menggunakan callback yang sama pada switch_theme. Daftarkan saat tema lama masih dimuat, bukan pada hook after_switch_theme tema berikutnya:

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

Cron::unschedule_all() menghapus semua event Blockstudio cron, bukan hanya tugas dari satu blok atau host. Hook ini tidak menghapus status prerender statis; gunakan wp bs teardown saat menghentikan seluruh instalasi. Tanpa pembersihan, event berulang tetap ada di WordPress dan dapat berjalan kembali jika kode bloknya diinstal lagi.

Filter

Ubah atau nonaktifkan tugas secara terprogram:

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 dipicu oleh kunjungan halaman, bukan oleh penjadwal tingkat sistem. Di situs dengan lalu lintas rendah, tugas mungkin tidak berjalan tepat sesuai jadwal. Untuk pengaturan waktu yang andal, siapkan cron sistem sungguhan yang mengakses wp-cron.php:

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

Lalu nonaktifkan pemicu cron bawaan WordPress di wp-config.php:

PHP
define('DISABLE_WP_CRON', true);

Untuk memeriksa peristiwa terjadwal, gunakan WP-CLI:

Shell
wp cron event list | grep blockstudio