Plugin Options API

A lightweight, centralized way to store and retrieve simple values — flags, counters, timestamps, configuration toggles — without hand-rolling your own JSON read/write logic. Backed by plugins/{slug}/data/options.json, with an in-request memory cache and atomic writes.

When to use it

Well-suited for simple, flat values:

• A boolean toggle ('enabled', 'maintenance_mode')
• A timestamp ('last_digest_sent_at')
• A counter ('total_submissions')
• A short string ('from_email', 'webhook_url')

For structured settings — nested arrays, an SMTP configuration object, per-type defaults — implement your own load_settings()/save_settings() pair against a dedicated data/config.json instead. The options API stores values flat, key by key, and doesn't handle nested defaults.

The three functions

pl_get_option(string $slug, string $key, mixed $default = null): mixed
pl_set_option(string $slug, string $key, mixed $value): bool
pl_delete_option(string $slug, string $key): bool

$enabled = pl_get_option('my-plugin', 'enabled', false);
$lastRun = pl_get_option('my-plugin', 'last_run_at', null);

pl_set_option('my-plugin', 'enabled', true);
pl_set_option('my-plugin', 'last_run_at', date('Y-m-d H:i:s'));

pl_delete_option('my-plugin', 'last_run_at'); // returns true even if the key never existed

pl_set_option()'s value must be JSON-serializable.

A practical example — a simple toggle

// In my-plugin-init.php: read the option at request time
pl_add_hook('early_request', function () {
    if (pl_get_option('my-plugin', 'maintenance', false)) {
        http_response_code(503);
        include __DIR__ . '/maintenance.html';
        exit;
    }
});

// In admin/actions.php: save the toggle when the admin submits the form
pl_set_option('my-plugin', 'maintenance', !empty($_POST['maintenance']));

Storage details

The data/ directory and its .htaccess protection are created automatically on first write — no need to call your own directory-setup helper before using this API. The file is read once per request and cached in memory; later pl_get_option() calls in the same request read from cache, not disk.