Add randomness for post selection by aaronjorbin · Pull Request #14018 · WordPress/wordpress-develop

aaronjorbin · 2026-10-05T16:39:58Z

Random content redirects are built on the existing rewrite and query layers. random is a public query var, so ?random works on any archive, search or home URL. WP_Rewrite::random_rewrite_rules(), prefixed by the new $random_base, uses generate_rewrite_rules() to build /random/, /random/{taxonomy}/{term}/, /random/author/{name}/ and /random/{post-type-archive}/. These rules are merged ahead of the greedy page and post rules. Which content can be picked is set by a new randomable post type argument, which falls back to publicly_queryable and then to public. Posts are randomable; pages and attachments are not. Rules are only generated for randomable types and for taxonomies attached to them. A published page at the random base takes precedence over /random/. That check happens when the rules are generated, and wp_after_insert_post and after_delete_post flush the rules whenever such a page changes. The trade-off is that request time stays free of the extra lookup, at the cost of a rule flush whenever that one page changes. It also makes the rules depend on content, so a stale cache could briefly show the wrong winner. Separately, rules for a disabled feature or a newly registered type only appear after a flush, which matches how the rest of the rewrite API behaves.

The main query does the random pick. A late pre_get_posts callback at priority 1000 sets one row, orderby=rand, published and non-password posts, no stickies, no found rows and no cache priming. It also neutralizes the overrides themes commonly set: nopaging, posts_per_archive_page, showposts and offset. A split_the_query callback stops WP_Query from splitting the request, because random queries are never cached. The result is that /random/ costs exactly one database query, and nothing is queried before it. Every WP_Query filter still applies, which was Peter's main objection to the reverted version. The late priority protects randomness from theme archive tweaks. The cost is that developers who want to change the selection must use wp_is_random_content_query() inside pre_get_posts, and they can't widen eligibility past randomable. ORDER BY RAND() is a full scan of the eligible rows. It was accepted over a COUNT plus random OFFSET, which takes two queries, because one query was the stated goal; very large sites may eventually want a cheaper strategy behind a filter. The redirect itself is a 302 sent on send_headers, before the wp action and template loading, with no-cache and noindex headers added through wp_headers. Singular, feed, admin, non-GET/HEAD and empty-archive requests fall through to normal rendering. A permalink on a host wp_safe_redirect() won't allow is skipped instead of being replaced by its dashboard fallback. That favors safety over following plugins that point permalinks to other domains.

Trac Ticket: https://core.trac.wordpress.org/ticket/64498

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Opus 5.5
Used for: basically everything

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

Random content redirects are built on the existing rewrite and query layers. random is a public query var, so ?random works on any archive, search or home URL. WP_Rewrite::random_rewrite_rules(), prefixed by the new $random_base, uses generate_rewrite_rules() to build /random/, /random/{taxonomy}/{term}/, /random/author/{name}/ and /random/{post-type-archive}/. These rules are merged ahead of the greedy page and post rules. Which content can be picked is set by a new randomable post type argument, which falls back to publicly_queryable and then to public. Posts are randomable; pages and attachments are not. Rules are only generated for randomable types and for taxonomies attached to them. A published page at the random base takes precedence over /random/. That check happens when the rules are generated, and wp_after_insert_post and after_delete_post flush the rules whenever such a page changes. The trade-off is that request time stays free of the extra lookup, at the cost of a rule flush whenever that one page changes. It also makes the rules depend on content, so a stale cache could briefly show the wrong winner. Separately, rules for a disabled feature or a newly registered type only appear after a flush, which matches how the rest of the rewrite API behaves. The main query does the random pick. A late pre_get_posts callback at priority 1000 sets one row, orderby=rand, published and non-password posts, no stickies, no found rows and no cache priming. It also neutralizes the overrides themes commonly set: nopaging, posts_per_archive_page, showposts and offset. A split_the_query callback stops WP_Query from splitting the request, because random queries are never cached. The result is that /random/ costs exactly one database query, and nothing is queried before it. Every WP_Query filter still applies, which was Peter's main objection to the reverted version. The late priority protects randomness from theme archive tweaks. The cost is that developers who want to change the selection must use wp_is_random_content_query() inside pre_get_posts, and they can't widen eligibility past randomable. ORDER BY RAND() is a full scan of the eligible rows. It was accepted over a COUNT plus random OFFSET, which takes two queries, because one query was the stated goal; very large sites may eventually want a cheaper strategy behind a filter. The redirect itself is a 302 sent on send_headers, before the wp action and template loading, with no-cache and noindex headers added through wp_headers. Singular, feed, admin, non-GET/HEAD and empty-archive requests fall through to normal rendering. A permalink on a host wp_safe_redirect() won't allow is skipped instead of being replaced by its dashboard fallback. That favors safety over following plugins that point permalinks to other domains. Trac Ticket: https://core.trac.wordpress.org/ticket/64498

