Ability category shared with the sibling JPKCom content plugins.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_CATEGORY
= 'jpkcom-content'
Categories are global and registration is FIRST-WINS: the second plugin to register the same slug gets null back and _doing_it_wrong() fires. Which plugin wins depends on load order, so registration goes through wp_has_ability_category() rather than assuming.
Top-level input keys each ability declares.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_INPUT_KEYS
= ['jpkcom-acf-references/list-filters' => [], 'jpkcom-acf-references/query-references' => ['type', 'filter_1', 'filter_2', 'customer', 'location', 'search', 'page', 'per_page', 'order'], 'jpkcom-acf-references/get-reference' => ['id']]
One list, one place, and checked against the registered input schemas by
tests/test-abilities.php. Neither schema that carries properties declares
additionalProperties, on purpose: core's validate_input() runs BEFORE the
execute callback, so declaring it would preempt the guard below and replace
a message naming the accepted keys with core's "not a valid property of the
object". Self-correction in one turn is the point of these messages.
list-filters is the exception and must stay one: it declares no properties at all, so additionalProperties => false is the only thing that can refuse a key there.
Largest number of values accepted in one filter axis.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_MAX_VALUES
= 20
Highest page number the query ability will ask the database for.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_PAGE_MAX
= \intdiv(num1: \PHP_INT_MAX, num2: \max(1, \JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_MAX))
Derived, not picked. WP_Query computes its LIMIT offset as absint( ( $page - 1 ) * $posts_per_page ), a plain integer multiplication: past PHP_INT_MAX it becomes a float and absint() casts rather than throws, collapsing the offset to 0 — so page one's records come back labelled as a page far beyond total_pages.
max() guards the divisor: a site may redefine PER_PAGE_MAX, and intdiv() by zero is a fatal at file load.
Default page size for the query ability.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_DEFAULT
= 10
NOT the shortcode's default. That one is -1, which means "all" there and would mean an unbounded response here.
Largest page size the query ability will honour.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_MAX
= 50
Longest search term, in BYTES, that WordPress will actually apply.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_SEARCH_MAX_BYTES
= 1600
WP_Query::parse_query() empties s when strlen() exceeds this — an anti-DoS
guard that runs INSIDE the query, after every check on the arguments has
passed. The result is not an error: the search simply stops narrowing and
every reference matches, while the response still echoes the term back as
applied.
strlen(), so the unit is BYTES. Counting characters would hand a 900- character accented term to a guard that counts bytes and reproduce the defect for non-ASCII callers only.
Largest number of entries list-filters reports per axis.
public
mixed
JPKCOM_ACFREFERENCES_ABILITY_VOCABULARY_LIMIT
= 500
public
mixed
JPKCOM_ACFREFERENCES_BASENAME
= \plugin_basename(__FILE__)
public
mixed
JPKCOM_ACFREFERENCES_PLUGIN_PATH
= \plugin_dir_path(__FILE__)
public
mixed
JPKCOM_ACFREFERENCES_PLUGIN_URL
= \plugin_dir_url(__FILE__)
public
mixed
JPKCOM_ACFREFERENCES_VERSION
= '1.2.1'
Decide whether the abilities should be registered at all.
jpkcom_acf_references_abilities_enabled() : bool
Requires Plugins only blocks activation; core does not stop a dependency
being deactivated while dependents are active. get_field() is therefore
checked rather than assumed.
True when registration should proceed.
Write a debug line, and only with WP_DEBUG.
jpkcom_acf_references_ability_log(string $message) : void
Message.
Build a WP_Error carrying an HTTP status.
jpkcom_acf_references_ability_error(string $code, string $message[, int $status = 400 ]) : WP_Error
The status is not decoration. The REST run controller returns the WP_Error verbatim and rest_ensure_response() defaults to 500 without data['status'] — and a 5xx tells an agent "transient fault, retry unchanged", which is the exact opposite of what a caller mistake needs to hear.
Error code.
Human-readable message.
HTTP status.
Error.
Turn a Throwable out of a callback into a WP_Error.
jpkcom_acf_references_ability_boundary(callable $body, string $ability) : array<string, mixed>|WP_Error
ACF throws while READING corrupt meta, so no check on the shape beforehand catches it. This rim does not catch everything: schema validation and the permission check both run before it.
Callback returning the ability result.
Ability name, for the log line.
Result or error.
Wrap an empty map so it encodes as {} rather than [].
jpkcom_acf_references_ability_json_object(array<string, mixed> $map) : array<string, mixed>|stdClass
PHP serialises an empty array as the JSON array [], and a client validating
against a schema declaring type: object rejects that. Only the empty case
is wrapped, so PHP callers keep array access where there is data.
Map.
Map, or an empty object.
Capability required to run an ability.
jpkcom_acf_references_ability_capability(string $ability) : bool
Defaults to read. Every query is hard-scoped to published references, so
this cannot expose drafts — but it is bulk machine-readable access, and a
site may want it narrower.
Ability name.
True when the current user may run it.
Build the meta array for an ability.
jpkcom_acf_references_ability_meta(string $ability) : array<string, mixed>
Three independent switches: show_in_rest (core REST), public (WP 7.1; inert passthrough before that), and mcp.public — not a core key at all, but the MCP Adapter's own gate for discovery AND execution.
All three annotations are set explicitly. They default to null, and the REST run controller derives the HTTP verb from them: readonly makes the run route GET-only and POST answers 405.
Ability name.
Meta array.
Refuse a top-level input key the ability does not declare.
jpkcom_acf_references_ability_validate_input_keys(array<string, mixed> $input, array<string|int, string> $allowed) : true|WP_Error
On EVERY ability, not a subset. A guard on some of them is a trap: a caller that learned the refusal on one assumes it everywhere, and the ability that silently accepts is the one it will trust. The sibling plugin shipped exactly that gap for a whole release.
Without this, an axis the ability does not declare is not applied and the answer is the complete unfiltered set behind an HTTP 200 — a caller has to notice an absence to notice the failure.
Raw ability input.
Declared keys.
True when every key is declared.
Bring the value core hands the callback into array form.
jpkcom_acf_references_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. This exact defect shipped twice in the sibling plugins.
Raw input.
Array form, or null when unusable.
Normalise a filter axis into a bounded list of term slugs.
jpkcom_acf_references_ability_slug_list(mixed $value) : array<string|int, string>
Raw value.
Slugs, deduplicated and capped.
Normalise a filter axis into a bounded list of positive post IDs.
jpkcom_acf_references_ability_id_list(mixed $value) : array<string|int, int>
Raw value.
IDs, deduplicated and capped.
Refuse a search term core would silently discard.
jpkcom_acf_references_ability_validate_search(string $search) : true|WP_Error
Search term.
True when the term is usable.
Read one taxonomy's terms as the filter vocabulary.
jpkcom_acf_references_ability_vocabulary(string $taxonomy) : array{terms: array>, truncated: bool}
hide_empty is false: a term with no reference today is still a valid filter value, and reporting only used terms would make the vocabulary shift under a caller that cached it.
Taxonomy slug.
Vocabulary.
Read the customers or locations a caller may filter by.
jpkcom_acf_references_ability_related_vocabulary(string $post_type) : array{items: array>, truncated: bool}
Published only, and projected to id/title. Never a WP_Post: ACF resolves these relations with post_status => 'any' elsewhere, and WP_Post exposes post_password as a public property.
Post type.
Vocabulary.
Count posts matching a set of query arguments, cheaply.
jpkcom_acf_references_ability_count_query(array<string, mixed> $args) : int
Query arguments.
Count.
Report how many published references the listing rule excludes, and why.
jpkcom_acf_references_ability_visibility_counts() : array<string, int>
Both numbers are DIFFERENCES, derived from the rule itself. Restating what "expired" means as its own meta_query is the defect this shape exists to prevent: the rule's expiry clause is an OR group of three branches, and negating only the first is not its complement — MariaDB casts '' to '0000-00-00', so every reference whose date had been saved and cleared would be counted as expired in the same response that lists it.
hidden_expired = ( published + featured row ) - listed hidden_missing_featured = published - ( published + featured row )
Counts.
The reference archive URL, or an empty string when there is none.
jpkcom_acf_references_ability_archive_url() : string
Archive URL.
Permission callback for list-filters.
jpkcom_acf_references_ability_permission_list_filters([mixed $input = null ]) : bool
Validated input, unused.
True when the current user may run it.
Permission callback for query-references.
jpkcom_acf_references_ability_permission_query_references([mixed $input = null ]) : bool
Validated input, unused.
True when the current user may run it.
Permission callback for get-reference.
jpkcom_acf_references_ability_permission_get_reference([mixed $input = null ]) : bool
Validated input, unused.
True when the current user may run it.
Report the values a caller may filter references by.
jpkcom_acf_references_ability_list_filters_inner([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Run a filtered, paginated query over publicly listed references.
jpkcom_acf_references_ability_query_references_inner([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Return one reference by ID.
jpkcom_acf_references_ability_get_reference_inner([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Execute callback for jpkcom-acf-references/list-filters.
jpkcom_acf_references_ability_list_filters([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Execute callback for jpkcom-acf-references/query-references.
jpkcom_acf_references_ability_query_references([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Execute callback for jpkcom-acf-references/get-reference.
jpkcom_acf_references_ability_get_reference([mixed $input = null ]) : array<string, mixed>|WP_Error
Ability input.
Result.
Build the registration arguments for every ability this plugin provides.
jpkcom_acf_references_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 of these arrays without a WordPress installation. Not free of side effects though: __() and the meta filter each fire apply_filters(), so third-party callbacks run whenever this is called.
Ability name => registration args.
Register the shared category, unless a sibling plugin already did.
jpkcom_acf_references_register_ability_category() : void
Categories are global and first-wins. Without the check all abilities still register - the category exists either way - but _doing_it_wrong() fires, and which plugin wins depends on load order.
Register every ability this plugin provides.
jpkcom_acf_references_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. The return value is checked, but do not expect a registration failure to announce itself on a customer site.
Render disable archive checkbox field
jpkcom_acf_references_disable_archive_field() : void
Render archive redirect URL field
jpkcom_acf_references_redirect_url_field() : void
Render Shortcodes admin page
jpkcom_acf_references_shortcodes_page() : void
Render Options admin page
jpkcom_acf_references_options_page() : void
Output Bootstrap 5 breadcrumb navigation
jpkcom_acf_references_breadcrumb() : void
Generates breadcrumb navigation for:
Includes proper ARIA labels and semantic HTML5 markup.
Outputs HTML directly.
Renders all ACF fields of a post with Bootstrap 5 markup and smart icons
jpkcom_render_acf_fields([string $post_type = '' ]) : void
Automatically detects field types and renders them with appropriate styling:
Optional. Post type for field group query. Default empty (uses current post type).
Get ACF field label by field key or field name
acf_get_field_label(string $field_key_or_name) : string
Attempts to retrieve the field label from ACF. If not found, returns a formatted fallback based on the field name/key.
Field key (e.g., 'field_abc123') or field name (e.g., 'job_title').
Field label or formatted fallback string.
Get ACF field label with enhanced search capabilities
jpkcom_get_acf_field_label(string $field_name_or_key[, string $post_type = '' ]) : string
Searches for field labels in this order:
Field name (e.g., 'job_title') or field key (e.g., 'field_abc123').
Optional. Post type for context-specific field group search. Default empty.
Field label or formatted fallback string.
Convert timestamp to human-readable relative date string
jpkcom_human_readable_relative_date(int $timestamp) : string
Converts Unix timestamps into relative date strings like:
All strings are translatable via the 'jpkcom-acf-references' text domain.
Unix timestamp to convert.
Translated relative date string.
Register custom image sizes for reference posts
jpkcom_acf_references_media_size() : void
Registers six image sizes:
Add custom image sizes to media library size selector
jpkcom_acf_references_image_sizes_to_selector(array<string|int, string> $sizes) : array<string|int, string>
Makes custom image sizes available in the WordPress media library dropdown when inserting images into posts.
Existing image size options.
Modified array with custom sizes added.
Output Bootstrap 5 pagination navigation
jpkcom_acf_references_pagination([string|int $pages = '' ][, int $range = 2 ]) : void
Generates numbered pagination with first/last and prev/next controls. Includes proper ARIA labels and accessible markup.
Features:
Optional. Total number of pages. Default empty (auto-detect from query).
Optional. Number of page links to show on either side of current page. Default 2.
Outputs HTML directly.
Build the WP_Query arguments that define a publicly listed reference.
jpkcom_acf_references_build_reference_query_args([array<string, mixed> $args = [] ]) : array<string, mixed>
Extracted verbatim from the list shortcode, which was its only home. Three parts carry weight and none of them may be simplified:
reference_featured EXISTS — the site treats a reference without that
meta row as not listed at all. The row's VALUE is irrelevant; a stored 0
is listed, a missing row is not, and get_field() cannot tell those apart.
The expiry OR group has THREE branches: at or after today, no row, and the empty string. The third is the ordinary case, not an edge case — ACF writes '' when a date is cleared rather than deleting the row, and MariaDB casts '' to '0000-00-00', which is less than any real date. A negation of only the first branch is not the complement of this group.
meta_key is set for the ordering, and its own postmeta.meta_key
condition lands in the WHERE clause. So a reference with no featured row
is excluded TWICE, independently. Removing either one changes nothing,
which is why the number of references carrying the row cannot be read off
this query and needs one of its own.
current_time( 'Y-m-d' ) and not date(): WordPress sets the PHP timezone
to UTC in wp-settings.php, so date() returns the UTC date and an expired
reference would stay visible for the length of the site's offset past local
midnight.
Arguments merged over the base rule.
WP_Query arguments.
Normalise a stored ACF date into ISO 8601, or null when it cannot be read.
jpkcom_acf_references_normalise_date(mixed $raw) : string|null
Never date( 'Y-m-d', strtotime( $x ) ): under strict_types a false from
strtotime() makes date() throw a TypeError. The round-trip check is
load-bearing rather than decorative — without it '20251340' becomes
2026-02-09 and '20259999' becomes 2033-06-07, both silently.
Wrapped in try/catch because a NUL byte in the stored value makes createFromFormat() throw a ValueError, and MySQL longtext stores NUL.
Stored value.
Y-m-d, or null when the value is unusable.
Reduce a stored value to plain text.
jpkcom_acf_references_plain_text(mixed $value) : string
Stored value.
Plain text, empty when the value is not a string.
Project a post-object field into id/title pairs.
jpkcom_acf_references_normalise_related(mixed $value) : array<int, array<string, mixed>>
Never emits a WP_Post. ACF resolves post_object fields through acf_get_posts() with post_status => 'any', so drafts and private customers genuinely arrive here — and WP_Post implements no JsonSerializable while exposing post_password, post_content and post_status as public properties. A reference linked to a password-protected customer would otherwise hand a subscriber that password in plain text.
absint() before get_post(): get_post( 0 ) returns the GLOBAL post, and absint() maps false, '', null and 'abc' all to 0. ACF returns false for an unassigned post_object, and both relation fields here allow null — without this guard a reference with no customer projects itself as its own customer.
Stored value.
Related records.
Resolve an attachment field to a URL, or null.
jpkcom_acf_references_attachment_url(mixed $value) : string|null
Accepts the three shapes ACF returns depending on return_format — id, url string, or array — and refuses anything that is not an attachment. The post-type check matters: an id pointing at a normal post would otherwise produce a permalink where the caller expects an image.
Stored value.
Attachment URL, or null.
Project a gallery field into url/alt records.
jpkcom_acf_references_normalise_gallery(mixed $value) : array<int, array<string, mixed>>
Emits only what a caller can use and nothing that identifies the attachment post itself. The alt text is read from the attachment meta rather than from ACF's formatted array, so this does not depend on the field's return_format.
Stored value.
Gallery images.
Read a reference's terms in one taxonomy as slug/name records.
jpkcom_acf_references_normalise_terms(int $post_id, string $taxonomy) : array<int, array<string, string>>
Reads the term relationships rather than the ACF meta, for the same reason the list shortcode does: the relationships are indexed, and the two stores can drift (import, direct DB write, a WPML duplication that never ran ACF's save routine). tools/check-term-sync.php is what detects that drift.
Reference ID.
Taxonomy slug.
Assigned terms.
Project one reference into plain data, or [] when it cannot be read.
jpkcom_acf_references_get_reference_data(int $post_id[, bool $full = false ]) : array<string, mixed>
This function gates, because nothing else does. The existing readers are safe only because the shortcode hands them posts a post_type/post_status query already filtered; this one takes a bare int and inherits none of that, and the abilities above it answer to any subscriber. It therefore refuses a non-reference post type, any status but publish, a non-empty post_password and a non-positive id.
"Does not exist" and "cannot be read" return the same empty array on purpose, so the ability above cannot be used to probe which IDs exist.
$full adds the detail block. It is emitted ONLY for a reference whose
detail page would actually render for an anonymous visitor: an external
reference URL 307s every visitor away (redirects.php:59-77) and an expired
reference 307s to the archive (redirects.php:149-206). For those the
address, the gallery and the description have no public render path at all,
so publishing them here would publish what the site never showed.
Reference ID.
Whether to include the detail block.
Reference data, or [] when unreadable.
jpkcom_acf_references_locate_template(string $template_name) : string|false
Locate template file with override support
jpkcom_acf_references_locate_template(string $template_name) : string|false
Searches for template files in this priority order:
Template filename (e.g., 'single-reference.php' or 'partials/reference/customer.php').
Full path to template file if found, false otherwise.
Template loader for singular and archive templates
jpkcom_acf_references_template_include(string $template) : string
Intercepts WordPress template_include filter and loads custom templates for reference, reference_customer, and reference_location post types (single and archive views).
Default template path from WordPress.
Template path to use (plugin template or default).
Load partial templates with full override support
jpkcom_acf_references_get_template_part(string $slug[, string $name = '' ][, array<string|int, mixed> $args = [] ]) : void
Similar to WordPress get_template_part() but uses the plugin's template hierarchy system. Useful for loading reusable template partials.
Example usage: jpkcom_acf_references_get_template_part('partials/reference/customer'); jpkcom_acf_references_get_template_part('partials/reference/customer', 'detailed'); jpkcom_acf_references_get_template_part('partials/reference/modal', '', ['data' => $data]);
Template slug (e.g., 'partials/reference/customer').
Optional. Template name/variation (e.g., 'alternative'). Default empty.
Optional. Array of variables to pass to the template. Default empty.
Load plugin text domain for translations
jpkcom_acfreferences_textdomain() : void
Loads translation files from the /languages directory.
Locate file with override support
jpkcom_acfreferences_locate_file(string $filename) : string|null
Searches for a file in multiple locations with priority:
The filename to locate (without path).
Full path to the file if found, null otherwise.