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 @@
+
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 @@
+ 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' => '
',
+ ),
+ 'with text when has previous link' => array(
+ 'current_attachment_index' => 3,
+ 'expected_attachment_index' => 2,
+ 'expected' => 'Some text',
+ 'args' => array( 'text' => 'Some text' ),
+ ),
+ 'when has next link' => array(
+ 'current_attachment_index' => 4,
+ 'expected_attachment_index' => 5,
+ 'expected' => '
',
+ 'args' => array( 'prev' => false ),
+ ),
+ 'with text when has next link' => array(
+ 'current_attachment_index' => 4,
+ 'expected_attachment_index' => 5,
+ 'expected' => 'Some text',
+ '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 @@
+ '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' => '
',
+ ),
+ 'with text when has next link' => array(
+ 'current_attachment_index' => 4,
+ 'expected_attachment_index' => 5,
+ 'expected' => 'Some text',
+ '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 @@
+ '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' => '
',
+ ),
+ 'with text when has previous link' => array(
+ 'current_attachment_index' => 3,
+ 'expected_attachment_index' => 2,
+ 'expected' => 'Some text',
+ '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 @@
+ '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' => '
',
+ ),
+ 'with text when has next link' => array(
+ 'current_attachment_index' => 4,
+ 'expected_attachment_index' => 5,
+ 'expected' => 'Some text',
+ '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 @@
+ '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' => '
',
+ ),
+ 'with text when has previous link' => array(
+ 'current_attachment_index' => 3,
+ 'expected_attachment_index' => 2,
+ 'expected' => 'Some text',
+ '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 @@
+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 );
+ }
+}