GB Query Enhancements includes a number of useful hooks to allow developers to extend and alter the plugin’s functionality.

Hooks Reference

This document lists all custom WordPress hooks (filters) provided by GB Query Enhancements. These hooks allow developers to customize query behavior, modify responses, and extend functionality.

Term Query Hooks

`gb_query_enhancements_max_terms`

Filter the maximum number of terms returned when “Show All” (-1 or 0) is selected for posts per page. This prevents performance issues from unbounded queries.

Parameters:

Parameter	Type	Description
`$max_terms`	`int`	Maximum terms limit. Default: `150`

Example:

add_filter( 'gb_query_enhancements_max_terms', function( $max_terms ) {
    return 300; // Allow up to 300 terms
} );

`gb_query_enhancements_term_query_args`

Filter the final term query arguments before the query is executed. This is the main hook for modifying term queries and runs for both frontend rendering and editor previews.

Parameters:

Parameter	Type	Description
`$normalized`	`array`	The sanitized/normalized query arguments
`$args`	`array`	The original unsanitized arguments
`$attributes`	`array`	The block attributes
`$page`	`int`	The current page number

Example:

add_filter( 'gb_query_enhancements_term_query_args', function( $normalized, $args, $attributes, $page ) {
    // Only show terms with posts
    $normalized['hide_empty'] = true;

    // Add custom ordering based on block attribute
    if ( ! empty( $attributes['customOrder'] ) ) {
        $normalized['orderby'] = $attributes['customOrder'];
    }

    return $normalized;
}, 10, 4 );

`gb_query_enhancements_term_query_data`

Filter the full term query data array after the query has executed. Use this to modify results (reorder, remove, inject synthetic items), override pagination values, or add custom data.

Parameters:

Parameter	Type	Description
`$query_data`	`array`	The query data array with keys: `data` (array of terms), `no_results` (bool), `args` (array), `total` (int), `max_num_pages` (int)
`$attributes`	`array`	The block attributes
`$page`	`int`	The current page number

Example:

add_filter( 'gb_query_enhancements_term_query_data', function( $query_data, $attributes, $page ) {
    // Remove terms that only have posts in draft status
    $query_data['data'] = array_filter( $query_data['data'], function( $term ) {
        $posts = get_posts( [
            'post_status' => 'publish',
            'tax_query'   => [ [ 'taxonomy' => $term->taxonomy, 'terms' => $term->term_id ] ],
            'fields'      => 'ids',
            'numberposts' => 1,
        ] );
        return ! empty( $posts );
    } );

    $query_data['total']      = count( $query_data['data'] );
    $query_data['no_results'] = empty( $query_data['data'] );

    return $query_data;
}, 10, 3 );

`gb_query_enhancements_rest_term_query_args`

Filter term query arguments specifically for REST API requests (editor previews). Runs after gb_query_enhancements_term_query_args.

Parameters:

Parameter	Type	Description
`$normalized_args`	`array`	The normalized term query arguments
`$request`	`\WP_REST_Request`	The REST request object
`$args`	`array`	The original args passed to the request
`$attributes`	`array`	The attributes passed to the request

Example:

add_filter( 'gb_query_enhancements_rest_term_query_args', function( $args, $request, $original_args, $attributes ) {
    // Limit preview results in editor
    $args['number'] = min( $args['number'] ?? 10, 20 );
    return $args;
}, 10, 4 );

`gb_query_enhancements_rest_terms_response`

Filter the REST API response for term queries. Useful for adding custom data to the editor preview.

Parameters:

Parameter	Type	Description
`$response`	`array`	The response data containing `terms`, `total`, `total_pages`, `page`
`$request`	`\WP_REST_Request`	The REST request object
`$terms`	`array`	The raw terms array

Example:

add_filter( 'gb_query_enhancements_rest_terms_response', function( $response, $request, $terms ) {
    // Add taxonomy info to response
    $response['taxonomy_info'] = get_taxonomy( $request->get_param( 'taxonomy' ) );
    return $response;
}, 10, 3 );

`gb_query_enhancements_term_response_data`

Filter individual term data in REST API responses. Called for each term when formatting the response.

Parameters:

Parameter	Type	Description
`$term_data`	`array`	The term data array with keys: `term_id`, `name`, `slug`, `taxonomy`, `description`, `parent`, `count`
`$term`	`\WP_Term`	The term object

