Skip to content

Hooks/Docs: rest_revision_query xref points to posts-controller — hook not there, needs its own PHPDoc #9

Closed

Description

@apermo

Problem

In class-wp-rest-revisions-controller.php at line 300, rest_revision_query carries a cross-reference to class-wp-rest-posts-controller.php. That file does not contain rest_revision_query — it contains the similar but distinct dynamic filter rest_{$this->post_type}_query.

rest_revision_query is a separate, revision-specific filter that has never had its own PHPDoc block.

Affected cross-reference

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php#L299-L303

Similar filter in posts controller (not the same hook)

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php#L412-L445

Fix

Remove the cross-reference comment and replace it with a proper PHPDoc block for rest_revision_query, for example:

/**
 * Filters WP_Query arguments when querying revisions via the REST API.
 *
 * @since 4.7.0
 *
 * @link https://developer.wordpress.org/reference/classes/wp_query/
 *
 * @param array           $args    Array of arguments for WP_Query.
 * @param WP_REST_Request $request The REST API request.
 */

Activity

  1. added this to the Broken cross-references milestone on Mar 8, 2026
  2. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Architectural investigation

    After deeper analysis, this cross-reference points to class-wp-rest-posts-controller.php with the implicit assumption that rest_revision_query is an instance of the dynamic hook rest_{$this->post_type}_query (i.e., fired when $this->post_type === 'revision'). That assumption is incorrect.

    Class hierarchy:

    • WP_REST_Posts_Controller extends WP_REST_Controller — fires rest_{$this->post_type}_query (line 444)
    • WP_REST_Revisions_Controller extends WP_REST_Controller — fires rest_revision_query independently (line 301)

    WP_REST_Revisions_Controller does NOT extend WP_REST_Posts_Controller. These are sibling controllers, both extending the base WP_REST_Controller. The dynamic hook in the posts controller therefore never fires with post_type = revision, and the two hooks (rest_revision_query and rest_{$this->post_type}_query) are architecturally unrelated despite serving the same conceptual purpose.

    Intent vs reality:

    The intent clearly was to document rest_revision_query as the revision-specific counterpart to rest_{$this->post_type}_query. Both filters pass ($args, $request) and serve the same purpose of filtering WP_Query arguments before a REST query executes. The cross-reference comment reflects this relationship — but points to the wrong file and the wrong hook name.

    Open question on fix approach:

    Two reasonable paths:

    1. Own PHPDoc in the revisions controller (proposed in the issue body above): Replace the cross-reference with a standalone @since 4.7.0 block. Clean and self-contained.

    2. Add rest_revision_query to the example list in the posts controller: The posts controller's PHPDoc already lists rest_post_query, rest_page_query, rest_attachment_query as examples of rest_{$this->post_type}_query (lines 430–432). Adding rest_revision_query there with a note that it is a parallel hook (not a dynamic variant) would highlight the relationship — but would be technically misleading since the hooks are not related by the $this->post_type pattern.

    Path 1 is cleaner. Path 2 creates confusion about the dynamic hook's scope.

  3. added
    documentationImprovements or additions to documentation
    verifiedIssue is manually verified.
    on Mar 8, 2026
  4. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Recommended fix approach (based on prior art in core)

    After reviewing how core documents related hooks elsewhere, the idiomatic approach is:

    1. Own PHPDoc block in the revisions controller

    Replace the cross-reference comment with a proper PHPDoc block directly above the rest_revision_query call in class-wp-rest-revisions-controller.php. This is the canonical home for this hook.

    2. {@see} link in the get_items() method docblock

    In the same revisions controller, add a {@see 'rest_revision_query'} line to the get_items() method's function-level docblock. This follows the same pattern used in comment.php and post.php, where related hooks are cross-referenced at the containing-function level rather than inside the hook's own @param block.

    Optionally, the posts controller's get_items() docblock could add a {@see 'rest_revision_query'} note to surface the relationship from the other direction.

    Why not cross-reference inside the hook's own PHPDoc block?

    No core example writes @see another_hook inside a hook's own @param block. The hook-to-hook relationship is always documented at the containing function level, not in the hook's own block.

    Why not add rest_revision_query to the "Possible hook names" list in the posts controller?

    That list documents instances of the same dynamic hook pattern (rest_{$this->post_type}_query). rest_revision_query is not an instance of that pattern — it is fired by a sibling controller that does not extend WP_REST_Posts_Controller. Adding it there would imply a relationship that does not exist in the code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhas-fixHas a fix/PR upstream is openedverifiedIssue is manually verified.

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions