[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_Patterns_Registry class
   4   *
   5   * @package WordPress
   6   * @subpackage Blocks
   7   * @since 5.5.0
   8   */
   9  
  10  /**
  11   * Class used for interacting with block patterns.
  12   *
  13   * @since 5.5.0
  14   */
  15  final class WP_Block_Patterns_Registry {
  16      /**
  17       * Registered block patterns array.
  18       *
  19       * @since 5.5.0
  20       * @var array[]
  21       */
  22      private $registered_patterns = array();
  23  
  24      /**
  25       * Container for the main instance of the class.
  26       *
  27       * @since 5.5.0
  28       * @var WP_Block_Patterns_Registry|null
  29       */
  30      private static $instance = null;
  31  
  32      /**
  33       * Registers a block pattern.
  34       *
  35       * @since 5.5.0
  36       * @since 5.8.0 Added support for the `blockTypes` property.
  37       *
  38       * @param string $pattern_name       Block pattern name including namespace.
  39       * @param array  $pattern_properties {
  40       *     List of properties for the block pattern.
  41       *
  42       *     @type string $title         Required. A human-readable title for the pattern.
  43       *     @type string $content       Required. Block HTML markup for the pattern.
  44       *     @type string $description   Optional. Visually hidden text used to describe the pattern in the
  45       *                                 inserter. A description is optional, but is strongly
  46       *                                 encouraged when the title does not fully describe what the
  47       *                                 pattern does. The description will help users discover the
  48       *                                 pattern while searching.
  49       *     @type int    $viewportWidth Optional. The intended width of the pattern to allow for a scaled
  50       *                                 preview within the pattern inserter.
  51       *     @type array  $categories    Optional. A list of registered pattern categories used to group block
  52       *                                 patterns. Block patterns can be shown on multiple categories.
  53       *                                 A category must be registered separately in order to be used
  54       *                                 here.
  55       *     @type array  $blockTypes    Optional. A list of block names including namespace that could use
  56       *                                 the block pattern in certain contexts (placeholder, transforms).
  57       *                                 The block pattern is available in the block editor inserter
  58       *                                 regardless of this list of block names.
  59       *                                 Certain blocks support further specificity besides the block name
  60       *                                 (e.g. for `core/template-part` you can specify areas
  61       *                                 like `core/template-part/header` or `core/template-part/footer`).
  62       *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover the
  63       *                                 pattern while searching.
  64       * }
  65       * @return bool True if the pattern was registered with success and false otherwise.
  66       */
  67  	public function register( $pattern_name, $pattern_properties ) {
  68          if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) {
  69              _doing_it_wrong(
  70                  __METHOD__,
  71                  __( 'Pattern name must be a string.' ),
  72                  '5.5.0'
  73              );
  74              return false;
  75          }
  76  
  77          if ( ! isset( $pattern_properties['title'] ) || ! is_string( $pattern_properties['title'] ) ) {
  78              _doing_it_wrong(
  79                  __METHOD__,
  80                  __( 'Pattern title must be a string.' ),
  81                  '5.5.0'
  82              );
  83              return false;
  84          }
  85  
  86          if ( ! isset( $pattern_properties['content'] ) || ! is_string( $pattern_properties['content'] ) ) {
  87              _doing_it_wrong(
  88                  __METHOD__,
  89                  __( 'Pattern content must be a string.' ),
  90                  '5.5.0'
  91              );
  92              return false;
  93          }
  94  
  95          $this->registered_patterns[ $pattern_name ] = array_merge(
  96              $pattern_properties,
  97              array( 'name' => $pattern_name )
  98          );
  99  
 100          return true;
 101      }
 102  
 103      /**
 104       * Unregisters a block pattern.
 105       *
 106       * @since 5.5.0
 107       *
 108       * @param string $pattern_name Block pattern name including namespace.
 109       * @return bool True if the pattern was unregistered with success and false otherwise.
 110       */
 111  	public function unregister( $pattern_name ) {
 112          if ( ! $this->is_registered( $pattern_name ) ) {
 113              _doing_it_wrong(
 114                  __METHOD__,
 115                  /* translators: %s: Pattern name. */
 116                  sprintf( __( 'Pattern "%s" not found.' ), $pattern_name ),
 117                  '5.5.0'
 118              );
 119              return false;
 120          }
 121  
 122          unset( $this->registered_patterns[ $pattern_name ] );
 123  
 124          return true;
 125      }
 126  
 127      /**
 128       * Retrieves an array containing the properties of a registered block pattern.
 129       *
 130       * @since 5.5.0
 131       *
 132       * @param string $pattern_name Block pattern name including namespace.
 133       * @return array Registered pattern properties.
 134       */
 135  	public function get_registered( $pattern_name ) {
 136          if ( ! $this->is_registered( $pattern_name ) ) {
 137              return null;
 138          }
 139  
 140          return $this->registered_patterns[ $pattern_name ];
 141      }
 142  
 143      /**
 144       * Retrieves all registered block patterns.
 145       *
 146       * @since 5.5.0
 147       *
 148       * @return array[] Array of arrays containing the registered block patterns properties,
 149       *                 and per style.
 150       */
 151  	public function get_all_registered() {
 152          return array_values( $this->registered_patterns );
 153      }
 154  
 155      /**
 156       * Checks if a block pattern is registered.
 157       *
 158       * @since 5.5.0
 159       *
 160       * @param string $pattern_name Block pattern name including namespace.
 161       * @return bool True if the pattern is registered, false otherwise.
 162       */
 163  	public function is_registered( $pattern_name ) {
 164          return isset( $this->registered_patterns[ $pattern_name ] );
 165      }
 166  
 167      /**
 168       * Utility method to retrieve the main instance of the class.
 169       *
 170       * The instance will be created if it does not exist yet.
 171       *
 172       * @since 5.5.0
 173       *
 174       * @return WP_Block_Patterns_Registry The main instance.
 175       */
 176  	public static function get_instance() {
 177          if ( null === self::$instance ) {
 178              self::$instance = new self();
 179          }
 180  
 181          return self::$instance;
 182      }
 183  }
 184  
 185  /**
 186   * Registers a new block pattern.
 187   *
 188   * @since 5.5.0
 189   *
 190   * @param string $pattern_name       Block pattern name including namespace.
 191   * @param array  $pattern_properties List of properties for the block pattern.
 192   *                                   See WP_Block_Patterns_Registry::register() for accepted arguments.
 193   * @return bool True if the pattern was registered with success and false otherwise.
 194   */
 195  function register_block_pattern( $pattern_name, $pattern_properties ) {
 196      return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
 197  }
 198  
 199  /**
 200   * Unregisters a block pattern.
 201   *
 202   * @since 5.5.0
 203   *
 204   * @param string $pattern_name Block pattern name including namespace.
 205   * @return bool True if the pattern was unregistered with success and false otherwise.
 206   */
 207  function unregister_block_pattern( $pattern_name ) {
 208      return WP_Block_Patterns_Registry::get_instance()->unregister( $pattern_name );
 209  }