[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Templates registry functions.
   4   *
   5   * @package WordPress
   6   * @since 6.7.0
   7   */
   8  
   9  /**
  10   * Core class used for interacting with templates.
  11   *
  12   * @since 6.7.0
  13   */
  14  final class WP_Block_Templates_Registry {
  15      /**
  16       * Registered templates, as `$name => $instance` pairs.
  17       *
  18       * @since 6.7.0
  19       * @var WP_Block_Template[] $registered_block_templates Registered templates.
  20       */
  21      private $registered_templates = array();
  22  
  23      /**
  24       * Container for the main instance of the class.
  25       *
  26       * @since 6.7.0
  27       * @var WP_Block_Templates_Registry|null
  28       */
  29      private static $instance = null;
  30  
  31      /**
  32       * Registers a template.
  33       *
  34       * @since 6.7.0
  35       *
  36       * @param string $template_name Template name including namespace.
  37       * @param array  $args          Optional. Array of template arguments.
  38       * @return WP_Block_Template|WP_Error The registered template on success, or WP_Error on failure.
  39       *
  40       * @phpstan-param lowercase-string&non-falsy-string $template_name
  41       */
  42  	public function register( $template_name, $args = array() ) {
  43  
  44          $template = null;
  45  
  46          $error_message = '';
  47          $error_code    = '';
  48  
  49          if ( ! is_string( $template_name ) ) {
  50              $error_message = __( 'Template names must be strings.' );
  51              $error_code    = 'template_name_no_string';
  52          } elseif ( preg_match( '/[A-Z]+/', $template_name ) ) {
  53              $error_message = __( 'Template names must not contain uppercase characters.' );
  54              $error_code    = 'template_name_no_uppercase';
  55          } elseif ( ! preg_match( '/^[a-z0-9_\-]+\/\/[a-z0-9_\-]+$/', $template_name ) ) {
  56              $error_message = __( 'Template names must contain a namespace prefix. Example: my-plugin//my-custom-template' );
  57              $error_code    = 'template_no_prefix';
  58          } elseif ( $this->is_registered( $template_name ) ) {
  59              /* translators: %s: Template name. */
  60              $error_message = sprintf( __( 'Template "%s" is already registered.' ), $template_name );
  61              $error_code    = 'template_already_registered';
  62          }
  63  
  64          if ( $error_message ) {
  65              _doing_it_wrong( __METHOD__, $error_message, '6.7.0' );
  66  
  67              return new WP_Error( $error_code, $error_message );
  68          }
  69  
  70          if ( ! $template ) {
  71              $theme_name             = get_stylesheet();
  72              list( $plugin, $slug )  = explode( '//', $template_name );
  73              $default_template_types = get_default_block_template_types();
  74  
  75              $template              = new WP_Block_Template();
  76              $template->id          = $theme_name . '//' . $slug;
  77              $template->theme       = $theme_name;
  78              $template->plugin      = $plugin;
  79              $template->author      = null;
  80              $template->content     = $args['content'] ?? '';
  81              $template->source      = 'plugin';
  82              $template->slug        = $slug;
  83              $template->type        = 'wp_template';
  84              $template->title       = $args['title'] ?? $template_name;
  85              $template->description = $args['description'] ?? '';
  86              $template->status      = 'publish';
  87              $template->origin      = 'plugin';
  88              $template->is_custom   = ! isset( $default_template_types[ $template_name ] );
  89              $template->post_types  = $args['post_types'] ?? array();
  90          }
  91  
  92          $this->registered_templates[ $template_name ] = $template;
  93  
  94          return $template;
  95      }
  96  
  97      /**
  98       * Retrieves all registered templates.
  99       *
 100       * @since 6.7.0
 101       *
 102       * @return WP_Block_Template[] Associative array of `$template_name => $template` pairs.
 103       */
 104  	public function get_all_registered() {
 105          return $this->registered_templates;
 106      }
 107  
 108      /**
 109       * Retrieves a registered template by its name.
 110       *
 111       * @since 6.7.0
 112       *
 113       * @param string $template_name Template name including namespace.
 114       * @return WP_Block_Template|null The registered template, or null if it is not registered.
 115       */
 116  	public function get_registered( $template_name ) {
 117          if ( ! $this->is_registered( $template_name ) ) {
 118              return null;
 119          }
 120  
 121          return $this->registered_templates[ $template_name ];
 122      }
 123  
 124      /**
 125       * Retrieves a registered template by its slug.
 126       *
 127       * @since 6.7.0
 128       *
 129       * @param string $template_slug Slug of the template.
 130       * @return WP_Block_Template|null The registered template, or null if it is not registered.
 131       */
 132  	public function get_by_slug( $template_slug ) {
 133          $all_templates = $this->get_all_registered();
 134  
 135          if ( ! $all_templates ) {
 136              return null;
 137          }
 138  
 139          foreach ( $all_templates as $template ) {
 140              if ( $template->slug === $template_slug ) {
 141                  return $template;
 142              }
 143          }
 144  
 145          return null;
 146      }
 147  
 148      /**
 149       * Retrieves registered templates matching a query.
 150       *
 151       * @since 6.7.0
 152       *
 153       * @param array  $query {
 154       *     Arguments to retrieve templates. Optional, empty by default.
 155       *
 156       *     @type string[] $slug__in     List of slugs to include.
 157       *     @type string[] $slug__not_in List of slugs to skip.
 158       *     @type string   $post_type    Post type to get the templates for.
 159       * }
 160       * @return WP_Block_Template[] Associative array of `$template_name => $template` pairs.
 161       */
 162  	public function get_by_query( $query = array() ) {
 163          $all_templates = $this->get_all_registered();
 164  
 165          if ( ! $all_templates ) {
 166              return array();
 167          }
 168  
 169          $query            = wp_parse_args(
 170              $query,
 171              array(
 172                  'slug__in'     => array(),
 173                  'slug__not_in' => array(),
 174                  'post_type'    => '',
 175              )
 176          );
 177          $slugs_to_include = $query['slug__in'];
 178          $slugs_to_skip    = $query['slug__not_in'];
 179          $post_type        = $query['post_type'];
 180  
 181          $matching_templates = array();
 182          foreach ( $all_templates as $template_name => $template ) {
 183              if ( $slugs_to_include && ! in_array( $template->slug, $slugs_to_include, true ) ) {
 184                  continue;
 185              }
 186  
 187              if ( $slugs_to_skip && in_array( $template->slug, $slugs_to_skip, true ) ) {
 188                  continue;
 189              }
 190  
 191              if ( $post_type && ! in_array( $post_type, $template->post_types, true ) ) {
 192                  continue;
 193              }
 194  
 195              $matching_templates[ $template_name ] = $template;
 196          }
 197  
 198          return $matching_templates;
 199      }
 200  
 201      /**
 202       * Checks if a template is registered.
 203       *
 204       * @since 6.7.0
 205       *
 206       * @param string|null $template_name Template name.
 207       * @return bool True if the template is registered, false otherwise.
 208       */
 209  	public function is_registered( $template_name ) {
 210          return isset( $template_name, $this->registered_templates[ $template_name ] );
 211      }
 212  
 213      /**
 214       * Unregisters a template.
 215       *
 216       * @since 6.7.0
 217       *
 218       * @param string $template_name Template name including namespace.
 219       * @return WP_Block_Template|WP_Error The unregistered template on success, or WP_Error on failure.
 220       */
 221  	public function unregister( $template_name ) {
 222          if ( ! $this->is_registered( $template_name ) ) {
 223              /* translators: %s: Template name. */
 224              $error_message = sprintf( __( 'Template "%s" is not registered.' ), $template_name );
 225  
 226              _doing_it_wrong( __METHOD__, $error_message, '6.7.0' );
 227  
 228              return new WP_Error( 'template_not_registered', $error_message );
 229          }
 230  
 231          $unregistered_template = $this->registered_templates[ $template_name ];
 232          unset( $this->registered_templates[ $template_name ] );
 233  
 234          return $unregistered_template;
 235      }
 236  
 237      /**
 238       * Utility method to retrieve the main instance of the class.
 239       *
 240       * The instance will be created if it does not exist yet.
 241       *
 242       * @since 6.7.0
 243       *
 244       * @return WP_Block_Templates_Registry The main instance.
 245       */
 246  	public static function get_instance() {
 247          self::$instance ??= new self();
 248  
 249          return self::$instance;
 250      }
 251  }