arraypress / wp-register-setting-fields
Registers a tabbed WordPress settings page from a field configuration, rendered by wp-field-kit.
Package info
github.com/arraypress/wp-register-setting-fields
pkg:composer/arraypress/wp-register-setting-fields
Requires
- php: >=8.3
- arraypress/wp-field-kit: dev-main
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/settings(namespaceSugarCommerce\Settings, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
Register Setting Fields
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_fieldcalls - 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
- Read settings on the front end, in cron or at activation, before the page exists
- 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.
Reading settings anywhere
The page is registered from one hook, and a plugin's settings are read from
everywhere: the front end, cron, a webhook, activation. Options is one
reader for all of them. When the page is registered it asks the page; when
it is not, it reads the option through the same decorators the page uses, so
an encrypted API key comes back as the key rather than as its ciphertext.
use ArrayPress\RegisterSettingFields\Options; function my_plugin_options(): Options { static $options = null; return $options ??= new Options( 'my_plugin_settings', [ 'page' => 'my_plugin', // The id the page is registered under. 'hook_prefix' => 'my_plugin', // Fires my_plugin_get_option and friends. 'fields' => 'my_plugin_settings_fields', // Callable or array: defaults and encryption before the page exists. ] ); } $key = my_plugin_options()->get( 'api_key', '' ); // Decrypted, constant, default, then the fallback. my_plugin_options()->update( 'api_key', $new_key ); // Encrypted if the field is. my_plugin_options()->delete( 'api_key' ); // The next read is the field's default. my_plugin_options()->all(); // Everything, as stored.
get()answers in the page's order: a constant the field opted into, the stored value decrypted, the field'sdefault, then the fallback. With nofieldsto go on it still decrypts, because ciphertext carries a marker.update()goes through the page when it is registered, which refuses a key that is not one of its fields. Without the page an encrypted field is still written encrypted.delete()is false when nothing is stored under the key. A secret that will not decrypt is kept until something readable replaces it.- A
fieldscallable is called once, on the first read that needs it. One that reads a setting while it builds the configuration gets an answer from the stored value rather than calling itself again.
With a hook_prefix, all() is filtered by {prefix}_get_settings,
get() by {prefix}_get_option and {prefix}_get_option_{$key}, and a
change fires {prefix}_update_option with the key, the new value and the
previous one. With none, nothing is fired. constant_prefix names a field's
constant as the page's own setting does, and defaults the same way: the
option name and an underscore.
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.
Appearance
A page is drawn as WordPress draws its own: a heading and a form table per section, the label on the left. That is the default and it is what every existing page keeps.
A plugin whose other screens are cards can ask for the page to match:
register_setting_fields( 'my_plugin', [ 'page_title' => __( 'My Plugin Settings', 'my-plugin' ), 'appearance' => 'modern', 'sections' => [ 'account' => [ 'title' => __( 'Account', 'my-plugin' ), 'description' => __( 'Who this site signs in as.', 'my-plugin' ), 'status' => [ 'label' => __( 'Connected', 'my-plugin' ), 'tone' => 'success' ], ], 'advanced' => [ 'title' => __( 'Advanced', 'my-plugin' ), 'collapsed' => true, ], ], 'fields' => [ 'api_key' => [ 'type' => 'password', 'label' => __( 'API key', 'my-plugin' ), 'section' => 'account', 'encrypted' => true, 'tooltip' => __( 'From your account page, under Developers.', 'my-plugin' ), ], 'timeout' => [ 'type' => 'number', 'label' => __( 'Timeout', 'my-plugin' ), 'section' => 'advanced', 'width' => 'half', ], ], ] );
Each section is then a white card with its title and description, each
field has its label above it and its tooltip as a help icon beside the
label, and the save button rides in a bar that stays at the foot of the
window and says "Saved" after a clean save in place of the notice. Three
things a section can say only apply here:
collapsedfolds the card away until it is opened. It opens by itself when a field inside it was refused.statusis a short state beside the title — a label, or a label and atoneofsuccess,warning,error,infoorneutral. A closure is called when the card is drawn, which is when the page's own settings can be read.- A
descriptionmay hold a short list as well as a sentence.
A section with a description and no fields is drawn too -- a card that only
explains, such as where a key is found. Nothing places it on a tab, so it
names one with tab and is on the first otherwise. A title over nothing is
not drawn. The classic appearance draws such a section as its heading and
paragraph.
A field's width of half puts two on a line. Nothing about what is
stored, sanitised or refused changes with the appearance.
Tabs down the side
A modern page keeps the centred header and its row of tabs unless it asks otherwise. A plugin with a menu of its own, whose settings sit between its list screens and its reports, can have the page laid out as those are:
register_setting_fields( 'my_plugin', [ 'header_title' => __( 'Settings', 'my-plugin' ), 'appearance' => 'modern', 'layout' => 'sidebar', 'tabs' => [ 'general' => [ 'label' => __( 'General', 'my-plugin' ), 'icon' => 'heroicons-outline:cog-6-tooth' ], 'payments' => [ 'label' => __( 'Payments', 'my-plugin' ), 'icon' => 'dashicons-money-alt' ], ], 'fields' => [ 'name' => [ 'type' => 'text', 'label' => __( 'Name', 'my-plugin' ), 'tab' => 'general' ], ], ] );
The title is then core's own heading at the top left ("Settings", and
"Settings › Payments" past the first tab) with notices under it, the tabs
are a card of links beside the cards, and on a narrow screen they are one
row of pills that scrolls. A tab's icon is drawn only in this layout, and
takes either form the field kit's Icons::render() reads: a set:name icon
(heroicons-outline:cog-6-tooth, any set the kit has), drawn as inline SVG, or
a Dashicon by its name or its class (money-alt, dashicons-money-alt),
drawn as the font's span. A tab without one, or with one no set has, keeps
the space for it. The tick beside "Saved" is heroicons-outline:check-circle. layout is tabs by default and is read only when
the appearance is modern; the logo and badge of the header are not
drawn in the sidebar layout.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later