Example:

add_filter( 'gb_query_enhancements_term_response_data', function( $term_data, $term ) {
    // Add term meta to response
    $term_data['featured_image'] = get_term_meta( $term->term_id, 'featured_image', true );
    $term_data['custom_url'] = get_term_meta( $term->term_id, 'custom_url', true );
    return $term_data;
}, 10, 2 );

`gb_query_enhancements_term_meta_query`

Filter the built meta_query array for term queries. Useful for adding complex meta conditions.

Parameters:

Parameter	Type	Description
`$meta_query`	`array`	The built meta query array
`$meta_params`	`array`	The original meta parameters

Example:

add_filter( 'gb_query_enhancements_term_meta_query', function( $meta_query, $meta_params ) {
    // Add additional meta clause
    $meta_query[] = [
        'key'     => 'is_featured',
        'value'   => '1',
        'compare' => '='
    ];
    return $meta_query;
}, 10, 2 );

`gb_query_enhancements_term_loop_item_context`

Filter the block context array for each term loop item before the inner block is rendered. Use this to inject additional context values (e.g., precomputed data, ACF fields, related post IDs) into loop items.

Parameters:

Parameter	Type	Description
`$context`	`array`	The block context array with keys: `taxonomy`, `termId`, `postId`, `generateblocks/queryType`, `generateblocks/loopIndex`, `generateblocks/loopItem`
`$item`	`\WP_Term`	The term object for the current loop item
`$args`	`array`	The query args
`$block`	`\WP_Block`	The parent block instance
`$index`	`int`	The current loop index (1-based)

Example:

add_filter( 'gb_query_enhancements_term_loop_item_context', function( $context, $item, $args, $block, $index ) {
    // Attach a custom "featured image" attachment ID to each term's context
    $context['termFeaturedImage'] = get_term_meta( $item->term_id, 'featured_image', true );

    return $context;
}, 10, 5 );

`gb_query_enhancements_term_query_render_loop_items`

Filter the rendered HTML content for term query loop items. Called after all items are rendered.

Parameters:

Parameter	Type	Description
`$content`	`string`	The rendered HTML content
`$items`	`array`	The term items that were rendered
`$block`	`\WP_Block`	The block instance

Example:

add_filter( 'gb_query_enhancements_term_query_render_loop_items', function( $content, $items, $block ) {
    // Wrap content in custom container
    if ( ! empty( $items ) ) {
        $content = '<div class="terms-grid">' . $content . '</div>';
    }
    return $content;
}, 10, 3 );

User Query Hooks

`gb_query_enhancements_max_users`

Filter the maximum number of users returned when “Show All” (-1 or 0) is selected for posts per page.

Parameters:

Parameter	Type	Description
`$max_users`	`int`	Maximum users limit. Default: `150`

Example:

add_filter( 'gb_query_enhancements_max_users', function( $max_users ) {
    return 50; // Limit to 50 users for performance
} );

`gb_query_enhancements_user_query_args`

Filter the final user query arguments before the query is executed.

Parameters:

Parameter	Type	Description
`$normalized`	`array`	The sanitized/normalized query arguments
`$args`	`array`	The original unsanitized arguments
`$attributes`	`array`	The block attributes
`$page`	`int`	The current page number

Example:

add_filter( 'gb_query_enhancements_user_query_args', function( $normalized, $args, $attributes, $page ) {
    // Only show users who have published posts
    $normalized['has_published_posts'] = true;

    // Exclude specific users
    $normalized['exclude'] = [ 1 ]; // Exclude admin

    return $normalized;
}, 10, 4 );

`gb_query_enhancements_user_query_data`

Filter the full user query data array after the query has executed. Use this to modify results (reorder, remove, inject synthetic items), override pagination values, or add custom data.

Parameters:

Parameter	Type	Description
`$query_data`	`array`	The query data array with keys: `data` (array of user objects), `no_results` (bool), `args` (array), `total` (int), `max_num_pages` (int)
`$attributes`	`array`	The block attributes
`$page`	`int`	The current page number

Example:

