diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php index 121cc4a4c0c48..b212becaf0971 100644 --- a/src/wp-includes/general-template.php +++ b/src/wp-includes/general-template.php @@ -1558,6 +1558,59 @@ function post_type_archive_title( $prefix = '', $display = true ) { } } +/** + * Displays or retrieves the description for a post type archive. + * + * This is optimized for archive.php and archive-{$post_type}.php template files + * for displaying the description of the post type. + * + * @since 7.1.0 + * + * @param string $post_type Optional. Post type. + * @param bool $display Optional. Whether to display or retrieve description. Default true. + * @return string|void Description when retrieving, void when displaying or on failure. + */ +function post_type_archive_description( $post_type = '', $display = true ) { + if ( is_bool( $post_type ) ) { + $display = $post_type; + $post_type = ''; + } + + if ( ! $post_type && ! is_post_type_archive() ) { + return; + } + + if ( ! $post_type ) { + $post_type = get_query_var( 'post_type' ); + if ( is_array( $post_type ) ) { + $post_type = reset( $post_type ); + } + } + + $post_type_obj = get_post_type_object( $post_type ); + if ( ! $post_type_obj ) { + return; + } + + $description = $post_type_obj->description; + + /** + * Filters the post type archive description. + * + * @since 7.1.0 + * + * @param string $description Post type 'description' argument. + * @param string $post_type Post type. + */ + $description = apply_filters( 'post_type_archive_description', $description, $post_type ); + + if ( $display ) { + echo $description; + } else { + return $description; + } +} + /** * Displays or retrieves page title for category archive. * diff --git a/tests/phpunit/tests/general/postTypeArchiveDescription.php b/tests/phpunit/tests/general/postTypeArchiveDescription.php new file mode 100644 index 0000000000000..01e4aec47529e --- /dev/null +++ b/tests/phpunit/tests/general/postTypeArchiveDescription.php @@ -0,0 +1,53 @@ + true, + 'has_archive' => true, + 'description' => 'This is a test description.', + ) + ); + register_post_type( + 'cpt_no_desc', + array( + 'public' => true, + 'has_archive' => true, + ) + ); + } + + public function test_post_type_archive_description_echoes_by_default() { + $this->go_to( get_post_type_archive_link( 'cpt_with_desc' ) ); + $this->assertTrue( is_post_type_archive() ); + $this->expectOutputString( 'This is a test description.' ); + post_type_archive_description(); + } + + public function test_post_type_archive_description_no_desc() { + $this->go_to( get_post_type_archive_link( 'cpt_no_desc' ) ); + $this->assertSame( '', post_type_archive_description( '', false ) ); + } + + public function test_post_type_archive_description_with_passed_post_type() { + $this->assertSame( 'This is a test description.', post_type_archive_description( 'cpt_with_desc', false ) ); + } + + public function test_post_type_archive_description_filter() { + add_filter( 'post_type_archive_description', array( $this, 'filter_description' ), 10, 2 ); + $desc = post_type_archive_description( 'cpt_with_desc', false ); + remove_filter( 'post_type_archive_description', array( $this, 'filter_description' ) ); + + $this->assertSame( 'Filtered desc: cpt_with_desc', $desc ); + } + + public function filter_description( $desc, $post_type ) { + return "Filtered desc: {$post_type}"; + } +}