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