add_filter( 'gb_query_enhancements_user_query_data', function( $query_data, $attributes, $page ) {
    // Sort users by custom priority meta
    usort( $query_data['data'], function( $a, $b ) {
        $priority_a = get_user_meta( $a->ID, 'display_priority', true ) ?: 99;
        $priority_b = get_user_meta( $b->ID, 'display_priority', true ) ?: 99;
        return $priority_a - $priority_b;
    } );

    return $query_data;
}, 10, 3 );

`gb_query_enhancements_rest_user_query_args`

Filter user query arguments specifically for REST API requests (editor previews).

Parameters:

Parameter	Type	Description
`$normalized_args`	`array`	The normalized user query arguments
`$request`	`\WP_REST_Request`	The REST request object
`$args`	`array`	The original args passed to the request
`$attributes`	`array`	The attributes passed to the request

Example:

add_filter( 'gb_query_enhancements_rest_user_query_args', function( $args, $request, $original_args, $attributes ) {
    // Limit to specific roles in editor preview
    if ( empty( $args['role'] ) ) {
        $args['role__in'] = [ 'author', 'editor', 'administrator' ];
    }
    return $args;
}, 10, 4 );

`gb_query_enhancements_rest_users_response`

Filter the REST API response for user queries.

Parameters:

Parameter	Type	Description
`$response`	`array`	The response data containing `users`, `total`, `total_pages`, `page`
`$request`	`\WP_REST_Request`	The REST request object
`$users`	`array`	The raw users array

Example:

add_filter( 'gb_query_enhancements_rest_users_response', function( $response, $request, $users ) {
    // Add available roles to response
    $response['available_roles'] = wp_roles()->get_names();
    return $response;
}, 10, 3 );

`gb_query_enhancements_user_response_data`

Filter individual user data in REST API responses.

Parameters:

Parameter	Type	Description
`$user_data`	`array`	The user data array with keys: `ID`, `user_login`, `user_nicename`, `user_email`, `user_url`, `user_registered`, `display_name`
`$user`	`\WP_User`	The user object

Example:

add_filter( 'gb_query_enhancements_user_response_data', function( $user_data, $user ) {
    // Add user meta
    $user_data['bio'] = get_user_meta( $user->ID, 'description', true );
    $user_data['avatar_url'] = get_avatar_url( $user->ID );
    $user_data['post_count'] = count_user_posts( $user->ID );
    return $user_data;
}, 10, 2 );

`gb_query_enhancements_user_meta_query`

Filter the built meta_query array for user queries.

Parameters:

Parameter	Type	Description
`$meta_query`	`array`	The built meta query array
`$meta_params`	`array`	The original meta parameters

Example:

add_filter( 'gb_query_enhancements_user_meta_query', function( $meta_query, $meta_params ) {
    // Only show verified users
    $meta_query[] = [
        'key'     => 'verified',
        'value'   => '1',
        'compare' => '='
    ];
    return $meta_query;
}, 10, 2 );

`gb_query_enhancements_user_loop_item_context`

Filter the block context array for each user loop item before the inner block is rendered. Use this to inject additional context values into loop items.

Parameters:

Parameter	Type	Description
`$context`	`array`	The block context array with keys: `userId`, `postId`, `generateblocks/queryType`, `generateblocks/loopIndex`, `generateblocks/loopItem`
`$item`	`stdClass`	The user data object for the current loop item
`$args`	`array`	The query args
`$block`	`\WP_Block`	The parent block instance
`$index`	`int`	The current loop index (1-based)

Example:

add_filter( 'gb_query_enhancements_user_loop_item_context', function( $context, $item, $args, $block, $index ) {
    // Add the user's latest post ID to context
    $latest = get_posts( [
        'author'      => $item->ID,
        'numberposts' => 1,
        'fields'      => 'ids',
    ] );

    $context['userLatestPostId'] = $latest[0] ?? 0;

    return $context;
}, 10, 5 );

`gb_query_enhancements_user_query_render_loop_items`

Filter the rendered HTML content for user query loop items.

Parameters:

Parameter	Type	Description
`$content`	`string`	The rendered HTML content
`$items`	`array`	The user items that were rendered
`$block`	`\WP_Block`	The block instance

Example:

add_filter( 'gb_query_enhancements_user_query_render_loop_items', function( $content, $items, $block ) {
    // Add schema markup wrapper
    if ( ! empty( $items ) ) {
        $content = '<div itemscope itemtype="https://schema.org/ItemList">' . $content . '</div>';
    }
    return $content;
}, 10, 3 );

