From 7b97d8c74e93f37b66827d3117499b94356ddb6a Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Tue, 30 May 2023 14:11:46 +0000
Subject: [PATCH] Docs: Add a `@since` tag for the `pre_wp_setup_nav_menu_item`
 filter.

Includes moving the unit test next to the other `wp_setup_nav_menu_item()` tests and using the `MockAction` class to confirm that the filter runs.

Follow-up to [55867].

Props TobiasBg.
Fixes #56577.

git-svn-id: https://develop.svn.wordpress.org/trunk@55868 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/nav-menu.php          |  6 ++-
 tests/phpunit/tests/post/nav-menu.php | 53 +++++++++++++--------------
 2 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/src/wp-includes/nav-menu.php b/src/wp-includes/nav-menu.php
index cb49f2b38c..229ba8496b 100644
--- a/src/wp-includes/nav-menu.php
+++ b/src/wp-includes/nav-menu.php
@@ -822,10 +822,12 @@ function update_menu_item_cache( $menu_items ) {
 function wp_setup_nav_menu_item( $menu_item ) {
 
 	/**
-	 * Short-circuit the wp_setup_nav_menu_item() output.
+	 * Filters whether to short-circuit the wp_setup_nav_menu_item() output.
 	 *
 	 * Returning a non-null value from the filter will short-circuit wp_setup_nav_menu_item(),
-	 * and return that value.
+	 * returning that value instead.
+	 *
+	 * @since 6.3.0
 	 *
 	 * @param object|null $modified_menu_item Modified menu item. Default null.
 	 * @param object      $menu_item          The menu item to modify.
diff --git a/tests/phpunit/tests/post/nav-menu.php b/tests/phpunit/tests/post/nav-menu.php
index 0768e09666..9d1cffe069 100644
--- a/tests/phpunit/tests/post/nav-menu.php
+++ b/tests/phpunit/tests/post/nav-menu.php
@@ -591,6 +591,31 @@ class Tests_Post_Nav_Menu extends WP_UnitTestCase {
 		$this->assertTrue( ! _is_valid_nav_menu_item( $menu_item ) );
 	}
 
+	/**
+	 * @ticket 56577
+	 */
+	public function test_wp_setup_nav_menu_item_short_circuit_filter() {
+		$post_id = self::factory()->post->create();
+
+		$menu_item_id = wp_update_nav_menu_item(
+			$this->menu_id,
+			0,
+			array(
+				'menu-item-type'      => 'post_type',
+				'menu-item-object'    => 'post',
+				'menu-item-object-id' => $post_id,
+				'menu-item-status'    => 'publish',
+			)
+		);
+
+		$filter = new MockAction();
+		add_filter( 'pre_wp_setup_nav_menu_item', array( &$filter, 'filter' ) );
+
+		wp_setup_nav_menu_item( get_post( $menu_item_id ) );
+
+		$this->assertSame( 1, $filter->get_call_count() );
+	}
+
 	/**
 	 * @ticket 35206
 	 */
@@ -1344,32 +1369,4 @@ class Tests_Post_Nav_Menu extends WP_UnitTestCase {
 		$post = get_post( $menu_item_id );
 		$this->assertEqualsWithDelta( strtotime( gmdate( 'Y-m-d H:i:s' ) ), strtotime( $post->post_date ), 2, 'The dates should be equal' );
 	}
-
-	/**
-	 * @ticket 56577
-	 */
-	public function test_nav_menu_item_short_circuit_filter() {
-		// Create a nav menu item.
-		$menu_item_args = array(
-			'menu-item-type'   => 'custom',
-			'menu-item-title'  => 'Wordpress.org',
-			'menu-item-url'    => 'http://wordpress.org',
-			'menu-item-status' => 'publish',
-		);
-
-		$custom_item_id = wp_update_nav_menu_item( 0, 0, $menu_item_args );
-
-		$pre_setup_callback = function() {
-			return '--empty nav menu item--';
-		};
-
-		add_filter( 'pre_wp_setup_nav_menu_item', $pre_setup_callback );
-
-		// Confirm the short-circuit.
-		$custom_item = wp_setup_nav_menu_item( get_post( $custom_item_id ) );
-		$this->assertSame( '--empty nav menu item--', $custom_item );
-
-		remove_filter( 'pre_wp_setup_nav_menu_item', $pre_setup_callback );
-	}
-
 }