Skip to content

Commit 451d5b8

Browse files
arraypressclaude
arraypress
and
claude
committed
Drop the docs site; the README is the documentation
Forty-six files and a GitHub Pages workflow, for a library whose README was a forty-three line signpost pointing at it. Registration, tabs and sections, conditional fields, encryption, constants and every accessor are in the README now, and `composer docs:verify` checks its examples on every build. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tk8y5eZa3CHVVSM6nVxsJw
1 parent 5cffccf commit 451d5b8

49 files changed

Lines changed: 178 additions & 2660 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/static.yml‎

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎README.md‎

Lines changed: 177 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,205 @@
1-
# WordPress Setting Fields Library
1+
# WordPress Register Setting Fields
22

3-
A WordPress library for creating settings pages with tabs, sections, branded headers, and 30+ field types. Handles
4-
registration, rendering, sanitization, and the Settings API — you just define your fields.
3+
Settings pages for the WordPress admin, from a field configuration.
4+
5+
Registration, rendering, sanitization and the Settings API are handled; you describe the fields. Every type comes from
6+
[wp-field-kit](https://github.com/arraypress/wp-field-kit), so the same configuration renders the same control here, in
7+
a metabox, on a term screen or in a flyout.
8+
9+
## Features
10+
11+
- Every field type the kit has — sixty-odd, from text to a repeater to an email editor
12+
- Tabs and sections, with the tab remembered in the URL
13+
- A branded header with a logo, badge and whatever you want beside it
14+
- Conditional fields, encrypted values, and constants that override an option
15+
- Reset, export and import, when you want them
16+
- Values readable through helpers that know what a field meant, not just what it stored
17+
18+
## Requirements
19+
20+
- PHP 7.4+
21+
- WordPress 5.8+
522

623
## Installation
724

825
```bash
926
composer require arraypress/wp-register-setting-fields
1027
```
1128

12-
## Quick Start
29+
## Quick start
1330

1431
```php
1532
register_setting_fields( 'my_plugin', [
16-
'page_title' => 'My Plugin Settings',
17-
'menu_title' => 'My Plugin',
33+
'page_title' => __( 'My Plugin Settings', 'my-plugin' ),
34+
'menu_title' => __( 'My Plugin', 'my-plugin' ),
1835
'parent_slug' => 'options-general.php',
1936
'fields' => [
20-
'site_name' => [ 'type' => 'text', 'label' => 'Site Name' ],
21-
'enable_feature' => [ 'type' => 'toggle', 'label' => 'Enable Feature' ],
22-
'items_per_page' => [ 'type' => 'number', 'label' => 'Items Per Page', 'min' => 1, 'max' => 100 ],
37+
'site_name' => [ 'type' => 'text', 'label' => __( 'Site name', 'my-plugin' ) ],
38+
'enable_feature' => [ 'type' => 'toggle', 'label' => __( 'Enable feature', 'my-plugin' ) ],
39+
'items_per_page' => [
40+
'type' => 'number',
41+
'label' => __( 'Items per page', 'my-plugin' ),
42+
'min' => 1,
43+
'max' => 100,
44+
],
2345
],
2446
] );
47+
```
2548

49+
Reading them back:
50+
51+
```php
2652
$name = get_setting_field_value( 'my_plugin', 'site_name' );
2753

2854
if ( is_setting_on( 'my_plugin', 'enable_feature' ) ) {
29-
// Feature is enabled
55+
// ...
3056
}
3157
```
3258

33-
## Documentation
59+
## Registration
3460

35-
Full documentation is available at **[https://arraypress.github.io/wp-register-setting-fields](https://arraypress.github.io/wp-register-setting-fields)**
61+
```php
62+
register_setting_fields( 'my_plugin', [
63+
'page_title' => __( 'My Plugin Settings', 'my-plugin' ),
64+
'menu_title' => __( 'My Plugin', 'my-plugin' ),
65+
'menu_slug' => 'my-plugin',
66+
'parent_slug' => 'options-general.php',
67+
'capability' => 'manage_options',
68+
'option_name' => 'my_plugin',
69+
'icon' => 'dashicons-admin-generic',
70+
'position' => null,
71+
'submit_button' => true,
72+
'reset_button' => false,
73+
'export_import' => false,
74+
'tabs' => [ /* ... */ ],
75+
'sections' => [ /* ... */ ],
76+
'fields' => [ /* ... */ ],
77+
] );
78+
```
3679

37-
## Requirements
80+
| Key | What it does |
81+
| --- | --- |
82+
| `page_title` / `menu_title` | The page's heading and its menu entry. |
83+
| `menu_slug` | The page slug. Defaults to the id. |
84+
| `parent_slug` | Where it sits. A top-level menu when empty. |
85+
| `capability` | Who may see it. Defaults to `manage_options`. |
86+
| `option_name` | The option every value is stored in. Defaults to the id. |
87+
| `option_group` | The Settings API group. Defaults to `{id}_group`. |
88+
| `constant_prefix` | Constants that override stored values. Defaults to `{option_name}_`. |
89+
| `header_title`, `logo`, `badge` | A branded header instead of the plain one. |
90+
| `icon`, `position` | Menu icon and position, for a top-level page. |
91+
| `submit_button` | Whether to draw one. |
92+
| `reset_button` | A "restore defaults" button. |
93+
| `export_import` | Buttons to download and upload the settings as JSON. |
94+
| `help_tabs`, `help_sidebar` | Contextual help, in core's own panel. |
3895

39-
- PHP 7.4+
40-
- WordPress 5.8+
96+
## Tabs and sections
97+
98+
A field says which tab and which section it belongs to. Both are optional and can be mixed.
99+
100+
```php
101+
register_setting_fields( 'my_plugin', [
102+
'tabs' => [
103+
'general' => __( 'General', 'my-plugin' ),
104+
'advanced' => __( 'Advanced', 'my-plugin' ),
105+
],
106+
'sections' => [
107+
'branding' => [
108+
'title' => __( 'Branding', 'my-plugin' ),
109+
'description' => __( 'How it looks.', 'my-plugin' ),
110+
],
111+
],
112+
'fields' => [
113+
'site_name' => [
114+
'type' => 'text',
115+
'label' => __( 'Site name', 'my-plugin' ),
116+
'tab' => 'general',
117+
'section' => 'branding',
118+
],
119+
'debug' => [
120+
'type' => 'toggle',
121+
'label' => __( 'Debug mode', 'my-plugin' ),
122+
'tab' => 'advanced',
123+
],
124+
],
125+
] );
126+
```
127+
128+
## Conditional fields
129+
130+
```php
131+
'fields' => [
132+
'mode' => [
133+
'type' => 'select',
134+
'label' => __( 'Mode', 'my-plugin' ),
135+
'options' => [ 'auto' => __( 'Automatic', 'my-plugin' ), 'manual' => __( 'Manual', 'my-plugin' ) ],
136+
],
137+
'api_key' => [
138+
'type' => 'password',
139+
'label' => __( 'API key', 'my-plugin' ),
140+
'depends' => [ 'mode' => 'manual' ],
141+
],
142+
],
143+
```
144+
145+
The field is removed from the tab order when hidden, not merely made invisible.
146+
147+
## Encrypted values
148+
149+
```php
150+
'api_secret' => [
151+
'type' => 'password',
152+
'label' => __( 'API secret', 'my-plugin' ),
153+
'encrypted' => true,
154+
],
155+
```
156+
157+
Stored encrypted, refused REST exposure, and decrypted on the way back out through `get_setting_field_value()`.
158+
159+
## Constants
160+
161+
Any value can be overridden by a constant, which is how a secret stays out of the database on a production install.
162+
163+
```php
164+
// In wp-config.php:
165+
define( 'MY_PLUGIN_API_KEY', 'sk-live-...' );
166+
```
167+
168+
`get_setting_field_value( 'my_plugin', 'api_key' )` returns the constant, and the field renders read-only with a note
169+
saying where the value came from.
170+
171+
## Reading values
172+
173+
| Function | Returns |
174+
| --- | --- |
175+
| `get_setting_field_value( $id, $key, $fallback = null )` | One value, with its default and any constant applied. |
176+
| `get_all_setting_values( $id )` | Everything, keyed by field. |
177+
| `is_setting_on( $id, $key )` | Whether a toggle or checkbox is on. |
178+
| `is_setting_enabled( $id, $key, $option )` | Whether an option is among a multiple field's values. |
179+
| `get_setting_field_list( $id, $key )` | A list field's values as an array. |
180+
| `get_setting_field_ids( $id, $key )` | A relational field's ids, as integers. |
181+
| `get_setting_field_page_url( $id, $key )` | The permalink of a page a field points at. |
182+
| `is_setting_field_page( $id, $key )` | Whether the current request is that page. |
183+
| `update_setting_field_value( $id, $key, $value )` | Write one, sanitized by its own type. |
184+
| `delete_setting_field_value( $id, $key )` | Remove one, so it falls back to its default. |
185+
186+
Email and licence fields have their own: `get_setting_fields_email()`, `is_setting_fields_email_enabled()`,
187+
`get_setting_field_license_status()`, `is_setting_field_license_active()`.
188+
189+
## Custom sanitization
190+
191+
A field's type sanitizes it. Supply a callback to replace that entirely:
192+
193+
```php
194+
'slug' => [
195+
'type' => 'text',
196+
'label' => __( 'Slug', 'my-plugin' ),
197+
'sanitize_callback' => fn( $value ) => sanitize_title( $value ),
198+
],
199+
```
200+
201+
The callback receives the raw value, not one the type has already cleaned.
41202

42203
## License
43204

44-
GPL-2.0-or-later
205+
GPL-2.0-or-later

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070
"lint": "phpcs",
7171
"format": "phpcbf --standard=phpcs-format.xml.dist",
7272
"format:check": "phpcs --standard=phpcs-format.xml.dist",
73-
"docs:verify": "php vendor/arraypress/wp-field-kit/bin/verify-docs.php --calls=register_setting_fields,register_settings README.md $(find docs -name '*.md')"
73+
"docs:verify": "php vendor/arraypress/wp-field-kit/bin/verify-docs.php --calls=register_setting_fields,register_settings README.md"
7474
},
7575
"repositories": [
7676
{

‎docs/.nojekyll‎

Whitespace-only changes.

‎docs/_sidebar.md‎

Lines changed: 0 additions & 56 deletions
This file was deleted.

0 commit comments

Comments
 (0)