enmi-conf.org: comparison wp/wp-admin/includes/class-wp-screen.php

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 *
 * @since 3.3.0
 */
 final class WP_Screen {
 	/**
-	 * Any action associated with the screen. 'add' for *-add.php and *-new.php screens. Empty otherwise.
+	 * Any action associated with the screen.
+	 *
+	 * 'add' for *-add.php and *-new.php screens. Empty otherwise.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public $action;
 	/**
-	 * The base type of the screen. This is typically the same as $id but with any post types and taxonomies stripped.
+	 * The base type of the screen.
-	 * For example, for an $id of 'edit-post' the base is 'edit'.
+	 *
+	 * This is typically the same as `$id` but with any post types and taxonomies stripped.
+	 * For example, for an `$id` of 'edit-post' the base is 'edit'.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public $base;
 	 */
 	public $is_user;
 	/**
 	 * The base menu parent.
-	 * This is derived from $parent_file by removing the query string and any .php extension.
+	 *
-	 * $parent_file values of 'edit.php?post_type=page' and 'edit.php?post_type=post' have a $parent_base of 'edit'.
+	 * This is derived from `$parent_file` by removing the query string and any .php extension.
+	 * `$parent_file` values of 'edit.php?post_type=page' and 'edit.php?post_type=post'
+	 * have a `$parent_base` of 'edit'.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public $parent_base;
 	/**
 	 * The parent_file for the screen per the admin menu system.
-	 * Some $parent_file values are 'edit.php?post_type=page', 'edit.php', and 'options-general.php'.
+	 *
+	 * Some `$parent_file` values are 'edit.php?post_type=page', 'edit.php', and 'options-general.php'.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public $parent_file;
 	/**
 	 * The post type associated with the screen, if any.
+	 *
 	 * The 'edit.php?post_type=page' screen has a post type of 'page'.
 	 * The 'edit-tags.php?taxonomy=$taxonomy&post_type=page' screen has a post type of 'page'.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public $post_type;
 	/**
 	 * The taxonomy associated with the screen, if any.
+	 *
 	 * The 'edit-tags.php?taxonomy=category' screen has a taxonomy of 'category'.
 	 *
 	 * @since 3.3.0
 	 * @var string
 	 */
 	public static function get( $hook_name = '' ) {
 		if ( $hook_name instanceof WP_Screen ) {
 			return $hook_name;
 		}
-		$post_type       = $taxonomy = null;
+		$post_type       = null;
+		$taxonomy        = null;
 		$in_admin        = false;
 		$action          = '';
 		$is_block_editor = false;
 		if ( $hook_name ) {
 		}
 		// For those pesky meta boxes.
 		if ( $hook_name && post_type_exists( $hook_name ) ) {
 			$post_type = $id;
-			$id        = 'post'; // changes later. ends up being $base.
+			$id        = 'post'; // Changes later. Ends up being $base.
 		} else {
-			if ( '.php' == substr( $id, -4 ) ) {
+			if ( '.php' === substr( $id, -4 ) ) {
 				$id = substr( $id, 0, -4 );
 			}
-			if ( 'post-new' == $id || 'link-add' == $id || 'media-new' == $id || 'user-new' == $id ) {
+			if ( in_array( $id, array( 'post-new', 'link-add', 'media-new', 'user-new' ), true ) ) {
 				$id     = substr( $id, 0, -4 );
 				$action = 'add';
 			}
 		}
 		if ( ! $post_type && $hook_name ) {
-			if ( '-network' == substr( $id, -8 ) ) {
+			if ( '-network' === substr( $id, -8 ) ) {
 				$id       = substr( $id, 0, -8 );
 				$in_admin = 'network';
-			} elseif ( '-user' == substr( $id, -5 ) ) {
+			} elseif ( '-user' === substr( $id, -5 ) ) {
 				$id       = substr( $id, 0, -5 );
 				$in_admin = 'user';
 			}
 			$id = sanitize_key( $id );
-			if ( 'edit-comments' != $id && 'edit-tags' != $id && 'edit-' == substr( $id, 0, 5 ) ) {
+			if ( 'edit-comments' !== $id && 'edit-tags' !== $id && 'edit-' === substr( $id, 0, 5 ) ) {
 				$maybe = substr( $id, 5 );
 				if ( taxonomy_exists( $maybe ) ) {
 					$id       = 'edit-tags';
 					$taxonomy = $maybe;
 				} elseif ( post_type_exists( $maybe ) ) {
 			} else {
 				$in_admin = 'site';
 			}
 		}
-		if ( 'index' == $id ) {
+		if ( 'index' === $id ) {
 			$id = 'dashboard';
-		} elseif ( 'front' == $id ) {
+		} elseif ( 'front' === $id ) {
 			$in_admin = false;
 		}
 		$base = $id;
 				$id = 'edit-' . $taxonomy;
 				break;
 		}
-		if ( 'network' == $in_admin ) {
+		if ( 'network' === $in_admin ) {
 			$id   .= '-network';
 			$base .= '-network';
-		} elseif ( 'user' == $in_admin ) {
+		} elseif ( 'user' === $in_admin ) {
 			$id   .= '-user';
 			$base .= '-user';
 		}
 		if ( isset( self::$_registry[ $id ] ) ) {
 			$screen = self::$_registry[ $id ];
-			if ( $screen === get_current_screen() ) {
+			if ( get_current_screen() === $screen ) {
 				return $screen;
 			}
 		} else {
 			$screen     = new WP_Screen();
 			$screen->id = $id;
 		$screen->base            = $base;
 		$screen->action          = $action;
 		$screen->post_type       = (string) $post_type;
 		$screen->taxonomy        = (string) $taxonomy;
-		$screen->is_user         = ( 'user' == $in_admin );
+		$screen->is_user         = ( 'user' === $in_admin );
-		$screen->is_network      = ( 'network' == $in_admin );
+		$screen->is_network      = ( 'network' === $in_admin );
 		$screen->in_admin        = $in_admin;
 		$screen->is_block_editor = $is_block_editor;
 		self::$_registry[ $id ] = $screen;
 	 * Makes the screen object the current screen.
 	 *
 	 * @see set_current_screen()
 	 * @since 3.3.0
 	 *
-	 * @global WP_Screen $current_screen
+	 * @global WP_Screen $current_screen WordPress current screen object.
 	 * @global string    $taxnow
 	 * @global string    $typenow
 	 */
 	public function set_current_screen() {
 		global $current_screen, $taxnow, $typenow;
 	public function in_admin( $admin = null ) {
 		if ( empty( $admin ) ) {
 			return (bool) $this->in_admin;
 		}
-		return ( $admin == $this->in_admin );
+		return ( $admin === $this->in_admin );
 	}
 	/**
 	 * Sets or returns whether the block editor is loading on the current screen.
 	 *
 	 *
 	 * @param bool $set Optional. Sets whether the block editor is loading on the current screen or not.
 	 * @return bool True if the block editor is being loaded, false otherwise.
 	 */
 	public function is_block_editor( $set = null ) {
-		if ( $set !== null ) {
+		if ( null !== $set ) {
 			$this->is_block_editor = (bool) $set;
 		}
 		return $this->is_block_editor;
 	}
 	 * Sets the old string-based contextual help for the screen for backward compatibility.
 	 *
 	 * @since 3.3.0
 	 *
 	 * @param WP_Screen $screen A screen object.
-	 * @param string $help Help text.
+	 * @param string    $help   Help text.
 	 */
 	public static function add_old_compat_help( $screen, $help ) {
 		self::$_old_compat_help[ $screen->id ] = $help;
 	}
 	/**
 	 * Set the parent information for the screen.
+	 *
 	 * This is called in admin-header.php after the menu parent for the screen has been determined.
 	 *
 	 * @since 3.3.0
 	 *
 	 * @param string $parent_file The parent file of the screen. Typically the $parent_file global.
 		$this->parent_base         = str_replace( '.php', '', $this->parent_base );
 	}
 	/**
 	 * Adds an option for the screen.
-	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded to add screen options.
+	 *
-	 *
+	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded
-	 * @since 3.3.0
+	 * to add screen options.
 	 *
-	 * @param string $option Option ID
+	 * @since 3.3.0
-	 * @param mixed $args Option-dependent arguments.
+	 *
+	 * @param string $option Option ID.
+	 * @param mixed  $args   Option-dependent arguments.
 	 */
 	public function add_option( $option, $args = array() ) {
 		$this->_options[ $option ] = $args;
 	}
 		return $this->_help_tabs[ $id ];
 	}
 	/**
 	 * Add a help tab to the contextual help for the screen.
-	 * Call this on the load-$pagenow hook for the relevant screen.
+	 *
+	 * Call this on the `load-$pagenow` hook for the relevant screen,
+	 * or fetch the `$current_screen` object, or use get_current_screen()
+	 * and then call the method from the object.
+	 *
+	 * You may need to filter `$current_screen` using an if or switch statement
+	 * to prevent new help tabs from being added to ALL admin screens.
 	 *
 	 * @since 3.3.0
 	 * @since 4.4.0 The `$priority` argument was added.
 	 *
 	 * @param array $args {
 	 *     Array of arguments used to display the help tab.
 	 *
-	 *     @type string $title    Title for the tab. Default false.
+	 *     @type string   $title    Title for the tab. Default false.
-	 *     @type string $id       Tab ID. Must be HTML-safe. Default false.
+	 *     @type string   $id       Tab ID. Must be HTML-safe and should be unique for this menu.
-	 *     @type string $content  Optional. Help tab content in plain text or HTML. Default empty string.
+	 *                              It is NOT allowed to contain any empty spaces. Default false.
-	 *     @type string $callback Optional. A callback to generate the tab content. Default false.
+	 *     @type string   $content  Optional. Help tab content in plain text or HTML. Default empty string.
-	 *     @type int    $priority Optional. The priority of the tab, used for ordering. Default 10.
+	 *     @type callable $callback Optional. A callback to generate the tab content. Default false.
+	 *     @type int      $priority Optional. The priority of the tab, used for ordering. Default 10.
 	 * }
 	 */
 	public function add_help_tab( $args ) {
 		$defaults = array(
 			'title'    => false,
 		return $this->_help_sidebar;
 	}
 	/**
 	 * Add a sidebar to the contextual help for the screen.
-	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded to add a sidebar to the contextual help.
+	 *
+	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded
+	 * to add a sidebar to the contextual help.
 	 *
 	 * @since 3.3.0
 	 *
 	 * @param string $content Sidebar content in plain text or HTML.
 	 */
 		/**
 		 * Filters the legacy contextual help list.
 		 *
 		 * @since 2.7.0
-		 * @deprecated 3.3.0 Use get_current_screen()->add_help_tab() or
+		 * @deprecated 3.3.0 Use {@see get_current_screen()->add_help_tab()} or
-		 *                   get_current_screen()->remove_help_tab() instead.
+		 *                   {@see get_current_screen()->remove_help_tab()} instead.
 		 *
 		 * @param array     $old_compat_help Old contextual help.
 		 * @param WP_Screen $this            Current WP_Screen instance.
 		 */
-		self::$_old_compat_help = apply_filters( 'contextual_help_list', self::$_old_compat_help, $this );
+		self::$_old_compat_help = apply_filters_deprecated(
+			'contextual_help_list',
+			array( self::$_old_compat_help, $this ),
+			'3.3.0',
+			'get_current_screen()->add_help_tab(), get_current_screen()->remove_help_tab()'
+		);
 		$old_help = isset( self::$_old_compat_help[ $this->id ] ) ? self::$_old_compat_help[ $this->id ] : '';
 		/**
 		 * Filters the legacy contextual help text.
 		 *
 		 * @since 2.7.0
-		 * @deprecated 3.3.0 Use get_current_screen()->add_help_tab() or
+		 * @deprecated 3.3.0 Use {@see get_current_screen()->add_help_tab()} or
-		 *                   get_current_screen()->remove_help_tab() instead.
+		 *                   {@see get_current_screen()->remove_help_tab()} instead.
 		 *
 		 * @param string    $old_help  Help text that appears on the screen.
 		 * @param string    $screen_id Screen ID.
 		 * @param WP_Screen $this      Current WP_Screen instance.
 		 */
-		$old_help = apply_filters( 'contextual_help', $old_help, $this->id, $this );
+		$old_help = apply_filters_deprecated(
+			'contextual_help',
+			array( $old_help, $this->id, $this ),
+			'3.3.0',
+			'get_current_screen()->add_help_tab(), get_current_screen()->remove_help_tab()'
+		);
 		// Default help only if there is no old-style block of text and no new-style help tabs.
 		if ( empty( $old_help ) && ! $this->get_help_tabs() ) {
 			/**
 			 * Filters the default legacy contextual help text.
 			 *
 			 * @since 2.8.0
-			 * @deprecated 3.3.0 Use get_current_screen()->add_help_tab() or
+			 * @deprecated 3.3.0 Use {@see get_current_screen()->add_help_tab()} or
-			 *                   get_current_screen()->remove_help_tab() instead.
+			 *                   {@see get_current_screen()->remove_help_tab()} instead.
 			 *
 			 * @param string $old_help_default Default contextual help text.
 			 */
-			$default_help = apply_filters( 'default_contextual_help', '' );
+			$default_help = apply_filters_deprecated(
+				'default_contextual_help',
+				array( '' ),
+				'3.3.0',
+				'get_current_screen()->add_help_tab(), get_current_screen()->remove_help_tab()'
+			);
 			if ( $default_help ) {
 				$old_help = '<p>' . $default_help . '</p>';
 			}
 		}
 						?>
 					</div>
 				</div>
 			</div>
 		<?php
-		// Setup layout columns
+		// Setup layout columns.
 		/**
 		 * Filters the array of screen layout columns.
 		 *
 		 * This hook provides back-compat for plugins using the back-compat
 				$this->columns = $this->get_option( 'layout_columns', 'default' );
 			}
 		}
 		$GLOBALS['screen_layout_columns'] = $this->columns; // Set the global for back-compat.
-		// Add screen options
+		// Add screen options.
 		if ( $this->show_screen_options() ) {
 			$this->render_screen_options();
 		}
 		?>
 		</div>
 	 * Render the screen options tab.
 	 *
 	 * @since 3.3.0
 	 *
 	 * @param array $options {
-	 *     @type bool $wrap  Whether the screen-options-wrap div will be included. Defaults to true.
+	 *     Options for the tab.
+	 *
+	 *     @type bool $wrap Whether the screen-options-wrap div will be included. Defaults to true.
 	 * }
 	 */
 	public function render_screen_options( $options = array() ) {
 		$options = wp_parse_args(
 			$options,
 			array(
 				'wrap' => true,
 			)
 		);
-		$wrapper_start = $wrapper_end = $form_start = $form_end = '';
+		$wrapper_start = '';
+		$wrapper_end   = '';
+		$form_start    = '';
+		$form_end      = '';
 		// Output optional wrapper.
 		if ( $options['wrap'] ) {
 			$wrapper_start = '<div id="screen-options-wrap" class="hidden" tabindex="-1" aria-label="' . esc_attr__( 'Screen Options Tab' ) . '">';
 			$wrapper_end   = '</div>';
 		if ( 'dashboard' === $this->id && has_action( 'welcome_panel' ) && current_user_can( 'edit_theme_options' ) ) {
 			if ( isset( $_GET['welcome'] ) ) {
 				$welcome_checked = empty( $_GET['welcome'] ) ? 0 : 1;
 				update_user_meta( get_current_user_id(), 'show_welcome_panel', $welcome_checked );
 			} else {
-				$welcome_checked = get_user_meta( get_current_user_id(), 'show_welcome_panel', true );
+				$welcome_checked = (int) get_user_meta( get_current_user_id(), 'show_welcome_panel', true );
-				if ( 2 == $welcome_checked && wp_get_current_user()->user_email != get_option( 'admin_email' ) ) {
+				if ( 2 === $welcome_checked && wp_get_current_user()->user_email !== get_option( 'admin_email' ) ) {
 					$welcome_checked = false;
 				}
 			}
 			echo '<label for="wp_welcome_panel-hide">';
 			echo '<input type="checkbox" id="wp_welcome_panel-hide"' . checked( (bool) $welcome_checked, true, false ) . ' />';
 		<legend><?php echo $legend; ?></legend>
 		<?php
 		$special = array( '_title', 'cb', 'comment', 'media', 'name', 'title', 'username', 'blogname' );
 		foreach ( $columns as $column => $title ) {
-			// Can't hide these for they are special
+			// Can't hide these for they are special.
-			if ( in_array( $column, $special ) ) {
+			if ( in_array( $column, $special, true ) ) {
 				continue;
 			}
 			if ( empty( $title ) ) {
 				continue;
 			 */
 			$title = wp_strip_all_tags( $title );
 			$id = "$column-hide";
 			echo '<label>';
-			echo '<input class="hide-column-tog" name="' . $id . '" type="checkbox" id="' . $id . '" value="' . $column . '"' . checked( ! in_array( $column, $hidden ), true, false ) . ' />';
+			echo '<input class="hide-column-tog" name="' . $id . '" type="checkbox" id="' . $id . '" value="' . $column . '"' . checked( ! in_array( $column, $hidden, true ), true, false ) . ' />';
 			echo "$title</label>\n";
 		}
 		?>
 		</fieldset>
 		<?php
 		$num                   = $this->get_option( 'layout_columns', 'max' );
 		?>
 		<fieldset class='columns-prefs'>
 		<legend class="screen-layout"><?php _e( 'Layout' ); ?></legend>
-												<?php
+		<?php for ( $i = 1; $i <= $num; ++$i ) : ?>
-												for ( $i = 1; $i <= $num; ++$i ) :
+			<label class="columns-prefs-<?php echo $i; ?>">
-													?>
+			<input type='radio' name='screen_columns' value='<?php echo esc_attr( $i ); ?>' <?php checked( $screen_layout_columns, $i ); ?> />
-													<label class="columns-prefs-<?php echo $i; ?>">
+			<?php
-				<input type='radio' name='screen_columns' value='<?php echo esc_attr( $i ); ?>'
+				printf(
-													<?php checked( $screen_layout_columns, $i ); ?> />
+					/* translators: %s: Number of columns on the page. */
-													<?php printf( _n( '%s column', '%s columns', $i ), number_format_i18n( $i ) ); ?>
+					_n( '%s column', '%s columns', $i ),
-				</label>
+					number_format_i18n( $i )
-													<?php
+				);
-			endfor;
+			?>
-												?>
+			</label>
+		<?php endfor; ?>
 		</fieldset>
 		<?php
 	}
 	/**
 			if ( ! $per_page ) {
 				$per_page = 20;
 			}
 		}
-		if ( 'edit_comments_per_page' == $option ) {
+		if ( 'edit_comments_per_page' === $option ) {
 			$comment_status = isset( $_REQUEST['comment_status'] ) ? $_REQUEST['comment_status'] : 'all';
 			/** This filter is documented in wp-admin/includes/class-wp-comments-list-table.php */
 			$per_page = apply_filters( 'comments_per_page', $per_page, $comment_status );
-		} elseif ( 'categories_per_page' == $option ) {
+		} elseif ( 'categories_per_page' === $option ) {
 			/** This filter is documented in wp-admin/includes/class-wp-terms-list-table.php */
 			$per_page = apply_filters( 'edit_categories_per_page', $per_page );
 		} else {
 			/** This filter is documented in wp-admin/includes/class-wp-list-table.php */
 			$per_page = apply_filters( "{$option}", $per_page );
 		}
-		// Back compat
+		// Back compat.
 		if ( isset( $this->post_type ) ) {
 			/** This filter is documented in wp-admin/includes/post.php */
 			$per_page = apply_filters( 'edit_posts_per_page', $per_page, $this->post_type );
 		}
-		// This needs a submit button
+		// This needs a submit button.
 		add_filter( 'screen_options_show_submit', '__return_true' );
 		?>
 		<fieldset class="screen-options">
 		<legend><?php _e( 'Pagination' ); ?></legend>
 	 * @since 4.4.0
 	 *
 	 * @global string $mode List table view mode.
 	 */
 	public function render_view_mode() {
+		global $mode;
 		$screen = get_current_screen();
-		// Currently only enabled for posts lists
+		// Currently only enabled for posts and comments lists.
-		if ( 'edit' !== $screen->base ) {
+		if ( 'edit' !== $screen->base && 'edit-comments' !== $screen->base ) {
 			return;
 		}
-		$view_mode_post_types = get_post_types(
+		$view_mode_post_types = get_post_types( array( 'show_ui' => true ) );
-			array(
-				'hierarchical' => false,
-				'show_ui'      => true,
-			)
-		);
 		/**
 		 * Filters the post types that have different view mode options.
 		 *
 		 * @since 4.4.0
 		 *
 		 * @param string[] $view_mode_post_types Array of post types that can change view modes.
-		 *                                       Default non-hierarchical post types with show_ui on.
+		 *                                       Default post types with show_ui on.
 		 */
 		$view_mode_post_types = apply_filters( 'view_mode_post_types', $view_mode_post_types );
-		if ( ! in_array( $this->post_type, $view_mode_post_types ) ) {
+		if ( 'edit' === $screen->base && ! in_array( $this->post_type, $view_mode_post_types, true ) ) {
 			return;
 		}
-		global $mode;
+		if ( ! isset( $mode ) ) {
+			$mode = get_user_setting( 'posts_list_mode', 'list' );
-		// This needs a submit button
+		}
+		// This needs a submit button.
 		add_filter( 'screen_options_show_submit', '__return_true' );
 		?>
 		<fieldset class="metabox-prefs view-mode">
-		<legend><?php _e( 'View Mode' ); ?></legend>
+			<legend><?php _e( 'View mode' ); ?></legend>
-				<label for="list-view-mode">
+			<label for="list-view-mode">
-					<input id="list-view-mode" type="radio" name="mode" value="list" <?php checked( 'list', $mode ); ?> />
+				<input id="list-view-mode" type="radio" name="mode" value="list" <?php checked( 'list', $mode ); ?> />
-					<?php _e( 'List View' ); ?>
+				<?php _e( 'Compact view' ); ?>
-				</label>
+			</label>
-				<label for="excerpt-view-mode">
+			<label for="excerpt-view-mode">
-					<input id="excerpt-view-mode" type="radio" name="mode" value="excerpt" <?php checked( 'excerpt', $mode ); ?> />
+				<input id="excerpt-view-mode" type="radio" name="mode" value="excerpt" <?php checked( 'excerpt', $mode ); ?> />
-					<?php _e( 'Excerpt View' ); ?>
+				<?php _e( 'Extended view' ); ?>
-				</label>
+			</label>
 		</fieldset>
 		<?php
 	}
 	/**

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a