From 1fb0d8cfb793bceadaa49a8c53e81d81dab10f67 Mon Sep 17 00:00:00 2001
From: Christoph Bratschi <bratschi@appamics.com>
Date: Mon, 31 Aug 2026 23:33:29 +0200
Subject: [PATCH] Add filter for post preload URLs

---
 inc/preload.php                          | 24 ++++++++++-
 tests/php/integration/PreloadUrlTest.php | 54 ++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 tests/php/integration/PreloadUrlTest.php

diff --git a/inc/preload.php b/inc/preload.php
index 18ec4857..8a547218 100644
--- a/inc/preload.php
+++ b/inc/preload.php
@@ -120,6 +120,28 @@ function wpsc_update_idle_preload( $finish_time = null ) {
 	}
 }
 
+/**
+ * Gets the URL used to preload a post.
+ *
+ * @since $$next-version$$
+ *
+ * @param int $post_id Post ID.
+ * @return string|false The filtered post permalink, or false when no permalink is available.
+ */
+function wpsc_get_preload_post_url( $post_id ) {
+	$url = get_permalink( $post_id );
+
+	/**
+	 * Filters the URL used to preload a post.
+	 *
+	 * @since $$next-version$$
+	 *
+	 * @param string|false $url     The post permalink, or false when unavailable.
+	 * @param int          $post_id Post ID.
+	 */
+	return apply_filters( 'wpsc_preload_post_url', $url, $post_id );
+}
+
 function wp_cron_preload_cache() {
 	global $wpdb, $wp_cache_preload_interval, $wp_cache_preload_posts, $wp_cache_preload_email_me, $wp_cache_preload_email_volume, $cache_path, $wp_cache_preload_taxonomies;
 
@@ -338,7 +360,7 @@ function wp_cron_preload_cache() {
 			set_time_limit( 60 );
 			if ( $page_on_front != 0 && ( $post_id == $page_on_front || $post_id == $page_for_posts ) )
 				continue;
-			$url = get_permalink( $post_id );
+			$url = wpsc_get_preload_post_url( $post_id );
 
 			if ( ! is_string( $url ) ) {
 					wp_cache_debug( "wp_cron_preload_cache: skipped $post_id. Expected a URL, received: " . gettype( $url ) );
diff --git a/tests/php/integration/PreloadUrlTest.php b/tests/php/integration/PreloadUrlTest.php
new file mode 100644
index 00000000..12471971
--- /dev/null
+++ b/tests/php/integration/PreloadUrlTest.php
@@ -0,0 +1,54 @@
+<?php
+/**
+ * Integration tests for filtering post URLs during cache preloading.
+ *
+ * @package automattic/wp-super-cache
+ */
+class PreloadUrlTest extends WP_UnitTestCase {
+
+	public function set_up() {
+		parent::set_up();
+		remove_all_filters( 'wpsc_preload_post_url' );
+	}
+
+	public function tear_down() {
+		remove_all_filters( 'wpsc_preload_post_url' );
+		parent::tear_down();
+	}
+
+	/**
+	 * With no compatibility filter registered, the preload URL is unchanged.
+	 */
+	public function test_preload_url_defaults_to_the_post_permalink() {
+		$post_id   = self::factory()->post->create( array( 'post_status' => 'publish' ) );
+		$permalink = get_permalink( $post_id );
+
+		$this->assertSame( $permalink, wpsc_get_preload_post_url( $post_id ) );
+	}
+
+	/**
+	 * Compatibility plugins can provide a language-specific preload URL.
+	 */
+	public function test_preload_url_can_be_filtered_for_the_post() {
+		$post_id   = self::factory()->post->create( array( 'post_status' => 'publish' ) );
+		$permalink = get_permalink( $post_id );
+		$arguments = null;
+
+		add_filter(
+			'wpsc_preload_post_url',
+			static function ( $url, $filtered_post_id ) use ( &$arguments ) {
+				$arguments = array( $url, $filtered_post_id );
+
+				return add_query_arg( 'lang', 'fr', $url );
+			},
+			10,
+			2
+		);
+
+		$this->assertSame(
+			add_query_arg( 'lang', 'fr', $permalink ),
+			wpsc_get_preload_post_url( $post_id )
+		);
+		$this->assertSame( array( $permalink, $post_id ), $arguments );
+	}
+}