From fed211f327f09450de8eaa1d1cbdd7d2393ad362 Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Mon, 13 Jul 2026 23:39:19 +0530 Subject: [PATCH 1/2] Posts, Post Types: Introduce post_type_archive_description() to display or retrieve the description for a post type archive. --- src/wp-includes/general-template.php | 53 ++++++++++++++++ .../general/postTypeArchiveDescription.php | 63 +++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 tests/phpunit/tests/general/postTypeArchiveDescription.php diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php index e7640720d3c73..ace62ac143659 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..a1349ed7090eb --- /dev/null +++ b/tests/phpunit/tests/general/postTypeArchiveDescription.php @@ -0,0 +1,63 @@ + 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_returns() { + $this->go_to( get_post_type_archive_link( 'cpt_with_desc' ) ); + $this->assertSame( 'This is a test description.', post_type_archive_description( '', false ) ); + } + + 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_with_passed_post_type_echoes() { + $this->expectOutputString( 'This is a test description.' ); + post_type_archive_description( 'cpt_with_desc' ); + } + + 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}"; + } +} From 619873e18b143b5d0085f5fe791dd54804080d53 Mon Sep 17 00:00:00 2001 From: Sainath Poojary Date: Mon, 13 Jul 2026 23:39:19 +0530 Subject: [PATCH 2/2] Tests: Add unit tests for post_type_archive_description(). --- .../tests/general/postTypeArchiveDescription.php | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/tests/phpunit/tests/general/postTypeArchiveDescription.php b/tests/phpunit/tests/general/postTypeArchiveDescription.php index a1349ed7090eb..01e4aec47529e 100644 --- a/tests/phpunit/tests/general/postTypeArchiveDescription.php +++ b/tests/phpunit/tests/general/postTypeArchiveDescription.php @@ -30,11 +30,6 @@ public function test_post_type_archive_description_echoes_by_default() { post_type_archive_description(); } - public function test_post_type_archive_description_returns() { - $this->go_to( get_post_type_archive_link( 'cpt_with_desc' ) ); - $this->assertSame( 'This is a test description.', post_type_archive_description( '', false ) ); - } - 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 ) ); @@ -44,11 +39,6 @@ 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_with_passed_post_type_echoes() { - $this->expectOutputString( 'This is a test description.' ); - post_type_archive_description( 'cpt_with_desc' ); - } - 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 );