JPKCom ACF References

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.

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.

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.

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.

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.

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.

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.