Docs: Improve docblocks and types for WP_Screen properties.

* Correctly hint that `WP_Screen::$_show_screen_options` is null before being instantiated.
* Correctly hint that `::get_option()`, `get_help_tab()` and `get_screen_reader_text()` can return null.
* Ensure `$this->columns` is an `int`, by casting `$this->get_option( 'layout_columns', 'default' )` from its numeric string.

Developed in https://github.com/WordPress/wordpress-develop/pull/8860

Props justlevine, peterwilsoncc, westonruter.
See #64238, #64224.

Built from https://develop.svn.wordpress.org/trunk@61300


git-svn-id: http://core.svn.wordpress.org/trunk@60612 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/class-wp-screen.php

@@ -175,8 +175,10 @@ final class WP_Screen {
 	/**
 	 * Stores the result of the public show_screen_options function.
 	 *
+	 * Set when calling {@see self::show_screen_options()} for the first time.
+	 *
 	 * @since 3.3.0
-	 * @var bool
+	 * @var ?bool
 	 */
 	private $_show_screen_options;
 
@@ -545,7 +547,7 @@ final class WP_Screen {
 	 * @param string       $option Option name.
 	 * @param string|false $key    Optional. Specific array key for when the option is an array.
 	 *                             Default false.
-	 * @return string The option value if set, null otherwise.
+	 * @return ?string The option value if set, null otherwise.
 	 */
 	public function get_option( $option, $key = false ) {
 		if ( ! isset( $this->_options[ $option ] ) ) {
@@ -598,7 +600,7 @@ final class WP_Screen {
 	 * @since 3.4.0
 	 *
 	 * @param string $id Help Tab ID.
-	 * @return array Help tab arguments.
+	 * @return ?array Help tab arguments, or null if no help tabs added.
 	 */
 	public function get_help_tab( $id ) {
 		if ( ! isset( $this->_help_tabs[ $id ] ) ) {
@@ -733,7 +735,7 @@ final class WP_Screen {
 	 * @since 4.4.0
 	 *
 	 * @param string $key Screen reader text array named key.
-	 * @return string Screen reader text string.
+	 * @return ?string Screen reader text string, or null if no text is associated with the key.
 	 */
 	public function get_screen_reader_text( $key ) {
 		if ( ! isset( $this->_screen_reader_content[ $key ] ) ) {
@@ -949,8 +951,9 @@ final class WP_Screen {
 		if ( $this->get_option( 'layout_columns' ) ) {
 			$this->columns = (int) get_user_option( "screen_layout_$this->id" );
 
-			if ( ! $this->columns && $this->get_option( 'layout_columns', 'default' ) ) {
-				$this->columns = $this->get_option( 'layout_columns', 'default' );
+			$layout_columns = (int) $this->get_option( 'layout_columns', 'default' );
+			if ( ! $this->columns && $layout_columns ) {
+				$this->columns = $layout_columns;
 			}
 		}
 		$GLOBALS['screen_layout_columns'] = $this->columns; // Set the global for back-compat.

wp-admin/includes/image.php

@@ -827,7 +827,13 @@ function wp_read_image_metadata( $file ) {
 		return false;
 	}
 
-	list( , , $image_type ) = wp_getimagesize( $file );
+	$image_size = wp_getimagesize( $file );
+
+	if ( false === $image_size ) {
+		return false;
+	}
+
+	list( , , $image_type ) = $image_size;
 
 	/*
 	 * EXIF contains a bunch of data we'll probably never need formatted in ways

wp-admin/includes/taxonomy.php

@@ -48,19 +48,19 @@ function get_category_to_edit( $id ) {
  *
  * @since 2.0.0
  *
- * @param int|string $cat_name        Category name.
- * @param int        $category_parent Optional. ID of parent category.
- * @return int|WP_Error
+ * @param string $category_name   Category name.
+ * @param int    $category_parent Optional. ID of parent category.
+ * @return int The ID of category term on success, or zero on failure.
  */
-function wp_create_category( $cat_name, $category_parent = 0 ) {
-	$id = category_exists( $cat_name, $category_parent );
+function wp_create_category( $category_name, $category_parent = 0 ) {
+	$id = category_exists( $category_name, $category_parent );
 	if ( $id ) {
-		return $id;
+		return (int) $id;
 	}
 
 	return wp_insert_category(
 		array(
-			'cat_name'        => $cat_name,
+			'cat_name'        => $category_name,
 			'category_parent' => $category_parent,
 		)
 	);

wp-content/themes/twentynineteen/sass/blocks/_blocks.scss

@@ -436,6 +436,10 @@
 			}
 		}
 
+		&.has-text-color cite {
+			color: inherit;
+		}
+
 		&.is-style-solid-color {
 			background-color: $color__link;
 			padding-left: 0;

wp-content/themes/twentynineteen/style-editor.css

@@ -1103,6 +1103,12 @@ figcaption,
   color: #767676;
 }
 
+.wp-block-pullquote.has-text-color .wp-block-pullquote__citation,
+.wp-block-pullquote.has-primary-background-color blockquote p,
+.wp-block-pullquote.has-dark-gray-background-color blockquote p {
+  color: inherit;
+}
+
 .wp-block-pullquote.is-style-solid-color blockquote {
   width: calc(100% - (2 * 1rem));
   max-width: calc( 100% - (2 * 1rem));

wp-content/themes/twentynineteen/style-editor.scss

@@ -515,6 +515,12 @@ figcaption,
 		color: $color__text-light;
 	}
 
+	&.has-text-color .wp-block-pullquote__citation,
+	&.has-primary-background-color blockquote p,
+	&.has-dark-gray-background-color blockquote p {
+		color: inherit;
+	}
+
 	&.is-style-solid-color {
 
 		blockquote {

wp-content/themes/twentynineteen/style-rtl.css

@@ -5758,6 +5758,10 @@ body.page .main-navigation {
   margin-top: 0;
 }
 
+.entry .entry-content .wp-block-pullquote.has-text-color cite {
+  color: inherit;
+}
+
 .entry .entry-content .wp-block-pullquote.is-style-solid-color {
   background-color: #0073aa;
   padding-right: 0;

wp-content/themes/twentynineteen/style.css

@@ -5770,6 +5770,10 @@ body.page .main-navigation {
   margin-top: 0;
 }
 
+.entry .entry-content .wp-block-pullquote.has-text-color cite {
+  color: inherit;
+}
+
 .entry .entry-content .wp-block-pullquote.is-style-solid-color {
   background-color: #0073aa;
   padding-left: 0;

wp-includes/block-supports/block-visibility.php

@@ -19,7 +19,7 @@
 function wp_render_block_visibility_support( $block_content, $block ) {
 	$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
 
-	if ( ! $block_type || ! block_has_support( $block_type, 'blockVisibility', true ) ) {
+	if ( ! $block_type || ! block_has_support( $block_type, 'visibility', true ) ) {
 		return $block_content;
 	}
 

wp-includes/class-wp-block-processor.php

@@ -194,7 +194,7 @@
  * block, and re-serialize it into the original document. It’s possible to do so
  * while skipping over the parse of the rest of the document.
  *
- * {@see self::extract_block()} will scan forward from the current block opener
+ * {@see self::extract_full_block_and_advance()} will scan forward from the current block opener
  * and build the parsed block structure until the current block is closed. It will
  * include all inner HTML and inner blocks, and parse all of the inner blocks. It
  * can be used to extract a block at any depth in the document, helpful for operating
@@ -207,7 +207,7 @@
  *     }
  *
  *     $gallery_at    = $processor->get_span()->start;
- *     $gallery_block = $processor->extract_block();
+ *     $gallery_block = $processor->extract_full_block_and_advance();
  *     $after_gallery = $processor->get_span()->start;
  *     return (
  *         substr( $post_content, 0, $gallery_at ) .
@@ -1223,7 +1223,7 @@ class WP_Block_Processor {
 	 *     }
 	 *
 	 *     $gallery_at  = $processor->get_span()->start;
-	 *     $gallery     = $processor->extract_block();
+	 *     $gallery     = $processor->extract_full_block_and_advance();
 	 *     $ends_before = $processor->get_span();
 	 *     $ends_before = $ends_before->start ?? strlen( $post_content );
 	 *
@@ -1254,7 +1254,7 @@ class WP_Block_Processor {
 	 *     }
 	 * }
 	 */
-	public function extract_block(): ?array {
+	public function extract_full_block_and_advance(): ?array {
 		if ( $this->is_html() ) {
 			$chunk = $this->get_html_content();
 
@@ -1291,7 +1291,7 @@ class WP_Block_Processor {
 			 * @todo Use iteration instead of recursion, or at least refactor to tail-call form.
 			 */
 			if ( $this->opens_block() ) {
-				$inner_block             = $this->extract_block();
+				$inner_block             = $this->extract_full_block_and_advance();
 				$block['innerBlocks'][]  = $inner_block;
 				$block['innerContent'][] = null;
 			}

wp-includes/class-wp-dependencies.php

@@ -91,7 +91,7 @@ class WP_Dependencies {
 	 *
 	 * @since 5.4.0
 	 *
-	 * @var array
+	 * @var ?array<string, true>
 	 */
 	private $all_queued_deps;
 

wp-includes/class-wp-duotone.php

@@ -52,7 +52,7 @@ class WP_Duotone {
 	 *
 	 * @since 6.3.0
 	 *
-	 * @var array
+	 * @var ?array
 	 */
 	private static $global_styles_block_names;
 
@@ -76,7 +76,7 @@ class WP_Duotone {
 	 *
 	 * @since 6.3.0
 	 *
-	 * @var array
+	 * @var ?array
 	 */
 	private static $global_styles_presets;
 

wp-includes/class-wp-query.php

@@ -22,7 +22,7 @@ class WP_Query {
 	 * Query vars set by the user.
 	 *
 	 * @since 1.5.0
-	 * @var array
+	 * @var ?array
 	 */
 	public $query;
 
@@ -72,7 +72,7 @@ class WP_Query {
 	 * The ID of the queried object.
 	 *
 	 * @since 1.5.0
-	 * @var int
+	 * @var ?int
 	 */
 	public $queried_object_id;
 
@@ -80,7 +80,7 @@ class WP_Query {
 	 * SQL for the database query.
 	 *
 	 * @since 2.0.1
-	 * @var string
+	 * @var ?string
 	 */
 	public $request;
 
@@ -88,7 +88,7 @@ class WP_Query {
 	 * Array of post objects or post IDs.
 	 *
 	 * @since 1.5.0
-	 * @var WP_Post[]|int[]
+	 * @var WP_Post[]|int[]|null
 	 */
 	public $posts;
 
@@ -139,7 +139,7 @@ class WP_Query {
 	 * The list of comments for current post.
 	 *
 	 * @since 2.2.0
-	 * @var WP_Comment[]
+	 * @var ?WP_Comment[]
 	 */
 	public $comments;
 
@@ -163,7 +163,7 @@ class WP_Query {
 	 * Current comment object.
 	 *
 	 * @since 2.2.0
-	 * @var WP_Comment
+	 * @var ?WP_Comment
 	 */
 	public $comment;
 
@@ -466,7 +466,7 @@ class WP_Query {
 	 * Cached list of search stopwords.
 	 *
 	 * @since 3.7.0
-	 * @var array
+	 * @var ?array
 	 */
 	private $stopwords;
 

wp-includes/class-wp-rewrite.php

@@ -52,7 +52,7 @@ class WP_Rewrite {
 	 * Permalink structure for author archives.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $author_structure;
 
@@ -60,7 +60,7 @@ class WP_Rewrite {
 	 * Permalink structure for date archives.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $date_structure;
 
@@ -68,7 +68,7 @@ class WP_Rewrite {
 	 * Permalink structure for pages.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $page_structure;
 
@@ -84,7 +84,7 @@ class WP_Rewrite {
 	 * Permalink structure for searches.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $search_structure;
 
@@ -124,7 +124,7 @@ class WP_Rewrite {
 	 * Comments feed permalink structure.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $comment_feed_structure;
 
@@ -132,7 +132,7 @@ class WP_Rewrite {
 	 * Feed request permalink structure.
 	 *
 	 * @since 1.5.0
-	 * @var string
+	 * @var ?string
 	 */
 	public $feed_structure;
 

wp-includes/class-wp-theme.php

@@ -114,7 +114,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Header data from the theme's style.css file after being sanitized.
 	 *
 	 * @since 3.4.0
-	 * @var array
+	 * @var ?array
 	 */
 	private $headers_sanitized;
 
@@ -122,7 +122,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Is this theme a block theme.
 	 *
 	 * @since 6.2.0
-	 * @var bool
+	 * @var ?bool
 	 */
 	private $block_theme;
 
@@ -132,7 +132,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Cached due to sorting functions running over the translated name.
 	 *
 	 * @since 3.4.0
-	 * @var string
+	 * @var ?string
 	 */
 	private $name_translated;
 
@@ -140,7 +140,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Errors encountered when initializing the theme.
 	 *
 	 * @since 3.4.0
-	 * @var WP_Error
+	 * @var ?WP_Error
 	 */
 	private $errors;
 
@@ -162,7 +162,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Otherwise, 'template' is the same as 'stylesheet'.
 	 *
 	 * @since 3.4.0
-	 * @var string
+	 * @var ?string
 	 */
 	private $template;
 
@@ -170,7 +170,7 @@ final class WP_Theme implements ArrayAccess {
 	 * A reference to the parent theme, in the case of a child theme.
 	 *
 	 * @since 3.4.0
-	 * @var WP_Theme
+	 * @var ?WP_Theme
 	 */
 	private $parent;
 
@@ -178,7 +178,7 @@ final class WP_Theme implements ArrayAccess {
 	 * URL to the theme root, usually an absolute URL to wp-content/themes
 	 *
 	 * @since 3.4.0
-	 * @var string
+	 * @var ?string
 	 */
 	private $theme_root_uri;
 
@@ -186,7 +186,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Flag for whether the theme's textdomain is loaded.
 	 *
 	 * @since 3.4.0
-	 * @var bool
+	 * @var ?bool
 	 */
 	private $textdomain_loaded;
 
@@ -202,7 +202,7 @@ final class WP_Theme implements ArrayAccess {
 	 * Block template folders.
 	 *
 	 * @since 6.4.0
-	 * @var string[]
+	 * @var ?string[]
 	 */
 	private $block_template_folders;
 

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '7.0-alpha-61284';
+$wp_version = '7.0-alpha-61300';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.