[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Administration API: WP_Admin_Notice_Collector class
   4   *
   5   * @package WordPress
   6   * @subpackage Administration
   7   * @since x.x.x
   8   */
   9  
  10  /**
  11   * Capture admin notices generated in PHP during a request.
  12   *
  13   * Notices are captured via the {@see 'wp_admin_notice_markup'} filter.
  14   * a title placeholder is inserted into the admin page's `<title>` tag,
  15   * the admin page title is modified via the {@see 'admin_title'}
  16   * filter, the admin page is wrapped in an output buffer, and an
  17   * `ob_start()` callback replaces the placeholder with the final count once
  18   * the buffer is flushed.
  19   *
  20   * @since 7.2.0
  21   */
  22  class WP_Admin_Notice_Collector {
  23  
  24      /**
  25       * Placeholder inserted into the admin title, replaced with the
  26       * actual notice count once it is known.
  27       *
  28       * @since 7.2.0
  29       * @var string
  30       */
  31      const TITLE_PLACEHOLDER = '%%wp_admin_notice_count%%';
  32  
  33      /**
  34       * Notices captured during the current request.
  35       *
  36       * @since 7.2.0
  37       * @var array[]
  38       */
  39      protected static $notices = array();
  40  
  41      /**
  42       * Whether the collector's hooks have already been registered.
  43       *
  44       * @since 7.2.0
  45       * @var bool
  46       */
  47      protected static $hooked = false;
  48  
  49      /**
  50       * Registers the hooks used to collect notices and to annotate the admin title.
  51       *
  52       * @since 7.2.0
  53       */
  54  	public static function init() {
  55          if ( self::$hooked ) {
  56              return;
  57          }
  58  
  59          self::$hooked = true;
  60  
  61          add_filter( 'wp_admin_notice_markup', array( __CLASS__, 'capture_notice' ), 10, 3 );
  62  
  63          // Ajax/REST admin requests don't render a <title>, so skip the buffer there.
  64          if ( is_admin() && ! wp_doing_ajax() ) {
  65              add_filter( 'admin_title', array( __CLASS__, 'add_title_placeholder' ), 10, 2 );
  66              ob_start( array( __CLASS__, 'inject_notice_count' ) );
  67          }
  68      }
  69  
  70      /**
  71       * Captures a single admin notice without altering its markup.
  72       *
  73       * Hooked to the {@see 'wp_admin_notice_markup'} filter.
  74       *
  75       * @since 7.2.0
  76       *
  77       * @param string $markup  The HTML markup for the admin notice.
  78       * @param string $message The message for the admin notice.
  79       * @param array  $args    The arguments for the admin notice.
  80       * @return string The unmodified markup, so the filter remains transparent.
  81       */
  82  	public static function capture_notice( $markup, $message, $args ) {
  83          if ( '' !== trim( wp_strip_all_tags( $message ) ) ) {
  84              self::$notices[ $args['notice_id'] ] = array(
  85                  'markup'  => $markup,
  86                  'message' => $message,
  87                  'args'    => $args,
  88              );
  89          }
  90  
  91          return $markup;
  92      }
  93  
  94      /**
  95       * Returns all notices captured during the current request.
  96       *
  97       * @since 7.2.0
  98       *
  99       * @return array[] Array of captured notices. Each entry contains the
 100       *                 notice's 'markup', 'message', and 'args'.
 101       */
 102  	public static function get_notices() {
 103          return self::$notices;
 104      }
 105  
 106      /**
 107       * Returns the number of notices captured during the current request.
 108       *
 109       * @since 7.2.0
 110       *
 111       * @return int Notice count.
 112       */
 113  	public static function get_notice_count() {
 114          return count( self::$notices );
 115      }
 116  
 117      /**
 118       * Clears all previously captured notices.
 119       *
 120       * @since 7.2.0
 121       */
 122  	public static function reset() {
 123          self::$notices = array();
 124      }
 125  
 126      /**
 127       * Prepends a title placeholder via the {@see 'admin_title'} filter.
 128       *
 129       * The real count isn't known yet at this point, since notices are usually
 130       * produced later in the page. inject_notice_count() resolves it.
 131       *
 132       * @since 7.2.0
 133       *
 134       * @param string $admin_title The page title, with extra context added.
 135       * @param string $title       The original page title.
 136       * @return string The admin title with the placeholder prepended.
 137       */
 138  	public static function add_title_placeholder( $admin_title, $title ) {
 139          return self::TITLE_PLACEHOLDER . $admin_title;
 140      }
 141  
 142      /**
 143       * Replaces the title placeholder with the final notice count.
 144       *
 145       * Used as an `ob_start()` callback so it runs once the full page - including
 146       * any notices printed after `<title>` - has been buffered.
 147       *
 148       * @since 7.2.0
 149       *
 150       * @param string $buffer The full buffered page output.
 151       * @return string The page output with the placeholder resolved.
 152       */
 153  	public static function inject_notice_count( $buffer ) {
 154          $count = self::get_notice_count();
 155  
 156          if ( 0 === $count ) {
 157              return str_replace( self::TITLE_PLACEHOLDER, '', $buffer );
 158          }
 159  
 160          /* translators: %d: Number of admin notices on the current page. */
 161          $prefix = sprintf( _n( '(%d notice) ', '(%d notices) ', $count ), $count );
 162  
 163          return str_replace( self::TITLE_PLACEHOLDER, $prefix, $buffer );
 164      }
 165  }