README

A settings page from a list of fields — the menu, the tabs, the saving and the sanitising included.

What it does

A settings screen in WordPress is add_menu_page, register_setting, add_settings_section, add_settings_field and a sanitise callback per field, repeated until it works. Most of it is the same every time, and the part that varies is just the list of fields.

This takes the list. The menu, the tabs, the form, the nonce, the saving and the per-type sanitising follow from it.

Features

Get a settings page from a list of fields, with no add_settings_field calls
Group fields into tabs and sections, saving one tab without touching others
Read and write a value by name, without knowing how the option is shaped
Sanitise per field type, rather than writing a callback for each
Refuse a value that is missing or malformed, and say which field
Encrypt a field, so an API key is not stored in the clear
Export, import and reset from Screen Options
Show a field only when another is set

Installation

composer require arraypress/wp-register-setting-fields

Quick start

register_setting_fields( 'my_plugin', [
	'page_title'  => __( 'My Plugin Settings', 'my-plugin' ),
	'menu_title'  => __( 'My Plugin', 'my-plugin' ),
	'parent_slug' => 'options-general.php',
	'fields'      => [
		'site_name'      => [ 'type' => 'text', 'label' => __( 'Site name', 'my-plugin' ) ],
		'enable_feature' => [ 'type' => 'toggle', 'label' => __( 'Enable feature', 'my-plugin' ) ],
		'items_per_page' => [
			'type'  => 'number',
			'label' => __( 'Items per page', 'my-plugin' ),
			'min'   => 1,
			'max'   => 100,
		],
	],
] );

Then reading one, anywhere:

$name = get_setting_field_value( 'my_plugin', 'site_name' );

Field types come from arraypress/wp-field-kit, so anything it renders can go in a settings page.

Validation

Sanitising coerces; it does not refuse. A field that must hold something says 'required' => true, and one that must hold a particular shape names a rule with validate — email, url, numeric, integer, slug, alphanumeric, or a callable returning true, a message or a WP_Error:

'contact' => [ 'type' => 'text', 'label' => __( 'Contact', 'my-plugin' ), 'required' => true, 'validate' => 'email' ],

A value that fails is not stored. The field keeps what it held, every other field on the tab is saved, and after the redirect the message appears as an error notice at the top of the page — in place of "Settings saved." — and again under the field itself.

Requirements

PHP 8.3 or later
WordPress 7.1 or later

License

GPL-2.0-or-later

arraypress / wp-register-setting-fields

Package info

Security

Statistics