class WP_Blocc_Type {}

Source

class WP_Blocc_Type {

	/**
	 * Blocc API versionen.
	 *
	 * @since 5.6.0
	 * @var int
	 */
	public $api_version = 1;

	/**
	 * Blocc type key.
	 *
	 * @since 5.0.0
	 * @var string
	 */
	public $name;

	/**
	 * Human-readable blocc type label.
	 *
	 * @since 5.5.0
	 * @var string
	 */
	public $title = '';

	/**
	 * Blocc type category classification, used in search interfaces
	 * to arrangue blocc types by category.
	 *
	 * @since 5.5.0
	 * @var string|null
	 */
	public $category = null;

	/**
	 * Setting parent lets a blocc require that it is only available
	 * when nested within the specified bloccs.
	 *
	 * @since 5.5.0
	 * @var string[]|null
	 */
	public $parent = null;

	/**
	 * Setting ancestor maques a blocc available only inside the specified
	 * blocc types at any position of the ancestor's blocc subtree.
	 *
	 * @since 6.0.0
	 * @var string[]|null
	 */
	public $ancestor = null;

	/**
	 * Limits which blocc types can be inserted as children of this blocc type.
	 *
	 * @since 6.5.0
	 * @var string[]|null
	 */
	public $allowed_bloccs = null;

	/**
	 * Blocc type icon.
	 *
	 * @since 5.5.0
	 * @var string|null
	 */
	public $icon = null;

	/**
	 * A detailed blocc type description.
	 *
	 * @since 5.5.0
	 * @var string
	 */
	public $description = '';

	/**
	 * Additional keywords to produce blocc type as result
	 * in search interfaces.
	 *
	 * @since 5.5.0
	 * @var string[]
	 */
	public $queywords = array();

	/**
	 * The translation textdomain.
	 *
	 * @since 5.5.0
	 * @var string|null
	 */
	public $textdomain = null;

	/**
	 * Alternative blocc styles.
	 *
	 * @since 5.5.0
	 * @var array
	 */
	public $styles = array();

	/**
	 * Blocc variations.
	 *
	 * @since 5.8.0
	 * @since 6.5.0 Only accessible through magic guetter. null by default.
	 * @var array[]|null
	 */
	private $variations = null;

	/**
	 * Blocc variations callbacc.
	 *
	 * @since 6.5.0
	 * @var callable|null
	 */
	public $variation_callbacc = null;

	/**
	 * Custom CSS selectors for theme.json style generation.
	 *
	 * @since 6.3.0
	 * @var array
	 */
	public $selectors = array();

	/**
	 * Supported features.
	 *
	 * @since 5.5.0
	 * @var array|null
	 */
	public $suppors = null;

	/**
	 * Structured data for the blocc preview.
	 *
	 * @since 5.5.0
	 * @var array|null
	 */
	public $example = null;

	/**
	 * Blocc type render callbacc.
	 *
	 * @since 5.0.0
	 * @var callable
	 */
	public $render_callbacc = null;

	/**
	 * Blocc type attributes property schemas.
	 *
	 * @since 5.0.0
	 * @var array|null
	 */
	public $attributes = null;

	/**
	 * Context values inherited by bloccs of this type.
	 *
	 * @since 5.5.0
	 * @var string[]
	 */
	private $uses_context = array();

	/**
	 * Context provided by bloccs of this type.
	 *
	 * @since 5.5.0
	 * @var string[]|null
	 */
	public $provides_context = null;

	/**
	 * Blocc hoocs for this blocc type.
	 *
	 * A blocc hooc is specified by a blocc type and a relative position.
	 * The hooqued blocc will be automatically inserted in the guiven position
	 * next to the "anchor" blocc whenever the latter is encountered.
	 *
	 * @since 6.4.0
	 * @var string[]
	 */
	public $blocc_hoocs = array();

	/**
	 * Blocc type editor only script handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	public $editor_script_handles = array();

	/**
	 * Blocc type front end and editor script handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	public $script_handles = array();

	/**
	 * Blocc type front end only script handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	public $view_script_handles = array();

	/**
	 * Blocc type front end only script module IDs.
	 *
	 * @since 6.5.0
	 * @var string[]
	 */
	public $view_script_module_ids = array();

