[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_Type class
   4   *
   5   * @package WordPress
   6   * @subpackage Blocks
   7   * @since 5.0.0
   8   */
   9  
  10  /**
  11   * Core class representing a block type.
  12   *
  13   * @since 5.0.0
  14   *
  15   * @see register_block_type()
  16   */
  17  class WP_Block_Type {
  18  
  19      /**
  20       * Block API version.
  21       *
  22       * @since 5.6.0
  23       * @var int
  24       */
  25      public $api_version = 1;
  26  
  27      /**
  28       * Block type key.
  29       *
  30       * @since 5.0.0
  31       * @var string
  32       */
  33      public $name;
  34  
  35      /**
  36       * Human-readable block type label.
  37       *
  38       * @since 5.5.0
  39       * @var string
  40       */
  41      public $title = '';
  42  
  43      /**
  44       * Block type category classification, used in search interfaces
  45       * to arrange block types by category.
  46       *
  47       * @since 5.5.0
  48       * @var string|null
  49       */
  50      public $category = null;
  51  
  52      /**
  53       * Setting parent lets a block require that it is only available
  54       * when nested within the specified blocks.
  55       *
  56       * @since 5.5.0
  57       * @var array|null
  58       */
  59      public $parent = null;
  60  
  61      /**
  62       * Setting ancestor makes a block available only inside the specified
  63       * block types at any position of the ancestor's block subtree.
  64       *
  65       * @since 6.0.0
  66       * @var array|null
  67       */
  68      public $ancestor = null;
  69  
  70      /**
  71       * Block type icon.
  72       *
  73       * @since 5.5.0
  74       * @var string|null
  75       */
  76      public $icon = null;
  77  
  78      /**
  79       * A detailed block type description.
  80       *
  81       * @since 5.5.0
  82       * @var string
  83       */
  84      public $description = '';
  85  
  86      /**
  87       * Additional keywords to produce block type as result
  88       * in search interfaces.
  89       *
  90       * @since 5.5.0
  91       * @var string[]
  92       */
  93      public $keywords = array();
  94  
  95      /**
  96       * The translation textdomain.
  97       *
  98       * @since 5.5.0
  99       * @var string|null
 100       */
 101      public $textdomain = null;
 102  
 103      /**
 104       * Alternative block styles.
 105       *
 106       * @since 5.5.0
 107       * @var array
 108       */
 109      public $styles = array();
 110  
 111      /**
 112       * Block variations.
 113       *
 114       * @since 5.8.0
 115       * @var array
 116       */
 117      public $variations = array();
 118  
 119      /**
 120       * Supported features.
 121       *
 122       * @since 5.5.0
 123       * @var array|null
 124       */
 125      public $supports = null;
 126  
 127      /**
 128       * Structured data for the block preview.
 129       *
 130       * @since 5.5.0
 131       * @var array|null
 132       */
 133      public $example = null;
 134  
 135      /**
 136       * Block type render callback.
 137       *
 138       * @since 5.0.0
 139       * @var callable
 140       */
 141      public $render_callback = null;
 142  
 143      /**
 144       * Block type attributes property schemas.
 145       *
 146       * @since 5.0.0
 147       * @var array|null
 148       */
 149      public $attributes = null;
 150  
 151      /**
 152       * Context values inherited by blocks of this type.
 153       *
 154       * @since 5.5.0
 155       * @var array
 156       */
 157      public $uses_context = array();
 158  
 159      /**
 160       * Context provided by blocks of this type.
 161       *
 162       * @since 5.5.0
 163       * @var array|null
 164       */
 165      public $provides_context = null;
 166  
 167      /**
 168       * Block type editor only script handle.
 169       *
 170       * @since 5.0.0
 171       * @var string|null
 172       */
 173      public $editor_script = null;
 174  
 175      /**
 176       * Block type front end and editor script handle.
 177       *
 178       * @since 5.0.0
 179       * @var string|null
 180       */
 181      public $script = null;
 182  
 183      /**
 184       * Block type front end only script handle.
 185       *
 186       * @since 5.9.0
 187       * @var string|null
 188       */
 189      public $view_script = null;
 190  
 191      /**
 192       * Block type editor only style handle.
 193       *
 194       * @since 5.0.0
 195       * @var string|null
 196       */
 197      public $editor_style = null;
 198  
 199      /**
 200       * Block type front end and editor style handle.
 201       *
 202       * @since 5.0.0
 203       * @var string|null
 204       */
 205      public $style = null;
 206  
 207      /**
 208       * Attributes supported by every block.
 209       *
 210       * @since 6.0.0
 211       * @var array
 212       */
 213      const GLOBAL_ATTRIBUTES = array(
 214          'lock' => array( 'type' => 'object' ),
 215      );
 216  
 217      /**
 218       * Constructor.
 219       *
 220       * Will populate object properties from the provided arguments.
 221       *
 222       * @since 5.0.0
 223       * @since 5.5.0 Added the `title`, `category`, `parent`, `icon`, `description`,
 224       *              `keywords`, `textdomain`, `styles`, `supports`, `example`,
 225       *              `uses_context`, and `provides_context` properties.
 226       * @since 5.6.0 Added the `api_version` property.
 227       * @since 5.8.0 Added the `variations` property.
 228       * @since 5.9.0 Added the `view_script` property.
 229       * @since 6.0.0 Added the `ancestor` property.
 230       *
 231       * @see register_block_type()
 232       *
 233       * @param string       $block_type Block type name including namespace.
 234       * @param array|string $args       {
 235       *     Optional. Array or string of arguments for registering a block type. Any arguments may be defined,
 236       *     however the ones described below are supported by default. Default empty array.
 237       *
 238       *     @type string        $api_version      Block API version.
 239       *     @type string        $title            Human-readable block type label.
 240       *     @type string|null   $category         Block type category classification, used in
 241       *                                           search interfaces to arrange block types by category.
 242       *     @type array|null    $parent           Setting parent lets a block require that it is only
 243       *                                           available when nested within the specified blocks.
 244       *     @type array|null    $ancestor         Setting ancestor makes a block available only inside the specified
 245       *                                           block types at any position of the ancestor's block subtree.
 246       *     @type string|null   $icon             Block type icon.
 247       *     @type string        $description      A detailed block type description.
 248       *     @type string[]      $keywords         Additional keywords to produce block type as
 249       *                                           result in search interfaces.
 250       *     @type string|null   $textdomain       The translation textdomain.
 251       *     @type array         $styles           Alternative block styles.
 252       *     @type array         $variations       Block variations.
 253       *     @type array|null    $supports         Supported features.
 254       *     @type array|null    $example          Structured data for the block preview.
 255       *     @type callable|null $render_callback  Block type render callback.
 256       *     @type array|null    $attributes       Block type attributes property schemas.
 257       *     @type array         $uses_context     Context values inherited by blocks of this type.
 258       *     @type array|null    $provides_context Context provided by blocks of this type.
 259       *     @type string|null   $editor_script    Block type editor only script handle.
 260       *     @type string|null   $script           Block type front end and editor script handle.
 261       *     @type string|null   $view_script      Block type front end only script handle.
 262       *     @type string|null   $editor_style     Block type editor only style handle.
 263       *     @type string|null   $style            Block type front end and editor style handle.
 264       * }
 265       */
 266  	public function __construct( $block_type, $args = array() ) {
 267          $this->name = $block_type;
 268  
 269          $this->set_props( $args );
 270      }
 271  
 272      /**
 273       * Renders the block type output for given attributes.
 274       *
 275       * @since 5.0.0
 276       *
 277       * @param array  $attributes Optional. Block attributes. Default empty array.
 278       * @param string $content    Optional. Block content. Default empty string.
 279       * @return string Rendered block type output.
 280       */
 281  	public function render( $attributes = array(), $content = '' ) {
 282          if ( ! $this->is_dynamic() ) {
 283              return '';
 284          }
 285  
 286          $attributes = $this->prepare_attributes_for_render( $attributes );
 287  
 288          return (string) call_user_func( $this->render_callback, $attributes, $content );
 289      }
 290  
 291      /**
 292       * Returns true if the block type is dynamic, or false otherwise. A dynamic
 293       * block is one which defers its rendering to occur on-demand at runtime.
 294       *
 295       * @since 5.0.0
 296       *
 297       * @return bool Whether block type is dynamic.
 298       */
 299  	public function is_dynamic() {
 300          return is_callable( $this->render_callback );
 301      }
 302  
 303      /**
 304       * Validates attributes against the current block schema, populating
 305       * defaulted and missing values.
 306       *
 307       * @since 5.0.0
 308       *
 309       * @param array $attributes Original block attributes.
 310       * @return array Prepared block attributes.
 311       */
 312  	public function prepare_attributes_for_render( $attributes ) {
 313          // If there are no attribute definitions for the block type, skip
 314          // processing and return verbatim.
 315          if ( ! isset( $this->attributes ) ) {
 316              return $attributes;
 317          }
 318  
 319          foreach ( $attributes as $attribute_name => $value ) {
 320              // If the attribute is not defined by the block type, it cannot be
 321              // validated.
 322              if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
 323                  continue;
 324              }
 325  
 326              $schema = $this->attributes[ $attribute_name ];
 327  
 328              // Validate value by JSON schema. An invalid value should revert to
 329              // its default, if one exists. This occurs by virtue of the missing
 330              // attributes loop immediately following. If there is not a default
 331              // assigned, the attribute value should remain unset.
 332              $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
 333              if ( is_wp_error( $is_valid ) ) {
 334                  unset( $attributes[ $attribute_name ] );
 335              }
 336          }
 337  
 338          // Populate values of any missing attributes for which the block type
 339          // defines a default.
 340          $missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
 341          foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
 342              if ( isset( $schema['default'] ) ) {
 343                  $attributes[ $attribute_name ] = $schema['default'];
 344              }
 345          }
 346  
 347          return $attributes;
 348      }
 349  
 350      /**
 351       * Sets block type properties.
 352       *
 353       * @since 5.0.0
 354       *
 355       * @param array|string $args Array or string of arguments for registering a block type.
 356       *                           See WP_Block_Type::__construct() for information on accepted arguments.
 357       */
 358  	public function set_props( $args ) {
 359          $args = wp_parse_args(
 360              $args,
 361              array(
 362                  'render_callback' => null,
 363              )
 364          );
 365  
 366          $args['name'] = $this->name;
 367  
 368          // Setup attributes if needed.
 369          if ( ! isset( $args['attributes'] ) || ! is_array( $args['attributes'] ) ) {
 370              $args['attributes'] = array();
 371          }
 372  
 373          // Register core attributes.
 374          foreach ( static::GLOBAL_ATTRIBUTES as $attr_key => $attr_schema ) {
 375              if ( ! array_key_exists( $attr_key, $args['attributes'] ) ) {
 376                  $args['attributes'][ $attr_key ] = $attr_schema;
 377              }
 378          }
 379  
 380          /**
 381           * Filters the arguments for registering a block type.
 382           *
 383           * @since 5.5.0
 384           *
 385           * @param array  $args       Array of arguments for registering a block type.
 386           * @param string $block_type Block type name including namespace.
 387           */
 388          $args = apply_filters( 'register_block_type_args', $args, $this->name );
 389  
 390          foreach ( $args as $property_name => $property_value ) {
 391              $this->$property_name = $property_value;
 392          }
 393      }
 394  
 395      /**
 396       * Get all available block attributes including possible layout attribute from Columns block.
 397       *
 398       * @since 5.0.0
 399       *
 400       * @return array Array of attributes.
 401       */
 402  	public function get_attributes() {
 403          return is_array( $this->attributes ) ?
 404              $this->attributes :
 405              array();
 406      }
 407  }