WordPress Options API Autoload Example: Store Plugin Settings Without Slowing Requests

Last reviewed: April 22, 2026

The WordPress Options API is simple, but option storage can hurt performance when plugins put large values into autoloaded options. Autoloaded options are loaded early on every request, so they should be small, frequently needed, and intentionally chosen.

This guide shows how to store plugin options without slowing every request, when to use autoload, and how to keep settings separate from large operational data.

Problem this solves

Many plugins store everything in one option array because it is convenient. That works until the option grows into hundreds of kilobytes of logs, API responses, generated reports, or cached data. If that option autoloads, every request pays the cost even when the data is not needed.

Small settings option

<?php
function vulnwp_get_plugin_settings() {
	$defaults = array(
		'enabled' => false,
		'limit'   => 10,
	);

	$settings = get_option( 'vulnwp_plugin_settings', $defaults );

	return wp_parse_args( $settings, $defaults );
}

Small settings that are needed on most requests can be reasonable autoload candidates. Keep them focused and predictable.

Add large options with autoload disabled

Use add_option() when you need to control autoload behavior at creation time.

function vulnwp_store_large_report( array $report ) {
	$option_name = 'vulnwp_large_report_cache';

	if ( false === get_option( $option_name, false ) ) {
		add_option( $option_name, $report, '', 'no' );
		return;
	}

	update_option( $option_name, $report );
}

This pattern creates the option with autoload disabled. Use it for large data that is needed only on specific admin pages, reports, or background tasks.

Separate settings from data

Keep permanent configuration separate from generated or cached data. A plugin might use one small settings option and separate non-autoloaded options for reports, import state, or remote API snapshots.

vulnwp_plugin_settings        small, configuration, may autoload
vulnwp_large_report_cache     large, generated data, no autoload
vulnwp_last_import_state      operational state, usually no autoload

Audit autoloaded plugin options

On production, review large autoloaded options periodically. The exact SQL should be run carefully and only by someone who understands the database environment.

SELECT option_name, LENGTH(option_value) AS bytes
FROM wp_options
WHERE autoload IN ('yes', 'on', 'auto-on')
ORDER BY bytes DESC
LIMIT 20;

Do not delete options blindly. First identify the owning plugin, understand the value, and confirm whether it can be moved, trimmed, or recreated.

When to use transients instead

If the value is temporary cache data, a transient is often a better fit than a normal option. Transients communicate intent, include expiration, and can use persistent object cache when available. Options are better for configuration and durable state.

A good rule: if the value can be regenerated and should expire, use a transient. If the value is a setting that defines plugin behavior, use an option. If the value grows indefinitely, use neither without a retention plan.

Testing workflow

1. Install the plugin on staging and create realistic settings.
2. Check the options table for plugin-owned option names.
3. Confirm large generated values are not autoloaded.
4. Deactivate and uninstall on staging to confirm cleanup behavior.
5. Repeat after importing a production-sized dataset.

Production checklist

• Keep autoloaded options small.
• Use add_option() when autoload control matters.
• Separate settings from cache, logs, and generated reports.
• Delete plugin-owned options on uninstall when policy allows it.
• Avoid storing unbounded arrays in options.
• Review large autoloaded options during performance audits.

Common mistakes

• One option for everything. Settings and generated data have different loading needs.
• Large autoloaded values. They affect every request.
• No cleanup policy. Old plugin options can remain for years.
• Direct database edits without cache awareness. Use the Options API where possible.
• Storing logs in options. Logs need retention and a better storage model.

Related reading

For settings screens, read the Settings API example. For plugin removal policy, read the plugin uninstall example.

References and further reading

• WordPress Plugin Handbook: Options API
• WordPress Common APIs Handbook: Options
• WordPress Code Reference: update_option()