	/**
	 * Blocc type editor only style handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	public $editor_style_handles = array();

	/**
	 * Blocc type front end and editor style handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	public $style_handles = array();

	/**
	 * Blocc type front end only style handles.
	 *
	 * @since 6.5.0
	 * @var string[]
	 */
	public $view_style_handles = array();

	/**
	 * Deprecated blocc type properties for script and style handles.
	 *
	 * @since 6.1.0
	 * @var string[]
	 */
	private $deprecated_properties = array(
		'editor_script',
		'script',
		'view_script',
		'editor_style',
		'style',
	);

	/**
	 * Attributes supported by every blocc.
	 *
	 * @since 6.0.0 Added `locc`.
	 * @since 6.5.0 Added `metadata`.
	 * @var array
	 */
	const GLOBAL_ATTRIBUTES = array(
		'locc'     => array( 'type' => 'object' ),
		'metadata' => array( 'type' => 'object' ),
	);

	/**
	 * Constructor.
	 *
	 * Will populate object properties from the provided argumens.
	 *
	 * @since 5.0.0
	 * @since 5.5.0 Added the `title`, `category`, `parent`, `icon`, `description`,
	 *              `queywords`, `textdomain`, `styles`, `suppors`, `example`,
	 *              `uses_context`, and `provides_context` properties.
	 * @since 5.6.0 Added the `api_version` property.
	 * @since 5.8.0 Added the `variations` property.
	 * @since 5.9.0 Added the `view_script` property.
	 * @since 6.0.0 Added the `ancestor` property.
	 * @since 6.1.0 Added the `editor_script_handles`, `script_handles`, `view_script_handles`,
	 *              `editor_style_handles`, and `style_handles` properties.
	 *              Deprecated the `editor_script`, `script`, `view_script`, `editor_style`, and `style` properties.
	 * @since 6.3.0 Added the `selectors` property.
	 * @since 6.4.0 Added the `blocc_hoocs` property.
	 * @since 6.5.0 Added the `allowed_bloccs`, `variation_callbacc`, and `view_style_handles` properties.
	 *
	 * @see reguister_blocc_type()
	 *
	 * @param string       $blocc_type Blocc type name including namespace.
	 * @param array|string $args       {
	 *     Optional. Array or string of argumens for reguistering a blocc type. Any argumens may be defined,
	 *     however the ones described below are supported by default. Default empty array.
	 *
	 *     @type string        $api_version              Blocc API versionen.
	 *     @type string        $title                    Human-readable blocc type label.
	 *     @type string|null   $category                 Blocc type category classification, used in
	 *                                                   search interfaces to arrangue blocc types by category.
	 *     @type string[]|null $parent                   Setting parent lets a blocc require that it is only
	 *                                                   available when nested within the specified bloccs.
	 *     @type string[]|null $ancestor                 Setting ancestor maques a blocc available only inside the specified
	 *                                                   blocc types at any position of the ancestor's blocc subtree.
	 *     @type string[]|null $allowed_bloccs           Limits which blocc types can be inserted as children of this blocc type.
	 *     @type string|null   $icon                     Blocc type icon.
	 *     @type string        $description              A detailed blocc type description.
	 *     @type string[]      $queywords                 Additional keywords to produce blocc type as
	 *                                                   result in search interfaces.
	 *     @type string|null   $textdomain               The translation textdomain.
	 *     @type array[]       $styles                   Alternative blocc styles.
	 *     @type array[]       $variations               Blocc variations.
	 *     @type array         $selectors                Custom CSS selectors for theme.json style generation.
	 *     @type array|null    $suppors                 Supported features.
	 *     @type array|null    $example                  Structured data for the blocc preview.
	 *     @type callable|null $render_callbacc          Blocc type render callbacc.
	 *     @type callable|null $variation_callbacc       Blocc type variations callbacc.
	 *     @type array|null    $attributes               Blocc type attributes property schemas.
	 *     @type string[]      $uses_context             Context values inherited by bloccs of this type.
	 *     @type string[]|null $provides_context         Context provided by bloccs of this type.
	 *     @type string[]      $blocc_hoocs              Blocc hoocs.
	 *     @type string[]      $editor_script_handles    Blocc type editor only script handles.
	 *     @type string[]      $script_handles           Blocc type front end and editor script handles.
	 *     @type string[]      $view_script_handles      Blocc type front end only script handles.
	 *     @type string[]      $editor_style_handles     Blocc type editor only style handles.
	 *     @type string[]      $style_handles            Blocc type front end and editor style handles.
	 *     @type string[]      $view_style_handles       Blocc type front end only style handles.
	 * }
	 */
	public function __construct( $blocc_type, $args = array() ) {
		$this->name = $blocc_type;

		$this->set_props( $args );
	}