Dynamic Tags Hooks

`gb_query_enhancements_dynamic_tag_output_{$tag}`

Filter the output of a specific dynamic tag. The dynamic portion of the hook name, $tag, refers to the tag name.

Available tags: term_title, term_description, term_archive_url, term_count, user_display_name, user_email, user_bio, user_avatar_url, user_url, user_posts_url, user_post_count

Parameters:

Parameter	Type	Description
`$output`	`string`	The dynamic tag output
`$options`	`array`	The dynamic tag options
`$instance`	`\WP_Block`	The block instance containing the tag

Examples:

// Truncate long term descriptions to 100 characters
add_filter( 'gb_query_enhancements_dynamic_tag_output_term_description', function( $output, $options, $instance ) {
    if ( strlen( $output ) > 100 ) {
        $output = mb_substr( $output, 0, 100 ) . '&hellip;';
    }
    return $output;
}, 10, 3 );

// Output user email as a mailto link
add_filter( 'gb_query_enhancements_dynamic_tag_output_user_email', function( $output, $options, $instance ) {
    if ( ! empty( $output ) && is_email( $output ) ) {
        $output = sprintf( '<a href="mailto:%s">%s</a>', esc_attr( $output ), esc_html( $output ) );
    }
    return $output;
}, 10, 3 );

// Append a role badge after user display name
add_filter( 'gb_query_enhancements_dynamic_tag_output_user_display_name', function( $output, $options, $instance ) {
    $loop_item = $instance->context['generateblocks/loopItem'] ?? null;
    $roles     = is_object( $loop_item ) && isset( $loop_item->roles ) ? $loop_item->roles : [];

    if ( in_array( 'administrator', $roles, true ) ) {
        $output .= ' <span class="role-badge role-admin">Admin</span>';
    }

    return $output;
}, 10, 3 );

`gb_query_enhancements_supported_core_blocks`

Filter the list of core blocks that receive dynamic tag replacements and loop context injection. This filters the saved setting value from the Settings > GB Query Enhancements > Core Block Support page. The default is an empty array — no core blocks are enabled until explicitly checked in settings.

Parameters:

Parameter	Type	Description
`$blocks`	`array`	Array of core block names saved in settings (default: `[]`)

Example:

// Programmatically enable core/paragraph regardless of the saved setting
add_filter( 'gb_query_enhancements_supported_core_blocks', function( $blocks ) {
    if ( ! in_array( 'core/paragraph', $blocks, true ) ) {
        $blocks[] = 'core/paragraph';
    }
    return $blocks;
} );

`gb_query_enhancements_context_keys`

Filter the context keys passed through from parent blocks to supported core blocks during rendering. This is the companion to gb_query_enhancements_supported_core_blocks — if you add custom context via the loop item context filters, you’ll need to add the corresponding keys here for them to be available in core blocks.

Parameters:

Parameter	Type	Description
`$keys`	`array`	Array of context key strings

Example:

add_filter( 'gb_query_enhancements_context_keys', function( $keys ) {
    // Pass custom context keys through to core blocks
    $keys[] = 'termFeaturedImage';
    $keys[] = 'userLatestPostId';
    return $keys;
} );

Hook Execution Order

Understanding when hooks fire helps you choose the right one:

Frontend Rendering

gb_query_enhancements_term_query_args / gb_query_enhancements_user_query_args
gb_query_enhancements_term_meta_query / gb_query_enhancements_user_meta_query (if meta query used)
gb_query_enhancements_term_query_data / gb_query_enhancements_user_query_data
gb_query_enhancements_supported_core_blocks / gb_query_enhancements_context_keys (during block rendering)
gb_query_enhancements_term_loop_item_context / gb_query_enhancements_user_loop_item_context (per item)
gb_query_enhancements_dynamic_tag_output_{$tag} (per dynamic tag)
gb_query_enhancements_term_query_render_loop_items / gb_query_enhancements_user_query_render_loop_items

Editor Preview (REST API)

gb_query_enhancements_term_query_args / gb_query_enhancements_user_query_args
gb_query_enhancements_rest_term_query_args / gb_query_enhancements_rest_user_query_args
gb_query_enhancements_term_response_data / gb_query_enhancements_user_response_data (per item)
gb_query_enhancements_rest_terms_response / gb_query_enhancements_rest_users_response