From 38232f655df8d010c2e99b6b5c5a14bc27ec71d3 Mon Sep 17 00:00:00 2001
From: Jake Spurlock <whyisjake@git.wordpress.org>
Date: Tue, 8 Jun 2021 23:12:22 +0000
Subject: [PATCH] Media: Add new functions to return the previous/next
 attachment links.

New functions:

* get_adjacent_image_link()
* get_next_image_link()
* get_previous_image_link()

Fixes #45708.

Props flixos90, DrewAPicture, mor10, antpb, hellofromTonya, whyisjake.




git-svn-id: https://develop.svn.wordpress.org/trunk@51122 602fd350-edb4-49c9-b593-d223f7449a82
---
 phpcs.xml.dist                                |  1 +
 src/wp-includes/media.php                     | 65 +++++++++++---
 .../tests/media/getAdjacentImageLink.php      | 88 +++++++++++++++++++
 .../phpunit/tests/media/getNextImageLink.php  | 57 ++++++++++++
 .../tests/media/getPreviousImageLink.php      | 57 ++++++++++++
 tests/phpunit/tests/media/nextImageLink.php   | 56 ++++++++++++
 .../phpunit/tests/media/previousImageLink.php | 56 ++++++++++++
 .../media/testcase-adjacent-image-link.php    | 70 +++++++++++++++
 8 files changed, 440 insertions(+), 10 deletions(-)
 create mode 100644 tests/phpunit/tests/media/getAdjacentImageLink.php
 create mode 100644 tests/phpunit/tests/media/getNextImageLink.php
 create mode 100644 tests/phpunit/tests/media/getPreviousImageLink.php
 create mode 100644 tests/phpunit/tests/media/nextImageLink.php
 create mode 100644 tests/phpunit/tests/media/previousImageLink.php
 create mode 100644 tests/phpunit/tests/media/testcase-adjacent-image-link.php

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 0f15b16849..d09abc947c 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -249,6 +249,7 @@
 				<element value="WP_Import_UnitTestCase"/>
 				<element value="Tests_Query_Conditionals"/>
 				<element value="WP_Test_XML_TestCase"/>
+				<element value="WP_Test_Adjacent_Image_Link_TestCase"/>
 
 				<!-- Mock classes. -->
 				<element value="Spy_REST_Server"/>
diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index 19fa2b8b9d..4a9849d3ca 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -3376,19 +3376,49 @@ function wp_video_shortcode( $attr, $content = '' ) {
 }
 add_shortcode( 'video', 'wp_video_shortcode' );
 
+/**
+ * Gets the previous image link that has the same post parent.
+ *
+ * @since 5.8.0
+ *
+ * @see get_adjacent_image_link()
+ *
+ * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
+ *                           of width and height values in pixels (in that order). Default 'thumbnail'.
+ * @param string|false $text Optional. Link text. Default false.
+ * @return string Markup for previous image link.
+ */
+function get_previous_image_link( $size = 'thumbnail', $text = false ) {
+	return get_adjacent_image_link( true, $size, $text );
+}
+
 /**
  * Displays previous image link that has the same post parent.
  *
  * @since 2.5.0
  *
- * @see adjacent_image_link()
- *
  * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
  *                           of width and height values in pixels (in that order). Default 'thumbnail'.
  * @param string|false $text Optional. Link text. Default false.
  */
 function previous_image_link( $size = 'thumbnail', $text = false ) {
-	adjacent_image_link( true, $size, $text );
+	echo get_previous_image_link( $size, $text );
+}
+
+/**
+ * Gets the next image link that has the same post parent.
+ *
+ * @since 5.8.0
+ *
+ * @see get_adjacent_image_link()
+ *
+ * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
+ *                           of width and height values in pixels (in that order). Default 'thumbnail'.
+ * @param string|false $text Optional. Link text. Default false.
+ * @return string Markup for next image link.
+ */
+function get_next_image_link( $size = 'thumbnail', $text = false ) {
+	return get_adjacent_image_link( false, $size, $text );
 }
 
 /**
@@ -3396,29 +3426,28 @@ function previous_image_link( $size = 'thumbnail', $text = false ) {
  *
  * @since 2.5.0
  *
- * @see adjacent_image_link()
- *
  * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
  *                           of width and height values in pixels (in that order). Default 'thumbnail'.
  * @param string|false $text Optional. Link text. Default false.
  */
 function next_image_link( $size = 'thumbnail', $text = false ) {
-	adjacent_image_link( false, $size, $text );
+	echo get_next_image_link( $size, $text );
 }
 
 /**
- * Displays next or previous image link that has the same post parent.
+ * Gets the next or previous image link that has the same post parent.
  *
  * Retrieves the current attachment object from the $post global.
  *
- * @since 2.5.0
+ * @since 5.8.0
  *
  * @param bool         $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
  * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
  *                           of width and height values in pixels (in that order). Default 'thumbnail'.
  * @param bool         $text Optional. Link text. Default false.
+ * @return string Markup for image link.
  */
