JPKCom Gutenberg Image Block Alt-Attribute

API Documentation

Table of Contents

Namespaces

JPKComGutenbergImgAltGitUpdate

Constants

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_CATEGORY  : mixed = 'jpkcom-media'
Ability category.
JPKCOM_GUTENBERG_IMG_ALT_ABILITY_INPUT_KEYS  : mixed = ['jpkcom-gutenberg-img-alt/list-images-missing-...
Top-level input keys the ability declares.
JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PAGE_MAX  : mixed = \intdiv(num1: \PHP_INT_MAX, num2: \max(1, \JPKC...
Highest page number accepted.
JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_DEFAULT  : mixed = 20
Default page size.
JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_MAX  : mixed = 100
Largest page size honoured.
JPKCOM_GUTENBERG_IMG_ALT_VERSION  : mixed = '1.1.0'

Functions

jpkcom_gutenberg_img_alt_abilities_enabled()  : bool
Decide whether the ability should be registered at all.
jpkcom_gutenberg_img_alt_ability_log()  : void
Write a debug line, and only with WP_DEBUG.
jpkcom_gutenberg_img_alt_ability_error()  : WP_Error
Build a WP_Error carrying an HTTP status.
jpkcom_gutenberg_img_alt_ability_boundary()  : array<string, mixed>|WP_Error
Turn a Throwable out of the callback into a WP_Error.
jpkcom_gutenberg_img_alt_ability_capability()  : bool
Check the capability required to run the ability.
jpkcom_gutenberg_img_alt_ability_meta()  : array<string, mixed>
Build the meta array for the ability.
jpkcom_gutenberg_img_alt_ability_normalise_input()  : array<string, mixed>|null
Bring the value core hands the callback into array form.
jpkcom_gutenberg_img_alt_ability_validate_input_keys()  : true|WP_Error
Refuse a top-level input key the ability does not declare.
jpkcom_gutenberg_img_alt_would_inject()  : bool
Would this plugin's filter inject an alt attribute for this stored value?
jpkcom_gutenberg_img_alt_ability_reason()  : string
Name why the filter would inject nothing, so a fixer knows what is there.
jpkcom_gutenberg_img_alt_ability_permission()  : bool
Permission callback.
jpkcom_gutenberg_img_alt_ability_list_inner()  : array<string, mixed>|WP_Error
List the image attachments the filter would find nothing to inject for.
jpkcom_gutenberg_img_alt_ability_list()  : array<string, mixed>|WP_Error
Execute callback.
jpkcom_gutenberg_img_alt_get_ability_definitions()  : array<string, array<string, mixed>>
Build the registration arguments.
jpkcom_gutenberg_img_alt_register_ability_category()  : void
Register the category, unless something already did.
jpkcom_gutenberg_img_alt_register_abilities()  : void
Register the ability.
jpkcom_gutenberg_img_alt_replace_alt_attribute()  : string

Constants

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_CATEGORY

Ability category.

public mixed JPKCOM_GUTENBERG_IMG_ALT_ABILITY_CATEGORY = 'jpkcom-media'

NOT the jpkcom-content category the three content plugins share: this reports an editorial gap in the media library, not published content, and it is gated differently. Categories are global and first-wins, so registration goes through wp_has_ability_category() either way.

Tags
since
1.1.0

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_INPUT_KEYS

Top-level input keys the ability declares.

public mixed JPKCOM_GUTENBERG_IMG_ALT_ABILITY_INPUT_KEYS = ['jpkcom-gutenberg-img-alt/list-images-missing-alt' => ['page', 'per_page']]

Cross-checked against the registered schema by tests/test-abilities.php. additionalProperties is deliberately not declared on a schema that carries properties: validate_input() runs before the execute callback and would preempt the guard, replacing a message naming the accepted keys with core's "not a valid property of the object".

Tags
since
1.1.0

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PAGE_MAX

Highest page number accepted.

public mixed JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PAGE_MAX = \intdiv(num1: \PHP_INT_MAX, num2: \max(1, \JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_MAX))

Derived rather than picked: the offset is a plain integer multiplication, and past PHP_INT_MAX it becomes a float that collapses to 0 - handing back page one's rows labelled as a page far beyond the last.

Tags
since
1.1.0

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_DEFAULT

Default page size.

public mixed JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_DEFAULT = 20
Tags
since
1.1.0

JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_MAX

Largest page size honoured.

public mixed JPKCOM_GUTENBERG_IMG_ALT_ABILITY_PER_PAGE_MAX = 100
Tags
since
1.1.0

Functions

jpkcom_gutenberg_img_alt_abilities_enabled()

Decide whether the ability should be registered at all.

jpkcom_gutenberg_img_alt_abilities_enabled() : bool
Tags
since
1.1.0
Return values
bool —

True when registration should proceed.

jpkcom_gutenberg_img_alt_ability_log()

Write a debug line, and only with WP_DEBUG.

jpkcom_gutenberg_img_alt_ability_log(string $message) : void
Parameters
$message : string

Message.

Tags
since
1.1.0

jpkcom_gutenberg_img_alt_ability_error()

Build a WP_Error carrying an HTTP status.

jpkcom_gutenberg_img_alt_ability_error(string $code, string $message[, int $status = 400 ]) : WP_Error

Without data['status'] rest_ensure_response() defaults to 500, and a 5xx tells an agent "transient fault, retry unchanged" - the opposite of what a caller mistake needs to hear.

Parameters
$code : string

Error code.

$message : string

Message.

$status : int = 400

HTTP status.

Tags
since
1.1.0
Return values
WP_Error —

Error.

jpkcom_gutenberg_img_alt_ability_boundary()

Turn a Throwable out of the callback into a WP_Error.

jpkcom_gutenberg_img_alt_ability_boundary(callable $body, string $ability) : array<string, mixed>|WP_Error
Parameters
$body : callable

Callback.

$ability : string

Ability name.

Tags
since
1.1.0
Return values
array<string, mixed>|WP_Error —

Result or error.

jpkcom_gutenberg_img_alt_ability_capability()

Check the capability required to run the ability.

jpkcom_gutenberg_img_alt_ability_capability(string $ability) : bool

upload_files, NOT read like the sibling content plugins. Those publish content the site already shows to visitors; this enumerates the media library, where file names and unattached uploads are editorial internals. The capability that means "works with media" is the honest gate, and it excludes subscribers.

Parameters
$ability : string

Ability name.

Tags
since
1.1.0
Return values
bool —

True when the current user may run it.

jpkcom_gutenberg_img_alt_ability_meta()

Build the meta array for the ability.

jpkcom_gutenberg_img_alt_ability_meta(string $ability) : array<string, mixed>

All three annotations explicit: they default to null and the REST run controller derives the HTTP verb from them, so without readonly the run route would be POST-only.

Parameters
$ability : string

Ability name.

Tags
since
1.1.0
Return values
array<string, mixed> —

Meta array.

jpkcom_gutenberg_img_alt_ability_normalise_input()

Bring the value core hands the callback into array form.

jpkcom_gutenberg_img_alt_ability_normalise_input(mixed $input) : array<string, mixed>|null

normalize_input() substitutes the schema's top-level default when the input is exactly null, and that default is a stdClass - so the callback receives an object and must read it. A callback that only accepts an array answers 400 to the most obvious call it has.

Parameters
$input : mixed

Raw input.

Tags
since
1.1.0
Return values
array<string, mixed>|null —

Array form, or null when unusable.

jpkcom_gutenberg_img_alt_ability_validate_input_keys()

Refuse a top-level input key the ability does not declare.

jpkcom_gutenberg_img_alt_ability_validate_input_keys(array<string, mixed> $input, array<string|int, string> $allowed) : true|WP_Error
Parameters
$input : array<string, mixed>

Raw input.

$allowed : array<string|int, string>

Declared keys.

Tags
since
1.1.0
Return values
true|WP_Error —

True when every key is declared.

jpkcom_gutenberg_img_alt_would_inject()

Would this plugin's filter inject an alt attribute for this stored value?

jpkcom_gutenberg_img_alt_would_inject(mixed $stored) : bool

THE load-bearing function of this file, and deliberately not a paraphrase of the rule. The filter gates on ! empty( $alt ) and the replacer then returns the block unchanged when '' === trim( $alt ). Two consequences follow that a reasonable-looking check would get wrong:

  • An alt of the single character "0" is EMPTY to PHP, so nothing is injected. A check for $alt !== '' would call that image supplied.
  • An alt of only spaces passes ! empty() but is stopped by the trim in the replacer. A check that mirrored only the first gate would call that image supplied too.

Reporting an image as fine when the mechanism has nothing to inject for it is the one answer this ability must never give, because it is the answer that stops someone looking.

Parameters
$stored : mixed

Raw stored alt value.

Tags
since
1.1.0
Return values
bool —

True when the filter would inject.

jpkcom_gutenberg_img_alt_ability_reason()

Name why the filter would inject nothing, so a fixer knows what is there.

jpkcom_gutenberg_img_alt_ability_reason(mixed $stored, bool $row_found) : string
Parameters
$stored : mixed

Raw stored value.

$row_found : bool

Whether a meta row exists at all.

Tags
since
1.1.0
Return values
string —

One of no_row, empty, zero, whitespace_only.

jpkcom_gutenberg_img_alt_ability_permission()

Permission callback.

jpkcom_gutenberg_img_alt_ability_permission([mixed $input = null ]) : bool
Parameters
$input : mixed = null

Validated input, unused.

Tags
since
1.1.0
Return values
bool —

True when the current user may run the ability.

jpkcom_gutenberg_img_alt_ability_list_inner()

List the image attachments the filter would find nothing to inject for.

jpkcom_gutenberg_img_alt_ability_list_inner([mixed $input = null ]) : array<string, mixed>|WP_Error

Queried with one statement rather than by walking the library in PHP: the predicate needs TRIM(), which no meta_query comparison expresses, and a page-by-page PHP filter would make total a guess.

Parameters
$input : mixed = null

Ability input.

Tags
since
1.1.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_gutenberg_img_alt_ability_list()

Execute callback.

jpkcom_gutenberg_img_alt_ability_list([mixed $input = null ]) : array<string, mixed>|WP_Error
Parameters
$input : mixed = null

Ability input.

Tags
since
1.1.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_gutenberg_img_alt_get_ability_definitions()

Build the registration arguments.

jpkcom_gutenberg_img_alt_get_ability_definitions() : array<string, array<string, mixed>>

Reads no WordPress state and touches no registry, which is what lets the CI harness assert the shape without a WordPress installation.

Tags
since
1.1.0
Return values
array<string, array<string, mixed>> —

Ability name => registration args.

jpkcom_gutenberg_img_alt_register_ability_category()

Register the category, unless something already did.

jpkcom_gutenberg_img_alt_register_ability_category() : void
Tags
since
1.1.0

jpkcom_gutenberg_img_alt_register_abilities()

Register the ability.

jpkcom_gutenberg_img_alt_register_abilities() : void

wp_register_ability() returns null on EVERY failure path and reports only through _doing_it_wrong(), which is silent in production - and so is the debug log without WP_DEBUG.

Tags
since
1.1.0

jpkcom_gutenberg_img_alt_replace_alt_attribute()

jpkcom_gutenberg_img_alt_replace_alt_attribute(string $block_content, string $alt) : string
Parameters
$block_content : string
$alt : string
Return values
string
On this page

Search results