[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_Type_Registry class
   4   *
   5   * @package WordPress
   6   * @subpackage Blocks
   7   * @since 5.0.0
   8   */
   9  
  10  /**
  11   * Core class used for interacting with block types.
  12   *
  13   * @since 5.0.0
  14   */
  15  #[AllowDynamicProperties]
  16  final class WP_Block_Type_Registry {
  17      /**
  18       * Registered block types, as `$name => $instance` pairs.
  19       *
  20       * @since 5.0.0
  21       * @var WP_Block_Type[]
  22       */
  23      private $registered_block_types = array();
  24  
  25      /**
  26       * Container for the main instance of the class.
  27       *
  28       * @since 5.0.0
  29       * @var WP_Block_Type_Registry|null
  30       */
  31      private static $instance = null;
  32  
  33      /**
  34       * Registers a block type.
  35       *
  36       * @since 5.0.0
  37       *
  38       * @see WP_Block_Type::__construct()
  39       *
  40       * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
  41       *                                   a complete WP_Block_Type instance. In case a WP_Block_Type
  42       *                                   is provided, the $args parameter will be ignored.
  43       * @param array                $args Optional. Array of block type arguments. Accepts any public property
  44       *                                   of `WP_Block_Type`. See WP_Block_Type::__construct() for information
  45       *                                   on accepted arguments. Default empty array.
  46       * @return WP_Block_Type|false The registered block type on success, or false on failure.
  47       *
  48       * @phpstan-param (lowercase-string&non-falsy-string)|WP_Block_Type $name
  49       */
  50  	public function register( $name, $args = array() ) {
  51          $block_type = null;
  52          if ( $name instanceof WP_Block_Type ) {
  53              $block_type = $name;
  54              $name       = $block_type->name;
  55          }
  56  
  57          if ( ! is_string( $name ) ) {
  58              _doing_it_wrong(
  59                  __METHOD__,
  60                  /* translators: %s: The received block type name type. */
  61                  sprintf( __( 'Block type names must be strings, received %s.' ), gettype( $name ) ),
  62                  '5.0.0'
  63              );
  64              return false;
  65          }
  66  
  67          if ( preg_match( '/[A-Z]+/', $name ) ) {
  68              _doing_it_wrong(
  69                  __METHOD__,
  70                  /* translators: %s: Block name. */
  71                  sprintf( __( 'Block type names must not contain uppercase characters. "%s" was given.' ), esc_html( $name ) ),
  72                  '5.0.0'
  73              );
  74              return false;
  75          }
  76  
  77          $name_matcher = '/^[a-z0-9-]+\/[a-z0-9-]+$/';
  78          if ( ! preg_match( $name_matcher, $name ) ) {
  79              _doing_it_wrong(
  80                  __METHOD__,
  81                  /* translators: %s: Block name. */
  82                  sprintf( __( 'Block type names must contain a namespace prefix. Example: my-plugin/my-custom-block-type. "%s" was given.' ), esc_html( $name ) ),
  83                  '5.0.0'
  84              );
  85              return false;
  86          }
  87  
  88          if ( $this->is_registered( $name ) ) {
  89              _doing_it_wrong(
  90                  __METHOD__,
  91                  /* translators: %s: Block name. */
  92                  sprintf( __( 'Block type "%s" is already registered.' ), $name ),
  93                  '5.0.0'
  94              );
  95              return false;
  96          }
  97  
  98          if ( ! $block_type ) {
  99              $block_type = new WP_Block_Type( $name, $args );
 100          }
 101  
 102          $this->registered_block_types[ $name ] = $block_type;
 103  
 104          return $block_type;
 105      }
 106  
 107      /**
 108       * Unregisters a block type.
 109       *
 110       * @since 5.0.0
 111       *
 112       * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
 113       *                                   a complete WP_Block_Type instance.
 114       * @return WP_Block_Type|false The unregistered block type on success, or false on failure.
 115       */
 116  	public function unregister( $name ) {
 117          if ( $name instanceof WP_Block_Type ) {
 118              $name = $name->name;
 119          }
 120  
 121          if ( ! $this->is_registered( $name ) ) {
 122              _doing_it_wrong(
 123                  __METHOD__,
 124                  /* translators: %s: Block name. */
 125                  sprintf( __( 'Block type "%s" is not registered.' ), $name ),
 126                  '5.0.0'
 127              );
 128              return false;
 129          }
 130  
 131          $unregistered_block_type = $this->registered_block_types[ $name ];
 132          unset( $this->registered_block_types[ $name ] );
 133  
 134          return $unregistered_block_type;
 135      }
 136  
 137      /**
 138       * Retrieves a registered block type.
 139       *
 140       * @since 5.0.0
 141       *
 142       * @param string|null $name Block type name including namespace.
 143       * @return WP_Block_Type|null The registered block type, or null if it is not registered.
 144       */
 145  	public function get_registered( $name ) {
 146          if ( ! $this->is_registered( $name ) ) {
 147              return null;
 148          }
 149  
 150          return $this->registered_block_types[ $name ];
 151      }
 152  
 153      /**
 154       * Retrieves all registered block types.
 155       *
 156       * @since 5.0.0
 157       *
 158       * @return WP_Block_Type[] Associative array of `$block_type_name => $block_type` pairs.
 159       */
 160  	public function get_all_registered() {
 161          return $this->registered_block_types;
 162      }
 163  
 164      /**
 165       * Checks if a block type is registered.
 166       *
 167       * @since 5.0.0
 168       *
 169       * @param string|null $name Block type name including namespace.
 170       * @return bool True if the block type is registered, false otherwise.
 171       */
 172  	public function is_registered( $name ) {
 173          return isset( $name, $this->registered_block_types[ $name ] );
 174      }
 175  
 176  	public function __wakeup() {
 177          if ( ! $this->registered_block_types ) {
 178              return;
 179          }
 180          if ( ! is_array( $this->registered_block_types ) ) {
 181              throw new UnexpectedValueException();
 182          }
 183          foreach ( $this->registered_block_types as $value ) {
 184              if ( ! $value instanceof WP_Block_Type ) {
 185                  throw new UnexpectedValueException();
 186              }
 187          }
 188      }
 189  
 190      /**
 191       * Utility method to retrieve the main instance of the class.
 192       *
 193       * The instance will be created if it does not exist yet.
 194       *
 195       * @since 5.0.0
 196       *
 197       * @return WP_Block_Type_Registry The main instance.
 198       */
 199  	public static function get_instance() {
 200          self::$instance ??= new self();
 201  
 202          return self::$instance;
 203      }
 204  }