settings-store.php
Settings store
Reads, writes and validates the single option this plugin owns. Every other module goes through here, so validation cannot be bypassed by adding a caller.
Tags
Table of Contents
Functions
- jpkcom_allow_blocks_option_name() : string
- Name of the option holding all settings.
- jpkcom_allow_blocks_is_valid_block_name() : bool
- Whether a string is a syntactically valid block name.
-
jpkcom_allow_blocks_empty_settings()
: array{schema: int, updated: string, roles: array
- The empty settings structure.
- jpkcom_allow_blocks_sanitize_settings() : array<string|int, mixed>
- Coerce any input into a valid settings structure.
- jpkcom_allow_blocks_count_rejected() : int
- Count how many entries a sanitised import or save would discard.
- jpkcom_allow_blocks_get_settings() : array<string|int, mixed>
- Read the validated settings.
- jpkcom_allow_blocks_save_settings() : bool
- Validate and store the settings.
- jpkcom_allow_blocks_blocked_for_roles() : array<string|int, string>
- Block names blocked for every one of the given roles.
Functions
jpkcom_allow_blocks_option_name()
Name of the option holding all settings.
jpkcom_allow_blocks_option_name() : string
Tags
Return values
string —Option name.
jpkcom_allow_blocks_is_valid_block_name()
Whether a string is a syntactically valid block name.
jpkcom_allow_blocks_is_valid_block_name(string $name) : bool
Follows the WordPress block name grammar: a lowercase namespace and name separated by exactly one slash.
Parameters
- $name : string
-
Candidate block name.
Tags
Return values
bool —True when the name may be stored.
jpkcom_allow_blocks_empty_settings()
The empty settings structure.
jpkcom_allow_blocks_empty_settings() : array{schema: int, updated: string, roles: array, labels: array}
Tags
Return values
array{schema: int, updated: string, roles: arrayjpkcom_allow_blocks_sanitize_settings()
Coerce any input into a valid settings structure.
jpkcom_allow_blocks_sanitize_settings(mixed $raw) : array<string|int, mixed>
Entries that fail validation are dropped rather than stored. Never throws, so a corrupt option can only ever mean "nothing is blocked".
Parameters
- $raw : mixed
-
Value from the database, an import file or a form.
Tags
Return values
array<string|int, mixed> —The validated structure.
jpkcom_allow_blocks_count_rejected()
Count how many entries a sanitised import or save would discard.
jpkcom_allow_blocks_count_rejected(mixed $raw) : int
Walks the same validation rules as jpkcom_allow_blocks_sanitize_settings()
without mutating anything, so a caller can tell the user "N entries were
invalid and will be ignored" instead of silently dropping them. A
companion function rather than a change to the sanitiser's signature,
so every existing caller of jpkcom_allow_blocks_sanitize_settings()
keeps working unchanged.
Counts, added together:
- one for every
rolesentry whose value is not an array (the entry cannot be walked further, so it counts as a single rejection), - one for every role whose slug does not survive
sanitize_key()unchanged (the whole role is dropped), - one for every block name within an otherwise valid role that is not a string or fails the block-name grammar,
- one for every
labelsentry whose key is not a valid block name or whose value is not a string.
Parameters
- $raw : mixed
-
Value from an import file or a form, same input the sanitiser would receive.
Tags
Return values
int —Number of entries the sanitiser would discard.
jpkcom_allow_blocks_get_settings()
Read the validated settings.
jpkcom_allow_blocks_get_settings() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —The validated structure.
jpkcom_allow_blocks_save_settings()
Validate and store the settings.
jpkcom_allow_blocks_save_settings(array<string|int, mixed> $settings) : bool
Autoload is off: the option is only read in the admin area, so the front end should not carry it on every request.
Parameters
- $settings : array<string|int, mixed>
-
Structure to store.
Tags
Return values
bool —True when the option was written.
jpkcom_allow_blocks_blocked_for_roles()
Block names blocked for every one of the given roles.
jpkcom_allow_blocks_blocked_for_roles(array<string|int, string> $role_slugs[, array<string|int, mixed>|null $settings = null ]) : array<string|int, string>
The intersection, not the union: a block is blocked only when all of the user's roles block it. This mirrors WordPress capability semantics, where holding more roles never means holding fewer rights. A role with no entry blocks nothing, so it empties the intersection.
Parameters
- $role_slugs : array<string|int, string>
-
Roles of the user.
- $settings : array<string|int, mixed>|null = null
-
Settings to use, or null to read them.
Tags
Return values
array<string|int, string> —Blocked block names, re-indexed.