-function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
+function get_adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
 	$post        = get_post();
 	$attachments = array_values(
 		get_children(
@@ -3473,7 +3502,23 @@ function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false )
 	 *                              an array of width and height values in pixels (in that order).
 	 * @param string $text          Link text.
 	 */
-	echo apply_filters( "{$adjacent}_image_link", $output, $attachment_id, $size, $text );
+	return apply_filters( "{$adjacent}_image_link", $output, $attachment_id, $size, $text );
+}
+
+/**
+ * Displays next or previous image link that has the same post parent.
+ *
+ * Retrieves the current attachment object from the $post global.
+ *
+ * @since 2.5.0
+ *
+ * @param bool         $prev Optional. Whether to display the next (false) or previous (true) link. Default true.
+ * @param string|int[] $size Optional. Image size. Accepts any registered image size name, or an array
+ *                           of width and height values in pixels (in that order). Default 'thumbnail'.
+ * @param bool         $text Optional. Link text. Default false.
+ */
+function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
+	echo get_adjacent_image_link( $prev, $size, $text );
 }
 
 /**
diff --git a/tests/phpunit/tests/media/getAdjacentImageLink.php b/tests/phpunit/tests/media/getAdjacentImageLink.php
new file mode 100644
index 0000000000..3f3d6c3c28
--- /dev/null
+++ b/tests/phpunit/tests/media/getAdjacentImageLink.php
@@ -0,0 +1,88 @@
+<?php
+
+require_once __DIR__ . '/testcase-adjacent-image-link.php';
+
+/**
+ * @group  media
+ * @covers ::get_adjacent_image_link
+ */
+class Tests_Media_GetAdjacentImageLink extends WP_Test_Adjacent_Image_Link_TestCase {
+	protected $default_args = array(
+		'prev' => true,
+		'size' => 'thumbnail',
+		'text' => false,
+	);
+
+	/**
+	 * @ticket 45708
+	 *
+	 * @dataProvider data_get_adjacent_image_link
+	 */
+	function test_get_adjacent_image_link( $current_attachment_index, $expected_attachment_index, $expected, array $args = array() ) {
+		list( $expected, $args ) = $this->setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, $args );
+
+		$actual = get_adjacent_image_link( ...$args );
+
+		$this->assertSame( $expected, $actual );
+	}
+
+	public function data_get_adjacent_image_link() {
+		return array(
+			// Happy paths.
+			'when has previous link'           => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image2.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+			),
+			'with text when has previous link' => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+			'when has next link'               => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image5.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+				'args'                      => array( 'prev' => false ),
+			),
+			'with text when has next link'     => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array(
+					'prev' => false,
+					'text' => 'Some text',
+				),
+			),
+
+			// Unhappy paths.
+			'when no previous link'            => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+			),
+			'with text when no previous link'  => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+			'when no next link'                => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'prev' => false ),
+			),
+			'with text when no next link'      => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array(
+					'prev' => false,
+					'text' => 'Some text',
+				),
+			),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/media/getNextImageLink.php b/tests/phpunit/tests/media/getNextImageLink.php
new file mode 100644
index 0000000000..484f13ddf9
--- /dev/null
+++ b/tests/phpunit/tests/media/getNextImageLink.php
@@ -0,0 +1,57 @@
+<?php
+
+require_once __DIR__ . '/testcase-adjacent-image-link.php';
+
+/**
+ * @group  media
+ * @covers ::get_next_image_link
+ */
+class Tests_Media_GetNextImageLink extends WP_Test_Adjacent_Image_Link_TestCase {
+	protected $default_args = array(
+		'size' => 'thumbnail',
+		'text' => false,
+	);
+
+	/**
+	 * @ticket 45708
+	 *
+	 * @dataProvider data_get_next_image_link
+	 */
+	function test_get_next_image_link( $current_attachment_index, $expected_attachment_index = 0, $expected, array $args = array() ) {
+		list( $expected, $args ) = $this->setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, $args );
+
+		$actual = get_next_image_link( ...$args );
+
+		$this->assertSame( $expected, $actual );
+	}
+
+	public function data_get_next_image_link() {
+		return array(
+			// Happy paths.
+			'when has next link'           => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image5.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+			),
+			'with text when has next link' => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+
+			// Unhappy paths.
+			'when no next link'            => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+			),
+			'with text when no next link'  => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/media/getPreviousImageLink.php b/tests/phpunit/tests/media/getPreviousImageLink.php
new file mode 100644
index 0000000000..9c98c883cc
--- /dev/null
+++ b/tests/phpunit/tests/media/getPreviousImageLink.php
@@ -0,0 +1,57 @@
+<?php
+
+require_once __DIR__ . '/testcase-adjacent-image-link.php';
+
+/**
+ * @group  media
+ * @covers ::get_previous_image_link
+ */
+class Tests_Media_GetPreviousImageLink extends WP_Test_Adjacent_Image_Link_TestCase {
+	protected $default_args = array(
+		'size' => 'thumbnail',
+		'text' => false,
+	);
+
+	/**
+	 * @ticket 45708
+	 *
+	 * @dataProvider data_get_previous_image_link
+	 */
+	function test_get_previous_image_link( $current_attachment_index, $expected_attachment_index = 0, $expected, array $args = array() ) {
+		list( $expected, $args ) = $this->setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, $args );
+
+		$actual = get_previous_image_link( ...$args );
+
+		$this->assertSame( $expected, $actual );
+	}
+
+	public function data_get_previous_image_link() {
+		return array(
+			// Happy paths.
+			'when has previous link'           => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image2.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+			),
+			'with text when has previous link' => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+
+			// Unhappy paths.
+			'when no previous link'            => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+			),
+			'with text when no previous link'  => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/media/nextImageLink.php b/tests/phpunit/tests/media/nextImageLink.php
new file mode 100644
index 0000000000..fc4527f49e
--- /dev/null
+++ b/tests/phpunit/tests/media/nextImageLink.php
@@ -0,0 +1,56 @@
+<?php
+
+require_once __DIR__ . '/testcase-adjacent-image-link.php';
+
+/**
+ * @group  media
+ * @covers ::next_image_link
+ */
+class Tests_Media_NextImageLink extends WP_Test_Adjacent_Image_Link_TestCase {
+	protected $default_args = array(
+		'size' => 'thumbnail',
+		'text' => false,
+	);
+
+	/**
+	 * @ticket 45708
+	 *
+	 * @dataProvider data_next_image_link
+	 */
+	function test_next_image_link( $current_attachment_index, $expected_attachment_index = 0, $expected, array $args = array() ) {
+		list( $expected, $args ) = $this->setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, $args );
+
+		$this->expectOutputString( $expected );
+		$this->assertNull( next_image_link( ...$args ) );
+	}
+
+	public function data_next_image_link() {
+		return array(
+			// Happy paths.
+			'when has next link'           => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image5.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+			),
+			'with text when has next link' => array(
+				'current_attachment_index'  => 4,
+				'expected_attachment_index' => 5,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+
+			// Unhappy paths.
+			'when no next link'            => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+			),
+			'with text when no next link'  => array(
+				'current_attachment_index'  => 5,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/media/previousImageLink.php b/tests/phpunit/tests/media/previousImageLink.php
new file mode 100644
index 0000000000..7cdb24e0bf
--- /dev/null
+++ b/tests/phpunit/tests/media/previousImageLink.php
@@ -0,0 +1,56 @@
+<?php
+
+require_once __DIR__ . '/testcase-adjacent-image-link.php';
+
+/**
+ * @group  media
+ * @covers ::previous_image_link
+ */
+class Tests_Media_PreviousImageLink extends WP_Test_Adjacent_Image_Link_TestCase {
+	protected $default_args = array(
+		'size' => 'thumbnail',
+		'text' => false,
+	);
+
+	/**
+	 * @ticket 45708
+	 *
+	 * @dataProvider data_previous_image_link
+	 */
+	function test_previous_image_link( $current_attachment_index, $expected_attachment_index = 0, $expected, array $args = array() ) {
+		list( $expected, $args ) = $this->setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, $args );
+
+		$this->expectOutputString( $expected );
+		$this->assertNull( previous_image_link( ...$args ) );
+	}
+
+	public function data_previous_image_link() {
+		return array(
+			// Happy paths.
+			'when has previous link'           => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'><img width="1" height="1" src="http://example.org/wp-content/uploads/image2.jpg" class="attachment-thumbnail size-thumbnail" alt="" loading="lazy" /></a>',
+			),
+			'with text when has previous link' => array(
+				'current_attachment_index'  => 3,
+				'expected_attachment_index' => 2,
+				'expected'                  => '<a href=\'http://example.org/?attachment_id=%%ID%%\'>Some text</a>',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+
+			// Unhappy paths.
+			'when no previous link'            => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+			),
+			'with text when no previous link'  => array(
+				'current_attachment_index'  => 1,
+				'expected_attachment_index' => 0,
+				'expected'                  => '',
+				'args'                      => array( 'text' => 'Some text' ),
+			),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/media/testcase-adjacent-image-link.php b/tests/phpunit/tests/media/testcase-adjacent-image-link.php
new file mode 100644
index 0000000000..57ba20c08e
--- /dev/null
+++ b/tests/phpunit/tests/media/testcase-adjacent-image-link.php
@@ -0,0 +1,70 @@
+<?php
+
+abstract class WP_Test_Adjacent_Image_Link_TestCase extends WP_UnitTestCase {
+	/**
+	 * Array of 5 attachments for use in the tests.
+	 *
+	 * @var init{}|WP_Error[]
+	 */
+	protected static $attachments;
+
+	/**
+	 * Default args for the function being tested.
+	 *
+	 * Defined in each test class.
+	 *
+	 * @var int[]|WP_Error[] Array of attachment IDs.
+	 */
+	protected $default_args = array();
+
+	/**
+	 * Setup the tests after the data provider but before the tests start.
+	 *
+	 * @param WP_UnitTest_Factory $factory Instance of the factory.
+	 */
+	public static function wpSetUpBeforeClass( WP_UnitTest_Factory $factory ) {
+		$parent_id = $factory->post->create();
+
+		for ( $index = 1; $index <= 5; $index++ ) {
+			self::$attachments[ $index ] = $factory->attachment->create_object(
+				"image{$index}.jpg",
+				$parent_id,
+				array(
+					'post_mime_type' => 'image/jpeg',
+					'post_type'      => 'attachment',
+				)
+			);
+		}
+	}
+
+	/**
+	 * Sets up the test scenario.
+	 *
+	 * @param integer $current_attachment_index  Current attachment's index number in the self::$attachments array.
+	 * @param integer $expected_attachment_index Expected attachment's index number in the self::$attachments array.
+	 * @param string  $expected                  The expected output string.
+	 * @param array   $args                      Array of arguments to pass to the function being tested.
+	 * @return array {
+	 *     Array of the prepared test parameters.
+	 *
+	 *     @var string $expected Expected output string.
+	 *     @var array  $args     All of the arguments to pass to the function being tested.
+	 * }
+	 */
+	protected function setup_test_scenario( $current_attachment_index, $expected_attachment_index, $expected, array $args = array() ) {
+		// This prep code allows the data provider to specify the different arguments needed for the test scenario.
+		$args = array_merge( $this->default_args, $args );
+		$args = array_values( $args );
+
+		// Replace the attachment ID placeholder.
+		if ( isset( self::$attachments[ $expected_attachment_index ] ) ) {
+			$expected = str_replace( '%%ID%%', self::$attachments[ $expected_attachment_index ], $expected );
+		}
+
+		// Go to the current attachment to set the state for the tests.
+		$this->go_to( get_permalink( self::$attachments[ $current_attachment_index ] ) );
+
+		// Return the changed parameters.
+		return array( $expected, $args );
+	}
+}