[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  final class WP_Block_Type_Registry {
  16      /**
  17       * Registered block types, as `$name => $instance` pairs.
  18       *
  19       * @since 5.0.0
  20       * @var WP_Block_Type[]
  21       */
  22      private $registered_block_types = array();
  23  
  24      /**
  25       * Container for the main instance of the class.
  26       *
  27       * @since 5.0.0
  28       * @var WP_Block_Type_Registry|null
  29       */
  30      private static $instance = null;
  31  
  32      /**
  33       * Registers a block type.
  34       *
  35       * @since 5.0.0
  36       *
  37       * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
  38       *                                   a complete WP_Block_Type instance. In case a WP_Block_Type
  39       *                                   is provided, the $args parameter will be ignored.
  40       * @param array                $args {
  41       *     Optional. Array of block type arguments. Accepts any public property of `WP_Block_Type`.
  42       *     Any arguments may be defined, however the ones described below are supported by default.
  43       *     Default empty array.
  44       *
  45       *     @type callable $render_callback Callback used to render blocks of this block type.
  46       *     @type array    $attributes      Block attributes mapping, property name to schema.
  47       * }
  48       * @return WP_Block_Type|false The registered block type on success, or false on failure.
  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              $message = __( 'Block type names must be strings.' );
  59              _doing_it_wrong( __METHOD__, $message, '5.0.0' );
  60              return false;
  61          }
  62  
  63          if ( preg_match( '/[A-Z]+/', $name ) ) {
  64              $message = __( 'Block type names must not contain uppercase characters.' );
  65              _doing_it_wrong( __METHOD__, $message, '5.0.0' );
  66              return false;
  67          }
  68  
  69          $name_matcher = '/^[a-z0-9-]+\/[a-z0-9-]+$/';
  70          if ( ! preg_match( $name_matcher, $name ) ) {
  71              $message = __( 'Block type names must contain a namespace prefix. Example: my-plugin/my-custom-block-type' );
  72              _doing_it_wrong( __METHOD__, $message, '5.0.0' );
  73              return false;
  74          }
  75  
  76          if ( $this->is_registered( $name ) ) {
  77              /* translators: %s: Block name. */
  78              $message = sprintf( __( 'Block type "%s" is already registered.' ), $name );
  79              _doing_it_wrong( __METHOD__, $message, '5.0.0' );
  80              return false;
  81          }
  82  
  83          if ( ! $block_type ) {
  84              $block_type = new WP_Block_Type( $name, $args );
  85          }
  86  
  87          $this->registered_block_types[ $name ] = $block_type;
  88  
  89          return $block_type;
  90      }
  91  
  92      /**
  93       * Unregisters a block type.
  94       *
  95       * @since 5.0.0
  96       *
  97       * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
  98       *                                   a complete WP_Block_Type instance.
  99       * @return WP_Block_Type|false The unregistered block type on success, or false on failure.
 100       */
 101  	public function unregister( $name ) {
 102          if ( $name instanceof WP_Block_Type ) {
 103              $name = $name->name;
 104          }
 105  
 106          if ( ! $this->is_registered( $name ) ) {
 107              /* translators: %s: Block name. */
 108              $message = sprintf( __( 'Block type "%s" is not registered.' ), $name );
 109              _doing_it_wrong( __METHOD__, $message, '5.0.0' );
 110              return false;
 111          }
 112  
 113          $unregistered_block_type = $this->registered_block_types[ $name ];
 114          unset( $this->registered_block_types[ $name ] );
 115  
 116          return $unregistered_block_type;
 117      }
 118  
 119      /**
 120       * Retrieves a registered block type.
 121       *
 122       * @since 5.0.0
 123       *
 124       * @param string $name Block type name including namespace.
 125       * @return WP_Block_Type|null The registered block type, or null if it is not registered.
 126       */
 127  	public function get_registered( $name ) {
 128          if ( ! $this->is_registered( $name ) ) {
 129              return null;
 130          }
 131  
 132          return $this->registered_block_types[ $name ];
 133      }
 134  
 135      /**
 136       * Retrieves all registered block types.
 137       *
 138       * @since 5.0.0
 139       *
 140       * @return WP_Block_Type[] Associative array of `$block_type_name => $block_type` pairs.
 141       */
 142  	public function get_all_registered() {
 143          return $this->registered_block_types;
 144      }
 145  
 146      /**
 147       * Checks if a block type is registered.
 148       *
 149       * @since 5.0.0
 150       *
 151       * @param string $name Block type name including namespace.
 152       * @return bool True if the block type is registered, false otherwise.
 153       */
 154  	public function is_registered( $name ) {
 155          return isset( $this->registered_block_types[ $name ] );
 156      }
 157  
 158      /**
 159       * Utility method to retrieve the main instance of the class.
 160       *
 161       * The instance will be created if it does not exist yet.
 162       *
 163       * @since 5.0.0
 164       *
 165       * @return WP_Block_Type_Registry The main instance.
 166       */
 167  	public static function get_instance() {
 168          if ( null === self::$instance ) {
 169              self::$instance = new self();
 170          }
 171  
 172          return self::$instance;
 173      }
 174  }