Posts, Post Types: Introduce post_type_archive_description()

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.
  *

tests/phpunit/tests/general/postTypeArchiveDescription.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * @group general
+ * @group template
+ */
+class Tests_General_PostTypeArchiveDescription extends WP_UnitTestCase {
+	public function set_up() {
+		parent::set_up();
+		register_post_type(
+			'cpt_with_desc',
+			array(
+				'public'      => 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}";
+	}
+}