[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_Pattern_Categories_Registry class
   4   *
   5   * @package WordPress
   6   * @subpackage Blocks
   7   * @since 5.5.0
   8   */
   9  
  10  /**
  11   * Class used for interacting with block pattern categories.
  12   */
  13  #[AllowDynamicProperties]
  14  final class WP_Block_Pattern_Categories_Registry {
  15      /**
  16       * Registered block pattern categories array.
  17       *
  18       * @since 5.5.0
  19       * @var array[]
  20       */
  21      private $registered_categories = array();
  22  
  23      /**
  24       * Pattern categories registered outside the `init` action.
  25       *
  26       * @since 6.0.0
  27       * @var array[]
  28       */
  29      private $registered_categories_outside_init = array();
  30  
  31      /**
  32       * Container for the main instance of the class.
  33       *
  34       * @since 5.5.0
  35       * @var WP_Block_Pattern_Categories_Registry|null
  36       */
  37      private static $instance = null;
  38  
  39      /**
  40       * Registers a pattern category.
  41       *
  42       * @since 5.5.0
  43       * @since 6.2.0 Added support for the `description` property.
  44       *
  45       * @param string $category_name       Pattern category name including namespace.
  46       * @param array  $category_properties {
  47       *     List of properties for the block pattern category.
  48       *
  49       *     @type string $label       Required. A human-readable label for the pattern category.
  50       *     @type string $description Optional. A human-readable description of the pattern category.
  51       * }
  52       * @return bool True if the pattern category was registered with success and false otherwise.
  53       */
  54  	public function register( $category_name, $category_properties ) {
  55          if ( ! isset( $category_name ) || ! is_string( $category_name ) ) {
  56              _doing_it_wrong(
  57                  __METHOD__,
  58                  __( 'Block pattern category name must be a string.' ),
  59                  '5.5.0'
  60              );
  61              return false;
  62          }
  63  
  64          $category = array_merge(
  65              array( 'name' => $category_name ),
  66              $category_properties
  67          );
  68  
  69          $this->registered_categories[ $category_name ] = $category;
  70  
  71          // If the category is registered inside an action other than `init`, store it
  72          // also to a dedicated array. Used to detect deprecated registrations inside
  73          // `admin_init` or `current_screen`.
  74          if ( current_action() && 'init' !== current_action() ) {
  75              $this->registered_categories_outside_init[ $category_name ] = $category;
  76          }
  77  
  78          return true;
  79      }
  80  
  81      /**
  82       * Unregisters a pattern category.
  83       *
  84       * @since 5.5.0
  85       *
  86       * @param string $category_name Pattern category name including namespace.
  87       * @return bool True if the pattern was unregistered with success and false otherwise.
  88       */
  89  	public function unregister( $category_name ) {
  90          if ( ! $this->is_registered( $category_name ) ) {
  91              _doing_it_wrong(
  92                  __METHOD__,
  93                  /* translators: %s: Block pattern name. */
  94                  sprintf( __( 'Block pattern category "%s" not found.' ), $category_name ),
  95                  '5.5.0'
  96              );
  97              return false;
  98          }
  99  
 100          unset( $this->registered_categories[ $category_name ] );
 101          unset( $this->registered_categories_outside_init[ $category_name ] );
 102  
 103          return true;
 104      }
 105  
 106      /**
 107       * Retrieves an array containing the properties of a registered pattern category.
 108       *
 109       * @since 5.5.0
 110       *
 111       * @param string $category_name Pattern category name including namespace.
 112       * @return array|null Registered pattern properties, or `null` if the pattern category is not registered.
 113       */
 114  	public function get_registered( $category_name ) {
 115          if ( ! $this->is_registered( $category_name ) ) {
 116              return null;
 117          }
 118  
 119          return $this->registered_categories[ $category_name ];
 120      }
 121  
 122      /**
 123       * Retrieves all registered pattern categories.
 124       *
 125       * @since 5.5.0
 126       *
 127       * @param bool $outside_init_only Return only categories registered outside the `init` action.
 128       * @return array[] Array of arrays containing the registered pattern categories properties.
 129       */
 130  	public function get_all_registered( $outside_init_only = false ) {
 131          return array_values(
 132              $outside_init_only
 133                  ? $this->registered_categories_outside_init
 134                  : $this->registered_categories
 135          );
 136      }
 137  
 138      /**
 139       * Checks if a pattern category is registered.
 140       *
 141       * @since 5.5.0
 142       *
 143       * @param string|null $category_name Pattern category name including namespace.
 144       * @return bool True if the pattern category is registered, false otherwise.
 145       */
 146  	public function is_registered( $category_name ) {
 147          return isset( $category_name, $this->registered_categories[ $category_name ] );
 148      }
 149  
 150      /**
 151       * Utility method to retrieve the main instance of the class.
 152       *
 153       * The instance will be created if it does not exist yet.
 154       *
 155       * @since 5.5.0
 156       *
 157       * @return WP_Block_Pattern_Categories_Registry The main instance.
 158       */
 159  	public static function get_instance() {
 160          self::$instance ??= new self();
 161  
 162          return self::$instance;
 163      }
 164  }