WooCommerce Code Reference

IdCursorFilter
in package

WP_Query ID-cursor pagination helper.

Implements cursor-based pagination on the posts ID column by hooking posts_where and reading two custom query vars:

  • wc_api_after_id — emit AND ID > X in the SQL WHERE clause.
  • wc_api_before_id — emit AND ID < X.

Resolvers set whichever of those vars they need on their WP_Query args and call {@see} once before running the query. The filter registers itself lazily on first use and short-circuits for any query that doesn't set these vars, so it's safe to leave in place for the rest of the request.

Table of Contents

AFTER_ID  = 'wc_api_after_id'
Query var for the exclusive lower-bound ID (`ID > X`).
BEFORE_ID  = 'wc_api_before_id'
Query var for the exclusive upper-bound ID (`ID < X`).
$registered  : bool
Whether the posts_where hook is currently registered for this request.
apply()  : string
Filter callback for `posts_where`. Appends cursor conditions when the corresponding query vars are set on the WP_Query; returns the input clause unchanged otherwise.
decode_id_cursor()  : int
Decode a base64-encoded ID cursor into a positive integer.
ensure_registered()  : void
Register the posts_where filter on first call; no-op thereafter.

Constants

Properties

Methods

apply()

Filter callback for `posts_where`. Appends cursor conditions when the corresponding query vars are set on the WP_Query; returns the input clause unchanged otherwise.

public static apply(string $where, WP_Query $query) : string
Parameters
$where : string

SQL WHERE clause being built.

$query : WP_Query

The WP_Query being prepared.

Return values
string — The modified WHERE clause.

decode_id_cursor()

Decode a base64-encoded ID cursor into a positive integer.

public static decode_id_cursor(string $cursor, string $name) : int

Resolvers encode cursors via base64_encode( (string) $id ) on the way out; this is the symmetric decode. base64_decode(..., true) returns false for malformed input, which (int) casts to 0 and {@see} would silently treat as "no cursor" — leaving clients with unfiltered results instead of a clear error. Validate explicitly and throw INVALID_ARGUMENT → HTTP 400 on any bad input.

Parameters
$cursor : string

The client-supplied cursor string.

$name : string

Which cursor argument (after / before), for error messages.

Tags
throws
ApiException

When the cursor isn't a valid base64-encoded positive integer.

Return values
int — The decoded positive integer ID.

ensure_registered()

Register the posts_where filter on first call; no-op thereafter.

public static ensure_registered() : void

The filter is a no-op for queries that don't set the cursor query vars, so leaving it registered for the remainder of the request is harmless — and it means resolvers never need to clean up after themselves, which is how the previous add/remove dance leaked.

Return values
void —