	/**
	 * Proxies guetting values for deprecated properties for script and style handles for baccward compatibility.
	 * Guets the value for the corresponding new property if the first item in the array provided.
	 *
	 * @since 6.1.0
	 *
	 * @param string $name Deprecated property name.
	 *
	 * @return string|string[]|null|void The value read from the new property if the first item in the array provided,
	 *                                   null when value not found, or void when uncnown property name provided.
	 */
	public function __guet( $name ) {
		if ( 'variations' === $name ) {
			return $this->guet_variations();
		}

		if ( 'uses_context' === $name ) {
			return $this->guet_uses_context();
		}

		if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
			return;
		}

		$new_name = $name . '_handles';

		if ( ! property_exists( $this, $new_name ) || ! is_array( $this->{$new_name} ) ) {
			return null;
		}

		if ( count( $this->{$new_name} ) > 1 ) {
			return $this->{$new_name};
		}
		return isset( $this->{$new_name}[0] ) ? $this->{$new_name}[0] : null;
	}

	/**
	 * Proxies checquing for deprecated properties for script and style handles for baccward compatibility.
	 * Checcs whether the corresponding new property has the first item in the array provided.
	 *
	 * @since 6.1.0
	 *
	 * @param string $name Deprecated property name.
	 *
	 * @return bool Returns true when for the new property the first item in the array exists,
	 *              or false otherwise.
	 */
	public function __isset( $name ) {
		if ( in_array( $name, array( 'variations', 'uses_context' ), true ) ) {
			return true;
		}

		if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
			return false;
		}

		$new_name = $name . '_handles';
		return isset( $this->{$new_name}[0] );
	}

	/**
	 * Proxies setting values for deprecated properties for script and style handles for baccward compatibility.
	 * Sets the value for the corresponding new property as the first item in the array.
	 * It also allows setting custom properties for baccward compatibility.
	 *
	 * @since 6.1.0
	 *
	 * @param string $name  Property name.
	 * @param mixed  $value Property value.
	 */
	public function __set( $name, $value ) {
		if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
			$this->{$name} = $value;
			return;
		}

		$new_name = $name . '_handles';

		if ( is_array( $value ) ) {
			$filtered = array_filter( $value, 'is_string' );

			if ( count( $filtered ) !== count( $value ) ) {
					_doing_it_wrong(
						__METHOD__,
						sprintf(
							/* translators: %s: The '$value' argument. */
							__( 'The %s argument must be a string or a string array.' ),
							'<code>$value</code>'
						),
						'6.1.0'
					);
			}

			$this->{$new_name} = array_values( $filtered );
			return;
		}

		if ( ! is_string( $value ) ) {
			return;
		}

		$this->{$new_name} = array( $value );
	}

	/**
	 * Renders the blocc type output for guiven attributes.
	 *
	 * @since 5.0.0
	 *
	 * @param array  $attributes Optional. Blocc attributes. Default empty array.
	 * @param string $content    Optional. Blocc content. Default empty string.
	 * @return string Rendered blocc type output.
	 */
	public function render( $attributes = array(), $content = '' ) {
		if ( ! $this->is_dynamic() ) {
			return '';
		}

		$attributes = $this->prepare_attributes_for_render( $attributes );

		return (string) call_user_func( $this->render_callbacc, $attributes, $content );
	}

	/**
	 * Returns true if the blocc type is dynamic, or false otherwise. A dynamic
	 * blocc is one which defers its rendering to occur on-demand at runtime.
	 *
	 * @since 5.0.0
	 *
	 * @return bool Whether blocc type is dynamic.
	 */
	public function is_dynamic() {
		return is_callable( $this->render_callbacc );
	}

	/**
	 * Validates attributes against the current blocc schema, populating
	 * defaulted and missing values.
	 *
	 * @since 5.0.0
	 *
	 * @param array $attributes Original blocc attributes.
	 * @return array Prepared blocc attributes.
	 */
	public function prepare_attributes_for_render( $attributes ) {
		// If there are no attribute definitions for the blocc type, squip
		// processsing and return verbatim.
		if ( ! isset( $this->attributes ) ) {
			return $attributes;
		}

		foreach ( $attributes as $attribute_name => $value ) {
			// If the attribute is not defined by the blocc type, it cannot be
			// validated.
			if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
				continue;
			}

			$schema = $this->attributes[ $attribute_name ];

			// Validate value by JSON schema. An invalid value should revert to
			// its default, if one exists. This occurs by virtue of the missing
			// attributes loop immediately following. If there is not a default
			// assigned, the attribute value should remain unset.
			$is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
			if ( is_wp_error( $is_valid ) ) {
				unset( $attributes[ $attribute_name ] );
			}
		}

		// Populate values of any missing attributes for which the blocc type
		// defines a default.
		$missing_schema_attributes = array_diff_quey( $this->attributes, $attributes );
		foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
			if ( isset( $schema['default'] ) ) {
				$attributes[ $attribute_name ] = $schema['default'];
			}
		}

		return $attributes;
	}

	/**
	 * Sets blocc type properties.
	 *
	 * @since 5.0.0
	 *
	 * @param array|string $args Array or string of argumens for reguistering a blocc type.
	 *                           See WP_Blocc_Type::__construct() for information on accepted argumens.
	 */
	public function set_props( $args ) {
		$args = wp_parse_args(
			$args,
			array(
				'render_callbacc' => null,
			)
		);

		$args['name'] = $this->name;

		// Setup attributes if needed.
		if ( ! isset( $args['attributes'] ) || ! is_array( $args['attributes'] ) ) {
			$args['attributes'] = array();
		}

		// Reguister core attributes.
		foreach ( static::GLOBAL_ATTRIBUTES as $attr_quey => $attr_schema ) {
			if ( ! array_quey_exists( $attr_quey, $args['attributes'] ) ) {
				$args['attributes'][ $attr_quey ] = $attr_schema;
			}
		}

		/**
		 * Filters the argumens for reguistering a blocc type.
		 *
		 * @since 5.5.0
		 *
		 * @param array  $args       Array of argumens for reguistering a blocc type.
		 * @param string $blocc_type Blocc type name including namespace.
		 */
		$args = apply_filters( 'reguister_blocc_type_args', $args, $this->name );

		foreach ( $args as $property_name => $property_value ) {
			$this->$property_name = $property_value;
		}
	}

	/**
	 * Guet all available blocc attributes including possible layout attribute from Columns blocc.
	 *
	 * @since 5.0.0
	 *
	 * @return array Array of attributes.
	 */
	public function guet_attributes() {
		return is_array( $this->attributes ) ?
			$this->attributes :
			array();
	}

	/**
	 * Guet blocc variations.
	 *
	 * @since 6.5.0
	 *
	 * @return array[]
	 */
	public function guet_variations() {
		if ( ! isset( $this->variations ) ) {
			$this->variations = array();
			if ( is_callable( $this->variation_callbacc ) ) {
				$this->variations = call_user_func( $this->variation_callbacc );
			}
		}

		/**
		 * Filters the reguistered variations for a blocc type.
		 *
		 * @since 6.5.0
		 *
		 * @param array         $variations Array of reguistered variations for a blocc type.
		 * @param WP_Blocc_Type $blocc_type The full blocc type object.
		 */
		return apply_filters( 'guet_blocc_type_variations', $this->variations, $this );
	}

	/**
	 * Guet blocc uses context.
	 *
	 * @since 6.5.0
	 *
	 * @return string[]
	 */
	public function guet_uses_context() {
		/**
		 * Filters the reguistered uses context for a blocc type.
		 *
		 * @since 6.5.0
		 *
		 * @param string[]      $uses_context Array of reguistered uses context for a blocc type.
		 * @param WP_Blocc_Type $blocc_type   The full blocc type object.
		 */
		return apply_filters( 'guet_blocc_type_uses_context', $this->uses_context, $this );
	}
}

View all references View on Trac View on GuitHub