You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Hooks/Docs: rest_revision_query xref points to posts-controller — hook not there, needs its own PHPDoc #9
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.
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.
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:
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.
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.
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.
Activity
apermo commentedon Mar 8, 2026
Architectural investigation
After deeper analysis, this cross-reference points to
class-wp-rest-posts-controller.phpwith the implicit assumption thatrest_revision_queryis an instance of the dynamic hookrest_{$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— firesrest_{$this->post_type}_query(line 444)WP_REST_Revisions_Controller extends WP_REST_Controller— firesrest_revision_queryindependently (line 301)WP_REST_Revisions_Controllerdoes NOT extendWP_REST_Posts_Controller. These are sibling controllers, both extending the baseWP_REST_Controller. The dynamic hook in the posts controller therefore never fires withpost_type = revision, and the two hooks (rest_revision_queryandrest_{$this->post_type}_query) are architecturally unrelated despite serving the same conceptual purpose.Intent vs reality:
The intent clearly was to document
rest_revision_queryas the revision-specific counterpart torest_{$this->post_type}_query. Both filters pass($args, $request)and serve the same purpose of filteringWP_Queryarguments 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:
Own PHPDoc in the revisions controller (proposed in the issue body above): Replace the cross-reference with a standalone
@since 4.7.0block. Clean and self-contained.Add
rest_revision_queryto the example list in the posts controller: The posts controller's PHPDoc already listsrest_post_query,rest_page_query,rest_attachment_queryas examples ofrest_{$this->post_type}_query(lines 430–432). Addingrest_revision_querythere 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_typepattern.Path 1 is cleaner. Path 2 creates confusion about the dynamic hook's scope.
apermo commentedon Mar 8, 2026
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_querycall inclass-wp-rest-revisions-controller.php. This is the canonical home for this hook.2.
{@see}link in theget_items()method docblockIn the same revisions controller, add a
{@see 'rest_revision_query'}line to theget_items()method's function-level docblock. This follows the same pattern used incomment.phpandpost.php, where related hooks are cross-referenced at the containing-function level rather than inside the hook's own@paramblock.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_hookinside a hook's own@paramblock. 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_queryto 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_queryis not an instance of that pattern — it is fired by a sibling controller that does not extendWP_REST_Posts_Controller. Adding it there would imply a relationship that does not exist in the code.