github-actions · 2026-10-05T16:40:10Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jorbin, peterwilsoncc, westonruter, annezazu.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-10-05T16:43:16Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Parameter #2 $fallback_url of function wp_validate_redirect expects string, false given.

annezazu · 2026-10-05T18:43:33Z

Gave this a spin locally and it's working well! I used AI to put in some filler content.

Testing with just /random:

Screen.Recording.2026-10-05.at.12.39.51.PM.mov

Testing with /random/author/[name]:

Screen.Recording.2026-10-05.at.12.40.31.PM.mov

I also tested with an author without any posts and it showed no results:

Screen.Recording.2026-10-05.at.12.42.51.PM.mov

peterwilsoncc

I've done a first pass review and left a few comments inline.

This is looking pretty good generally.

peterwilsoncc · 2026-10-05T22:24:44Z

+	/*
+	 * Only redirect to locations permitted by wp_safe_redirect(). Off-site permalinks would
+	 * otherwise be replaced by its fallback, sending the visitor to the dashboard.
+	 */
+	if ( ! $location || ! wp_validate_redirect( $location, '' ) ) {


wp_safe_redirect() calls wp_validate_redirect() so there's no need to validate twice.

Suggested change

/*

* Only redirect to locations permitted by wp_safe_redirect(). Off-site permalinks would

* otherwise be replaced by its fallback, sending the visitor to the dashboard.

*/

if ( ! $location || ! wp_validate_redirect( $location, '' ) ) {

if ( ! $location ) {

peterwilsoncc · 2026-10-05T22:42:02Z

+			'publicly_queryable' => true,
+			'randomable'         => true,


Suggested change

'publicly_queryable' => true,

'randomable' => true,

'publicly_queryable' => true,

'randomable' => true,

'has_archive' => true,

peterwilsoncc · 2026-10-05T22:47:41Z

+		return;
+	}
+
+	foreach ( array( $post, $post_before ) as $page ) {


The rewrite flush will need if:

the permalinks use /%postname%/,

a post with the slug random is created, and,

the blog doesn't have a prefix (I think this is only a multi-site thing without a filter).

peterwilsoncc · 2026-10-05T22:49:19Z

 		$args['embeddable'] ??= $args['public'];

+		// If not set, default to the setting for 'publicly_queryable'.
+		$args['randomable'] ??= $args['publicly_queryable'];


&& has_archive ?

peterwilsoncc · 2026-10-05T23:06:56Z

+	 * @since 7.2.0
+	 * @var string
+	 */
+	public $random_base = 'random';


This will need to be an option on the permalink screen for i18n: French users may want to change this to aléatoire, for example.

I can't find if the default values are translatable for the category and tag bases but it will be good to check in with the polyglot team. If the other bases aren't translatable it would be good to check with the team if that was a backward compatibility choice at the time to avoid breaking URLs.

peterwilsoncc · 2026-10-05T23:26:53Z

+		add_filter( 'wp_redirect', array( $this, 'filter_wp_redirect' ), 10, 2 );
+	}
+
+	public function tear_down() {


I think all of these are reset in the base tear down. Leaving confirmation as homework.

Post types certainly are.

peterwilsoncc · 2026-10-05T23:32:21Z

+			array_merge(
+				array(
+					'post_status' => 'publish',
+					'post_date'   => '2022-01-01 00:00:00',


All I am saying is that:

Hamilton debut was on August 6, 2015

Dear Evan Hansen debut was December 4, 2016 (I'm still crying)

Shucked debut was April 4, 2023

peterwilsoncc · 2026-10-05T23:37:28Z

+			'future'             => array(
+				array(
+					'post_status' => 'future',
+					'post_date'   => '2099-01-01 00:00:00',


I'm the worst but technically this is a flaky test whereas time() + YEAR_IN_SECONDS is not.

peterwilsoncc · 2026-10-05T23:39:08Z

+		$this->go_to( home_url( '/random/category/empty/' ) );
+
+		$this->assertNotRedirected( 'An empty archive has nothing to redirect to.' );
+		$this->assertTrue( is_category( 'empty' ), 'The empty archive should be displayed.' );


I think a 404 is more appropriate.

peterwilsoncc · 2026-10-06T00:25:57Z

 add_action( 'attachment_updated', 'wp_check_for_changed_dates', 12, 3 );

+// Random content redirects, see wp_is_random_content_redirect_enabled().
+add_action( 'pre_get_posts', 'wp_random_content_pre_get_posts', 1000 );


If you keep this instead of setting the values in WP then I think it can run at the default of 10 so plugins filtering the results get the populated values.

westonruter · 2026-10-06T00:37:21Z

+		 *
+		 * @since 7.2.0
+		 *
+		 * @param string[] $random_rewrite Array of rewrite rules for random content redirects, keyed by their regex pattern.


Suggested change

* @param string[] $random_rewrite Array of rewrite rules for random content redirects, keyed by their regex pattern.

* @param array<string, string> $random_rewrite Array of rewrite rules for random content redirects, keyed by their regex pattern.

westonruter · 2026-10-06T00:38:10Z

+	 *
+	 * @see wp_is_random_content_redirect_enabled()
+	 *
+	 * @return string[] Array of rewrite rules for random content redirects, keyed by their regex pattern.


Suggested change

* @return string[] Array of rewrite rules for random content redirects, keyed by their regex pattern.

* @return array<string, string> Array of rewrite rules for random content redirects, keyed by their regex pattern.

westonruter · 2026-10-06T00:39:41Z

+ * @param WP_Query $query The query to check.
+ * @return bool True if the query is a request for random content, false otherwise.
+ */
+function wp_is_random_content_query( $query ) {


Suggested change

function wp_is_random_content_query( $query ) {

function wp_is_random_content_query( WP_Query $query ): bool {

westonruter · 2026-10-06T00:39:56Z

+ * @param WP_Query $query The query to retrieve the post types for.
+ * @return string[] Post type names eligible for random selection.
+ */
+function wp_get_random_content_post_types( $query ) {


Suggested change

function wp_get_random_content_post_types( $query ) {

function wp_get_random_content_post_types( WP_Query $query ): array {

westonruter · 2026-10-06T00:40:28Z

+ * @see register_post_type()
+ *
+ * @param WP_Query $query The query to retrieve the post types for.
+ * @return string[] Post type names eligible for random selection.


Suggested change

* @return string[] Post type names eligible for random selection.

* @return string[] Post type names eligible for random selection.

*

* @phpstan-return list<string>

westonruter · 2026-10-06T00:42:10Z

+ * @param string[] $headers Associative array of headers to be sent.
+ * @return string[] Associative array of headers to be sent.
+ */
+function wp_random_content_headers( $headers ) {


Suggested change

function wp_random_content_headers( $headers ) {

function wp_random_content_headers( $headers ): array {

westonruter · 2026-10-06T00:43:44Z

+ *
+ * @return bool True if random content redirects are enabled, false otherwise.
+ */
+function wp_is_random_content_redirect_enabled() {


Suggested change

function wp_is_random_content_redirect_enabled() {

function wp_is_random_content_redirect_enabled(): bool {

westonruter · 2026-10-06T00:44:03Z

+ *
+ * @param WP_Query $query The WP_Query instance (passed by reference).
+ */
+function wp_random_content_pre_get_posts( $query ) {


Suggested change

function wp_random_content_pre_get_posts( $query ) {

function wp_random_content_pre_get_posts( $query ): void {

westonruter · 2026-10-06T00:44:19Z

+ *
+ * @global WP_Query $wp_query WordPress Query object.
+ */
+function wp_random_content_redirect() {


Suggested change

function wp_random_content_redirect() {

function wp_random_content_redirect(): void {

westonruter · 2026-10-06T00:44:50Z

+ * @param bool         $update      Optional. Whether this is an existing post being updated. Default false.
+ * @param WP_Post|null $post_before Optional. Post object before the update, null for new posts. Default null.
+ */
+function wp_random_content_flush_rewrite_rules_for_page( $post_id, $post, $update = false, $post_before = null ) {


Suggested change

function wp_random_content_flush_rewrite_rules_for_page( $post_id, $post, $update = false, $post_before = null ) {

function wp_random_content_flush_rewrite_rules_for_page( int $post_id, WP_Post $post, bool $update = false, ?WP_Post $post_before = null ): void {

peterwilsoncc · 2026-10-06T01:58:34Z

i forgot to mention: the db version will need a bump in order to trigger the upgrade routine and a rewrite rules update.

mukeshpanchal27 · 2026-10-06T03:30:34Z

+	 *
+	 * @return string[] Array of rewrite rules for random content redirects, keyed by their regex pattern.
+	 */
+	public function random_rewrite_rules() {


Suggested change

public function random_rewrite_rules() {

public function random_rewrite_rules(): array {

aaronjorbin requested review from annezazu and peterwilsoncc October 5, 2026 16:40

aaronjorbin commented Oct 5, 2026

View reviewed changes

Comment thread src/wp-includes/query.php Outdated

Fix phpstan suggestion

081f1eb

Parameter #2 $fallback_url of function wp_validate_redirect expects string, false given.

peterwilsoncc reviewed Oct 6, 2026

View reviewed changes

westonruter reviewed Oct 6, 2026

View reviewed changes

mukeshpanchal27 reviewed Oct 6, 2026

View reviewed changes

	* @param string[] $random_rewrite Array of rewrite rules for random content redirects, keyed by their regex pattern.
	* @param array<string, string> $random_rewrite Array of rewrite rules for random content redirects, keyed by their regex pattern.

	* @return string[] Array of rewrite rules for random content redirects, keyed by their regex pattern.
	* @return array<string, string> Array of rewrite rules for random content redirects, keyed by their regex pattern.

	function wp_is_random_content_query( $query ) {
	function wp_is_random_content_query( WP_Query $query ): bool {

	function wp_get_random_content_post_types( $query ) {
	function wp_get_random_content_post_types( WP_Query $query ): array {

	function wp_random_content_headers( $headers ) {
	function wp_random_content_headers( $headers ): array {

	function wp_is_random_content_redirect_enabled() {
	function wp_is_random_content_redirect_enabled(): bool {

	function wp_random_content_pre_get_posts( $query ) {
	function wp_random_content_pre_get_posts( $query ): void {

	function wp_random_content_redirect() {
	function wp_random_content_redirect(): void {

	function wp_random_content_flush_rewrite_rules_for_page( $post_id, $post, $update = false, $post_before = null ) {
	function wp_random_content_flush_rewrite_rules_for_page( int $post_id, WP_Post $post, bool $update = false, ?WP_Post $post_before = null ): void {

	public function random_rewrite_rules() {
	public function random_rewrite_rules(): array {

Conversation

aaronjorbin commented Oct 5, 2026

Use of AI Tools

Uh oh!

github-actions Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 5, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

annezazu commented Oct 5, 2026

Uh oh!

peterwilsoncc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterwilsoncc commented Oct 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Oct 5, 2026 •

edited

Loading