[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_Styles_Registry class
   4   *
   5   * @package WordPress
   6   * @subpackage Blocks
   7   * @since 5.3.0
   8   */
   9  
  10  /**
  11   * Class used for interacting with block styles.
  12   *
  13   * @since 5.3.0
  14   */
  15  final class WP_Block_Styles_Registry {
  16      /**
  17       * Registered block styles, as `$block_name => $block_style_name => $block_style_properties` multidimensional arrays.
  18       *
  19       * @since 5.3.0
  20       *
  21       * @var array[]
  22       */
  23      private $registered_block_styles = array();
  24  
  25      /**
  26       * Container for the main instance of the class.
  27       *
  28       * @since 5.3.0
  29       *
  30       * @var WP_Block_Styles_Registry|null
  31       */
  32      private static $instance = null;
  33  
  34      /**
  35       * Registers a block style for the given block type.
  36       *
  37       * @since 5.3.0
  38       *
  39       * @param string $block_name       Block type name including namespace.
  40       * @param array  $style_properties Array containing the properties of the style name, label,
  41       *                                 is_default, style_handle (name of the stylesheet to be enqueued),
  42       *                                 inline_style (string containing the CSS to be added).
  43       * @return bool True if the block style was registered with success and false otherwise.
  44       */
  45  	public function register( $block_name, $style_properties ) {
  46  
  47          if ( ! isset( $block_name ) || ! is_string( $block_name ) ) {
  48              _doing_it_wrong(
  49                  __METHOD__,
  50                  __( 'Block name must be a string.' ),
  51                  '5.3.0'
  52              );
  53              return false;
  54          }
  55  
  56          if ( ! isset( $style_properties['name'] ) || ! is_string( $style_properties['name'] ) ) {
  57              _doing_it_wrong(
  58                  __METHOD__,
  59                  __( 'Block style name must be a string.' ),
  60                  '5.3.0'
  61              );
  62              return false;
  63          }
  64  
  65          if ( str_contains( $style_properties['name'], ' ' ) ) {
  66              _doing_it_wrong(
  67                  __METHOD__,
  68                  __( 'Block style name must not contain any spaces.' ),
  69                  '5.9.0'
  70              );
  71              return false;
  72          }
  73  
  74          $block_style_name = $style_properties['name'];
  75  
  76          if ( ! isset( $this->registered_block_styles[ $block_name ] ) ) {
  77              $this->registered_block_styles[ $block_name ] = array();
  78          }
  79          $this->registered_block_styles[ $block_name ][ $block_style_name ] = $style_properties;
  80  
  81          return true;
  82      }
  83  
  84      /**
  85       * Unregisters a block style of the given block type.
  86       *
  87       * @since 5.3.0
  88       *
  89       * @param string $block_name       Block type name including namespace.
  90       * @param string $block_style_name Block style name.
  91       * @return bool True if the block style was unregistered with success and false otherwise.
  92       */
  93  	public function unregister( $block_name, $block_style_name ) {
  94          if ( ! $this->is_registered( $block_name, $block_style_name ) ) {
  95              _doing_it_wrong(
  96                  __METHOD__,
  97                  /* translators: 1: Block name, 2: Block style name. */
  98                  sprintf( __( 'Block "%1$s" does not contain a style named "%2$s".' ), $block_name, $block_style_name ),
  99                  '5.3.0'
 100              );
 101              return false;
 102          }
 103  
 104          unset( $this->registered_block_styles[ $block_name ][ $block_style_name ] );
 105  
 106          return true;
 107      }
 108  
 109      /**
 110       * Retrieves the properties of a registered block style for the given block type.
 111       *
 112       * @since 5.3.0
 113       *
 114       * @param string $block_name       Block type name including namespace.
 115       * @param string $block_style_name Block style name.
 116       * @return array Registered block style properties.
 117       */
 118  	public function get_registered( $block_name, $block_style_name ) {
 119          if ( ! $this->is_registered( $block_name, $block_style_name ) ) {
 120              return null;
 121          }
 122  
 123          return $this->registered_block_styles[ $block_name ][ $block_style_name ];
 124      }
 125  
 126      /**
 127       * Retrieves all registered block styles.
 128       *
 129       * @since 5.3.0
 130       *
 131       * @return array[] Array of arrays containing the registered block styles properties grouped by block type.
 132       */
 133  	public function get_all_registered() {
 134          return $this->registered_block_styles;
 135      }
 136  
 137      /**
 138       * Retrieves registered block styles for a specific block type.
 139       *
 140       * @since 5.3.0
 141       *
 142       * @param string $block_name Block type name including namespace.
 143       * @return array[] Array whose keys are block style names and whose values are block style properties.
 144       */
 145  	public function get_registered_styles_for_block( $block_name ) {
 146          if ( isset( $this->registered_block_styles[ $block_name ] ) ) {
 147              return $this->registered_block_styles[ $block_name ];
 148          }
 149          return array();
 150      }
 151  
 152      /**
 153       * Checks if a block style is registered for the given block type.
 154       *
 155       * @since 5.3.0
 156       *
 157       * @param string $block_name       Block type name including namespace.
 158       * @param string $block_style_name Block style name.
 159       * @return bool True if the block style is registered, false otherwise.
 160       */
 161  	public function is_registered( $block_name, $block_style_name ) {
 162          return isset( $this->registered_block_styles[ $block_name ][ $block_style_name ] );
 163      }
 164  
 165      /**
 166       * Utility method to retrieve the main instance of the class.
 167       *
 168       * The instance will be created if it does not exist yet.
 169       *
 170       * @since 5.3.0
 171       *
 172       * @return WP_Block_Styles_Registry The main instance.
 173       */
 174  	public static function get_instance() {
 175          if ( null === self::$instance ) {
 176              self::$instance = new self();
 177          }
 178  
 179          return self::$instance;
 180      }
 181  }