[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       * @since 5.5.0
  37       * @var string
  38       */
  39      public $title = '';
  40  
  41      /**
  42       * @since 5.5.0
  43       * @var string|null
  44       */
  45      public $category = null;
  46  
  47      /**
  48       * @since 5.5.0
  49       * @var array|null
  50       */
  51      public $parent = null;
  52  
  53      /**
  54       * @since 5.5.0
  55       * @var string|null
  56       */
  57      public $icon = null;
  58  
  59      /**
  60       * @since 5.5.0
  61       * @var string
  62       */
  63      public $description = '';
  64  
  65      /**
  66       * @since 5.5.0
  67       * @var array
  68       */
  69      public $keywords = array();
  70  
  71      /**
  72       * @since 5.5.0
  73       * @var string|null
  74       */
  75      public $textdomain = null;
  76  
  77      /**
  78       * @since 5.5.0
  79       * @var array
  80       */
  81      public $styles = array();
  82  
  83      /**
  84       * @since 5.5.0
  85       * @var array|null
  86       */
  87      public $supports = null;
  88  
  89      /**
  90       * @since 5.5.0
  91       * @var array|null
  92       */
  93      public $example = null;
  94  
  95      /**
  96       * Block type render callback.
  97       *
  98       * @since 5.0.0
  99       * @var callable
 100       */
 101      public $render_callback = null;
 102  
 103      /**
 104       * Block type attributes property schemas.
 105       *
 106       * @since 5.0.0
 107       * @var array|null
 108       */
 109      public $attributes = null;
 110  
 111      /**
 112       * Context values inherited by blocks of this type.
 113       *
 114       * @since 5.5.0
 115       * @var array
 116       */
 117      public $uses_context = array();
 118  
 119      /**
 120       * Context provided by blocks of this type.
 121       *
 122       * @since 5.5.0
 123       * @var array|null
 124       */
 125      public $provides_context = null;
 126  
 127      /**
 128       * Block type editor script handle.
 129       *
 130       * @since 5.0.0
 131       * @var string|null
 132       */
 133      public $editor_script = null;
 134  
 135      /**
 136       * Block type front end script handle.
 137       *
 138       * @since 5.0.0
 139       * @var string|null
 140       */
 141      public $script = null;
 142  
 143      /**
 144       * Block type editor style handle.
 145       *
 146       * @since 5.0.0
 147       * @var string|null
 148       */
 149      public $editor_style = null;
 150  
 151      /**
 152       * Block type front end style handle.
 153       *
 154       * @since 5.0.0
 155       * @var string|null
 156       */
 157      public $style = null;
 158  
 159      /**
 160       * Constructor.
 161       *
 162       * Will populate object properties from the provided arguments.
 163       *
 164       * @since 5.0.0
 165       *
 166       * @see register_block_type()
 167       *
 168       * @param string       $block_type Block type name including namespace.
 169       * @param array|string $args       Optional. Array or string of arguments for registering a block type.
 170       *                                 Default empty array.
 171       */
 172  	public function __construct( $block_type, $args = array() ) {
 173          $this->name = $block_type;
 174  
 175          $this->set_props( $args );
 176      }
 177  
 178      /**
 179       * Renders the block type output for given attributes.
 180       *
 181       * @since 5.0.0
 182       *
 183       * @param array  $attributes Optional. Block attributes. Default empty array.
 184       * @param string $content    Optional. Block content. Default empty string.
 185       * @return string Rendered block type output.
 186       */
 187  	public function render( $attributes = array(), $content = '' ) {
 188          if ( ! $this->is_dynamic() ) {
 189              return '';
 190          }
 191  
 192          $attributes = $this->prepare_attributes_for_render( $attributes );
 193  
 194          return (string) call_user_func( $this->render_callback, $attributes, $content );
 195      }
 196  
 197      /**
 198       * Returns true if the block type is dynamic, or false otherwise. A dynamic
 199       * block is one which defers its rendering to occur on-demand at runtime.
 200       *
 201       * @since 5.0.0
 202       *
 203       * @return bool Whether block type is dynamic.
 204       */
 205  	public function is_dynamic() {
 206          return is_callable( $this->render_callback );
 207      }
 208  
 209      /**
 210       * Validates attributes against the current block schema, populating
 211       * defaulted and missing values.
 212       *
 213       * @since 5.0.0
 214       *
 215       * @param array $attributes Original block attributes.
 216       * @return array Prepared block attributes.
 217       */
 218  	public function prepare_attributes_for_render( $attributes ) {
 219          // If there are no attribute definitions for the block type, skip
 220          // processing and return verbatim.
 221          if ( ! isset( $this->attributes ) ) {
 222              return $attributes;
 223          }
 224  
 225          foreach ( $attributes as $attribute_name => $value ) {
 226              // If the attribute is not defined by the block type, it cannot be
 227              // validated.
 228              if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
 229                  continue;
 230              }
 231  
 232              $schema = $this->attributes[ $attribute_name ];
 233  
 234              // Validate value by JSON schema. An invalid value should revert to
 235              // its default, if one exists. This occurs by virtue of the missing
 236              // attributes loop immediately following. If there is not a default
 237              // assigned, the attribute value should remain unset.
 238              $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
 239              if ( is_wp_error( $is_valid ) ) {
 240                  unset( $attributes[ $attribute_name ] );
 241              }
 242          }
 243  
 244          // Populate values of any missing attributes for which the block type
 245          // defines a default.
 246          $missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
 247          foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
 248              if ( isset( $schema['default'] ) ) {
 249                  $attributes[ $attribute_name ] = $schema['default'];
 250              }
 251          }
 252  
 253          return $attributes;
 254      }
 255  
 256      /**
 257       * Sets block type properties.
 258       *
 259       * @since 5.0.0
 260       *
 261       * @param array|string $args Array or string of arguments for registering a block type.
 262       */
 263  	public function set_props( $args ) {
 264          $args = wp_parse_args(
 265              $args,
 266              array(
 267                  'render_callback' => null,
 268              )
 269          );
 270  
 271          $args['name'] = $this->name;
 272  
 273          /**
 274           * Filters the arguments for registering a block type.
 275           *
 276           * @since 5.5.0
 277           *
 278           * @param array  $args       Array of arguments for registering a block type.
 279           * @param string $block_type Block type name including namespace.
 280           */
 281          $args = apply_filters( 'register_block_type_args', $args, $this->name );
 282  
 283          foreach ( $args as $property_name => $property_value ) {
 284              $this->$property_name = $property_value;
 285          }
 286      }
 287  
 288      /**
 289       * Get all available block attributes including possible layout attribute from Columns block.
 290       *
 291       * @since 5.0.0
 292       *
 293       * @return array Array of attributes.
 294       */
 295  	public function get_attributes() {
 296          return is_array( $this->attributes ) ?
 297              $this->attributes :
 298              array();
 299      }
 300  }