wp-admin-settings-api

WordPress Settings API

The Settings API exists so you don't write your own form handling, nonce verification, capability check, sanitization dispatch, error flashing, and option storage. Core does all of it — you describe the form. Plugins that bypass it (POSTing to a custom admin-post handler, writing their own nonce + cap check) end up with worse security and worse a11y than the boring built-in path.

When to use this skill

Trigger when ANY of the following is true:

• A plugin needs an admin settings page that saves option values.
• Code references register_setting, add_settings_section, add_settings_field, settings_fields, do_settings_sections, add_settings_error, settings_errors, options.php, sanitize_callback, or show_in_rest in a plugin context.
• The user is about to write <form method="post" action="<?php echo $_SERVER['REQUEST_URI']; ?>"> and a manual handler — the Settings API is the right answer.
• The user complains: "my settings don't save", "settings_fields nonce mismatch", "options page registered but field doesn't show", "sanitize_callback runs twice", "tabs don't persist data when I switch".

The mental model — three IDs, easy to confuse

The Settings API uses three identifier types and reusing them inconsistently is the single most common debugging dead-end:

You CAN use the same string for $option_group and $page — that's the common simplification. But if you set the menu page slug to one thing, the section page to another, and settings_fields() to a third, the result is: nothing renders (silent — do_settings_sections finds no matching sections) AND the save dies loudly via wp_die() from options.php ("not in the allowed options list"). Two distinct failure modes from the same slug-drift bug. Pick one slug, reuse it.