JPKCom ACF References

References

Table of Contents

Constants

JPKCOM_ACFREFERENCES_ABILITY_CATEGORY  : mixed = 'jpkcom-content'
Ability category shared with the sibling JPKCom content plugins.
JPKCOM_ACFREFERENCES_ABILITY_INPUT_KEYS  : mixed = ['jpkcom-acf-references/list-filters' => [], 'j...
Top-level input keys each ability declares.
JPKCOM_ACFREFERENCES_ABILITY_MAX_VALUES  : mixed = 20
Largest number of values accepted in one filter axis.
JPKCOM_ACFREFERENCES_ABILITY_PAGE_MAX  : mixed = \intdiv(num1: \PHP_INT_MAX, num2: \max(1, \JPKC...
Highest page number the query ability will ask the database for.
JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_DEFAULT  : mixed = 10
Default page size for the query ability.
JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_MAX  : mixed = 50
Largest page size the query ability will honour.
JPKCOM_ACFREFERENCES_ABILITY_SEARCH_MAX_BYTES  : mixed = 1600
Longest search term, in BYTES, that WordPress will actually apply.
JPKCOM_ACFREFERENCES_ABILITY_VOCABULARY_LIMIT  : mixed = 500
Largest number of entries list-filters reports per axis.

Functions

jpkcom_acf_references_abilities_enabled()  : bool
Decide whether the abilities should be registered at all.
jpkcom_acf_references_ability_log()  : void
Write a debug line, and only with WP_DEBUG.
jpkcom_acf_references_ability_error()  : WP_Error
Build a WP_Error carrying an HTTP status.
jpkcom_acf_references_ability_boundary()  : array<string, mixed>|WP_Error
Turn a Throwable out of a callback into a WP_Error.
jpkcom_acf_references_ability_json_object()  : array<string, mixed>|stdClass
Wrap an empty map so it encodes as {} rather than [].
jpkcom_acf_references_ability_capability()  : bool
Capability required to run an ability.
jpkcom_acf_references_ability_meta()  : array<string, mixed>
Build the meta array for an ability.
jpkcom_acf_references_ability_validate_input_keys()  : true|WP_Error
Refuse a top-level input key the ability does not declare.
jpkcom_acf_references_ability_normalise_input()  : array<string, mixed>|null
Bring the value core hands the callback into array form.
jpkcom_acf_references_ability_slug_list()  : array<string|int, string>
Normalise a filter axis into a bounded list of term slugs.
jpkcom_acf_references_ability_id_list()  : array<string|int, int>
Normalise a filter axis into a bounded list of positive post IDs.
jpkcom_acf_references_ability_validate_search()  : true|WP_Error
Refuse a search term core would silently discard.
jpkcom_acf_references_ability_vocabulary()  : array{terms: array>, truncated: bool}
Read one taxonomy's terms as the filter vocabulary.
jpkcom_acf_references_ability_related_vocabulary()  : array{items: array>, truncated: bool}
Read the customers or locations a caller may filter by.
jpkcom_acf_references_ability_count_query()  : int
Count posts matching a set of query arguments, cheaply.
jpkcom_acf_references_ability_visibility_counts()  : array<string, int>
Report how many published references the listing rule excludes, and why.
jpkcom_acf_references_ability_archive_url()  : string
The reference archive URL, or an empty string when there is none.
jpkcom_acf_references_ability_permission_list_filters()  : bool
Permission callback for list-filters.
jpkcom_acf_references_ability_permission_query_references()  : bool
Permission callback for query-references.
jpkcom_acf_references_ability_permission_get_reference()  : bool
Permission callback for get-reference.
jpkcom_acf_references_ability_list_filters_inner()  : array<string, mixed>|WP_Error
Report the values a caller may filter references by.
jpkcom_acf_references_ability_query_references_inner()  : array<string, mixed>|WP_Error
Run a filtered, paginated query over publicly listed references.
jpkcom_acf_references_ability_get_reference_inner()  : array<string, mixed>|WP_Error
Return one reference by ID.
jpkcom_acf_references_ability_list_filters()  : array<string, mixed>|WP_Error
Execute callback for jpkcom-acf-references/list-filters.
jpkcom_acf_references_ability_query_references()  : array<string, mixed>|WP_Error
Execute callback for jpkcom-acf-references/query-references.
jpkcom_acf_references_ability_get_reference()  : array<string, mixed>|WP_Error
Execute callback for jpkcom-acf-references/get-reference.
jpkcom_acf_references_get_ability_definitions()  : array<string, array<string, mixed>>
Build the registration arguments for every ability this plugin provides.
jpkcom_acf_references_register_ability_category()  : void
Register the shared category, unless a sibling plugin already did.
jpkcom_acf_references_register_abilities()  : void
Register every ability this plugin provides.
jpkcom_acf_references_disable_archive_field()  : void
Render disable archive checkbox field
jpkcom_acf_references_redirect_url_field()  : void
Render archive redirect URL field
jpkcom_acf_references_shortcodes_page()  : void
Render Shortcodes admin page
jpkcom_acf_references_options_page()  : void
Render Options admin page
jpkcom_acf_references_breadcrumb()  : void
Output Bootstrap 5 breadcrumb navigation
jpkcom_render_acf_fields()  : void
Renders all ACF fields of a post with Bootstrap 5 markup and smart icons
acf_get_field_label()  : string
Get ACF field label by field key or field name
jpkcom_get_acf_field_label()  : string
Get ACF field label with enhanced search capabilities
jpkcom_human_readable_relative_date()  : string
Convert timestamp to human-readable relative date string
jpkcom_acf_references_media_size()  : void
Register custom image sizes for reference posts
jpkcom_acf_references_image_sizes_to_selector()  : array<string|int, string>
Add custom image sizes to media library size selector
jpkcom_acf_references_pagination()  : void
Output Bootstrap 5 pagination navigation
jpkcom_acf_references_build_reference_query_args()  : array<string, mixed>
Build the WP_Query arguments that define a publicly listed reference.
jpkcom_acf_references_normalise_date()  : string|null
Normalise a stored ACF date into ISO 8601, or null when it cannot be read.
jpkcom_acf_references_plain_text()  : string
Reduce a stored value to plain text.
jpkcom_acf_references_normalise_related()  : array<int, array<string, mixed>>
Project a post-object field into id/title pairs.
jpkcom_acf_references_attachment_url()  : string|null
Resolve an attachment field to a URL, or null.
jpkcom_acf_references_normalise_gallery()  : array<int, array<string, mixed>>
Project a gallery field into url/alt records.
jpkcom_acf_references_normalise_terms()  : array<int, array<string, string>>
Read a reference's terms in one taxonomy as slug/name records.
jpkcom_acf_references_get_reference_data()  : array<string, mixed>
Project one reference into plain data, or [] when it cannot be read.
jpkcom_acf_references_locate_template()  : string|false
jpkcom_acf_references_locate_template()  : string|false
Locate template file with override support
jpkcom_acf_references_template_include()  : string
Template loader for singular and archive templates
jpkcom_acf_references_get_template_part()  : void
Load partial templates with full override support

Constants

JPKCOM_ACFREFERENCES_ABILITY_CATEGORY

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.

Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_INPUT_KEYS

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.

Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_MAX_VALUES

Largest number of values accepted in one filter axis.

public mixed JPKCOM_ACFREFERENCES_ABILITY_MAX_VALUES = 20
Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_PAGE_MAX

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.

Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_DEFAULT

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.

Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_MAX

Largest page size the query ability will honour.

public mixed JPKCOM_ACFREFERENCES_ABILITY_PER_PAGE_MAX = 50
Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_SEARCH_MAX_BYTES

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.

Tags
since
1.2.0

JPKCOM_ACFREFERENCES_ABILITY_VOCABULARY_LIMIT

Largest number of entries list-filters reports per axis.

public mixed JPKCOM_ACFREFERENCES_ABILITY_VOCABULARY_LIMIT = 500
Tags
since
1.2.0

Functions

jpkcom_acf_references_abilities_enabled()

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.

Tags
since
1.2.0
Return values
bool —

True when registration should proceed.

jpkcom_acf_references_ability_log()

Write a debug line, and only with WP_DEBUG.

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

Message.

Tags
since
1.2.0

jpkcom_acf_references_ability_error()

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.

Parameters
$code : string

Error code.

$message : string

Human-readable message.

$status : int = 400

HTTP status.

Tags
since
1.2.0
Return values
WP_Error —

Error.

jpkcom_acf_references_ability_boundary()

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.

Parameters
$body : callable

Callback returning the ability result.

$ability : string

Ability name, for the log line.

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

Result or error.

jpkcom_acf_references_ability_json_object()

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.

Parameters
$map : array<string, mixed>

Map.

Tags
since
1.2.0
Return values
array<string, mixed>|stdClass —

Map, or an empty object.

jpkcom_acf_references_ability_capability()

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.

Parameters
$ability : string

Ability name.

Tags
since
1.2.0
Return values
bool —

True when the current user may run it.

jpkcom_acf_references_ability_meta()

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.

Parameters
$ability : string

Ability name.

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

Meta array.

jpkcom_acf_references_ability_validate_input_keys()

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.

Parameters
$input : array<string, mixed>

Raw ability input.

$allowed : array<string|int, string>

Declared keys.

Tags
since
1.2.0
Return values
true|WP_Error —

True when every key is declared.

jpkcom_acf_references_ability_normalise_input()

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.

Parameters
$input : mixed

Raw input.

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

Array form, or null when unusable.

jpkcom_acf_references_ability_slug_list()

Normalise a filter axis into a bounded list of term slugs.

jpkcom_acf_references_ability_slug_list(mixed $value) : array<string|int, string>
Parameters
$value : mixed

Raw value.

Tags
since
1.2.0
Return values
array<string|int, string> —

Slugs, deduplicated and capped.

jpkcom_acf_references_ability_id_list()

Normalise a filter axis into a bounded list of positive post IDs.

jpkcom_acf_references_ability_id_list(mixed $value) : array<string|int, int>
Parameters
$value : mixed

Raw value.

Tags
since
1.2.0
Return values
array<string|int, int> —

IDs, deduplicated and capped.

jpkcom_acf_references_ability_validate_search()

Refuse a search term core would silently discard.

jpkcom_acf_references_ability_validate_search(string $search) : true|WP_Error
Parameters
$search : string

Search term.

Tags
since
1.2.0
Return values
true|WP_Error —

True when the term is usable.

jpkcom_acf_references_ability_vocabulary()

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.

Parameters
$taxonomy : string

Taxonomy slug.

Tags
since
1.2.0
Return values
array{terms: array>, truncated: bool} —

Vocabulary.

jpkcom_acf_references_ability_related_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.

Parameters
$post_type : string

Post type.

Tags
since
1.2.0
Return values
array{items: array>, truncated: bool} —

Vocabulary.

jpkcom_acf_references_ability_count_query()

Count posts matching a set of query arguments, cheaply.

jpkcom_acf_references_ability_count_query(array<string, mixed> $args) : int
Parameters
$args : array<string, mixed>

Query arguments.

Tags
since
1.2.0
Return values
int —

Count.

jpkcom_acf_references_ability_visibility_counts()

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 )

Tags
since
1.2.0
Return values
array<string, int> —

Counts.

jpkcom_acf_references_ability_archive_url()

The reference archive URL, or an empty string when there is none.

jpkcom_acf_references_ability_archive_url() : string
Tags
since
1.2.0
Return values
string —

Archive URL.

jpkcom_acf_references_ability_permission_list_filters()

Permission callback for list-filters.

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

Validated input, unused.

Tags
since
1.2.0
Return values
bool —

True when the current user may run it.

jpkcom_acf_references_ability_permission_query_references()

Permission callback for query-references.

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

Validated input, unused.

Tags
since
1.2.0
Return values
bool —

True when the current user may run it.

jpkcom_acf_references_ability_permission_get_reference()

Permission callback for get-reference.

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

Validated input, unused.

Tags
since
1.2.0
Return values
bool —

True when the current user may run it.

jpkcom_acf_references_ability_list_filters_inner()

Report the values a caller may filter references by.

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

Ability input.

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

Result.

jpkcom_acf_references_ability_query_references_inner()

Run a filtered, paginated query over publicly listed references.

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

Ability input.

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

Result.

jpkcom_acf_references_ability_get_reference_inner()

Return one reference by ID.

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

Ability input.

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

Result.

jpkcom_acf_references_ability_list_filters()

Execute callback for jpkcom-acf-references/list-filters.

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

Ability input.

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

Result.

jpkcom_acf_references_ability_query_references()

Execute callback for jpkcom-acf-references/query-references.

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

Ability input.

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

Result.

jpkcom_acf_references_ability_get_reference()

Execute callback for jpkcom-acf-references/get-reference.

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

Ability input.

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

Result.

jpkcom_acf_references_get_ability_definitions()

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.

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

Ability name => registration args.

jpkcom_acf_references_register_ability_category()

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.

Tags
since
1.2.0

jpkcom_acf_references_register_abilities()

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.

Tags
since
1.2.0

jpkcom_acf_references_disable_archive_field()

Render disable archive checkbox field

jpkcom_acf_references_disable_archive_field() : void
Tags
since
1.0.0

jpkcom_acf_references_redirect_url_field()

Render archive redirect URL field

jpkcom_acf_references_redirect_url_field() : void
Tags
since
1.0.0

jpkcom_acf_references_shortcodes_page()

Render Shortcodes admin page

jpkcom_acf_references_shortcodes_page() : void
Tags
since
1.0.0

jpkcom_acf_references_options_page()

Render Options admin page

jpkcom_acf_references_options_page() : void
Tags
since
1.0.0

jpkcom_acf_references_breadcrumb()

Output Bootstrap 5 breadcrumb navigation

jpkcom_acf_references_breadcrumb() : void

Generates breadcrumb navigation for:

  • Single reference posts (Home > References > Reference Title)
  • Reference archive (Home > References)
  • Other pages (Home > Page Title)

Includes proper ARIA labels and semantic HTML5 markup.

Tags
since
1.0.0
global

WP_Post $post Current post object.

Return values
void —

Outputs HTML directly.

jpkcom_render_acf_fields()

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:

  • Images: Responsive with rounded corners
  • WYSIWYG/Textarea: Light background container
  • Relationships/Post Objects: Linked post titles
  • True/False: Badge indicators
  • Repeater: Responsive tables
  • Groups: Nested definition lists
Parameters
$post_type : string = ''

Optional. Post type for field group query. Default empty (uses current post type).

Tags
since
1.0.0
global

WP_Post $post Current post object.

acf_get_field_label()

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.

Parameters
$field_key_or_name : string

Field key (e.g., 'field_abc123') or field name (e.g., 'job_title').

Tags
since
1.0.0
Return values
string —

Field label or formatted fallback string.

jpkcom_get_acf_field_label()

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:

  1. Direct field key lookup (if starts with 'field_')
  2. Search through field groups by post type
  3. Search through sub_fields (repeater/group fields)
  4. Fallback to formatted field name
Parameters
$field_name_or_key : string

Field name (e.g., 'job_title') or field key (e.g., 'field_abc123').

$post_type : string = ''

Optional. Post type for context-specific field group search. Default empty.

Tags
since
1.0.0
Return values
string —

Field label or formatted fallback string.

jpkcom_human_readable_relative_date()

Convert timestamp to human-readable relative date string

jpkcom_human_readable_relative_date(int $timestamp) : string

Converts Unix timestamps into relative date strings like:

  • "Published today"
  • "Published yesterday"
  • "Published 3 days ago"
  • "Published 2 weeks ago"
  • "Published 5 months ago"
  • "Published 2 years ago"

All strings are translatable via the 'jpkcom-acf-references' text domain.

Parameters
$timestamp : int

Unix timestamp to convert.

Tags
since
1.0.0
Return values
string —

Translated relative date string.

jpkcom_acf_references_media_size()

Register custom image sizes for reference posts

jpkcom_acf_references_media_size() : void

Registers six image sizes:

  • jpkcom-acf-reference-16x9: 576x324px (16:9, hard crop)
  • jpkcom-acf-reference-logo: 512x512px (square, hard crop)
  • jpkcom-acf-reference-header: 992x558px (16:9, hard crop)
  • jpkcom-acf-reference-card-overlay: 800x600px (4:3, hard crop)
  • jpkcom-acf-reference-gallery-thumb: 200x200px (square, hard crop)
  • jpkcom-acf-reference-gallery-modal: 1400px width (proportional, no crop)
Tags
since
1.0.0

jpkcom_acf_references_image_sizes_to_selector()

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.

Parameters
$sizes : array<string|int, string>

Existing image size options.

Tags
since
1.0.0
Return values
array<string|int, string> —

Modified array with custom sizes added.

jpkcom_acf_references_pagination()

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:

  • First/Last page links (« »)
  • Previous/Next page links (‹ ›)
  • Numbered page links with range control
  • Active page indicator
  • Disabled state for unavailable actions
Parameters
$pages : string|int = ''

Optional. Total number of pages. Default empty (auto-detect from query).

$range : int = 2

Optional. Number of page links to show on either side of current page. Default 2.

Tags
since
1.0.0
global

int $paged Current page number (set by WordPress).

WP_Query $wp_query WordPress query object.

Return values
void —

Outputs HTML directly.

jpkcom_acf_references_build_reference_query_args()

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:

  1. 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.

  2. 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.

  3. 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.

Parameters
$args : array<string, mixed> = []

Arguments merged over the base rule.

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

WP_Query arguments.

jpkcom_acf_references_normalise_date()

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.

Parameters
$raw : mixed

Stored value.

Tags
since
1.2.0
Return values
string|null —

Y-m-d, or null when the value is unusable.

jpkcom_acf_references_plain_text()

Reduce a stored value to plain text.

jpkcom_acf_references_plain_text(mixed $value) : string
Parameters
$value : mixed

Stored value.

Tags
since
1.2.0
Return values
string —

Plain text, empty when the value is not a string.

jpkcom_acf_references_normalise_related()

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.

Parameters
$value : mixed

Stored value.

Tags
since
1.2.0
Return values
array<int, array<string, mixed>> —

Related records.

jpkcom_acf_references_attachment_url()

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.

Parameters
$value : mixed

Stored value.

Tags
since
1.2.0
Return values
string|null —

Attachment URL, or null.

jpkcom_acf_references_normalise_gallery()

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.

Parameters
$value : mixed

Stored value.

Tags
since
1.2.0
Return values
array<int, array<string, mixed>> —

Gallery images.

jpkcom_acf_references_normalise_terms()

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.

Parameters
$post_id : int

Reference ID.

$taxonomy : string

Taxonomy slug.

Tags
since
1.2.0
Return values
array<int, array<string, string>> —

Assigned terms.

jpkcom_acf_references_get_reference_data()

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.

Parameters
$post_id : int

Reference ID.

$full : bool = false

Whether to include the detail block.

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

Reference data, or [] when unreadable.

jpkcom_acf_references_locate_template()

jpkcom_acf_references_locate_template(string $template_name) : string|false
Parameters
$template_name : string
Return values
string|false

jpkcom_acf_references_locate_template()

Locate template file with override support

jpkcom_acf_references_locate_template(string $template_name) : string|false

Searches for template files in this priority order:

  1. Child Theme: /wp-content/themes/your-child-theme/jpkcom-acf-references/
  2. Parent Theme: /wp-content/themes/your-theme/jpkcom-acf-references/
  3. MU plugin override: /wp-content/mu-plugins/jpkcom-acf-references-overrides/templates/
  4. Plugin itself: /wp-content/plugins/jpkcom-acf-references/templates/ (or debug-templates/ if WP_DEBUG)
Parameters
$template_name : string

Template filename (e.g., 'single-reference.php' or 'partials/reference/customer.php').

Tags
since
1.0.0
Return values
string|false —

Full path to template file if found, false otherwise.

jpkcom_acf_references_template_include()

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).

Parameters
$template : string

Default template path from WordPress.

Tags
since
1.0.0
Return values
string —

Template path to use (plugin template or default).

jpkcom_acf_references_get_template_part()

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]);

Parameters
$slug : string

Template slug (e.g., 'partials/reference/customer').

$name : string = ''

Optional. Template name/variation (e.g., 'alternative'). Default empty.

$args : array<string|int, mixed> = []

Optional. Array of variables to pass to the template. Default empty.

Tags
since
1.0.0
On this page

Search results