WordPress/wp-includes/class-wp-block-patterns-registry.php

323 lines
12 KiB
PHP
Raw Normal View History

<?php
/**
* Blocks API: WP_Block_Patterns_Registry class
*
* @package WordPress
* @subpackage Blocks
* @since 5.5.0
*/
/**
* Class used for interacting with block patterns.
*
* @since 5.5.0
*/
Code Modernization: Add `AllowDynamicProperties` attribute to all (parent) classes. Dynamic (non-explicitly declared) properties are deprecated as of PHP 8.2 and are expected to become a fatal error in PHP 9.0. There are a number of ways to mitigate this: * If it is an accidental typo for a declared property: fix the typo. * For known properties: declare them on the class. * For unknown properties: add the magic `__get()`, `__set()`, et al. methods to the class or let the class extend `stdClass` which has highly optimized versions of these magic methods built in. * For unknown ''use'' of dynamic properties, the `#[AllowDynamicProperties]` attribute can be added to the class. The attribute will automatically be inherited by child classes. Trac ticket #56034 is open to investigate and handle the third and fourth type of situations, however it has become clear this will need more time and will not be ready in time for WP 6.1. To reduce “noise” in the meantime, both in the error logs of WP users moving onto PHP 8.2, in the test run logs of WP itself, in test runs of plugins and themes, as well as to prevent duplicate tickets from being opened for the same issue, this commit adds the `#[AllowDynamicProperties]` attribute to all “parent” classes in WP. The logic used for this commit is as follows: * If a class already has the attribute: no action needed. * If a class does not `extend`: add the attribute. * If a class does `extend`: - If it extends `stdClass`: no action needed (as `stdClass` supports dynamic properties). - If it extends a PHP native class: add the attribute. - If it extends a class from one of WP's external dependencies: add the attribute. * In all other cases: no action — the attribute should not be needed as child classes inherit from the parent. Whether or not a class contains magic methods has not been taken into account, as a review of the currently existing magic methods has shown that those are generally not sturdy enough and often even set dynamic properties (which they should not). See the [https://www.youtube.com/watch?v=vDZWepDQQVE live stream from August 16, 2022] for more details. This commit only affects classes in the `src` directory of WordPress core. * Tests should not get this attribute, but should be fixed to not use dynamic properties instead. Patches for this are already being committed under ticket #56033. * While a number bundled themes (2014, 2019, 2020, 2021) contain classes, they are not a part of this commit and may be updated separately. Reference: [https://wiki.php.net/rfc/deprecate_dynamic_properties PHP RFC: Deprecate dynamic properties]. Follow-up to [53922]. Props jrf, hellofromTonya, markjaquith, peterwilsoncc, costdev, knutsp, aristath. See #56513, #56034. Built from https://develop.svn.wordpress.org/trunk@54133 git-svn-id: http://core.svn.wordpress.org/trunk@53692 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2022-09-12 17:47:14 +02:00
#[AllowDynamicProperties]
final class WP_Block_Patterns_Registry {
/**
* Registered block patterns array.
*
* @since 5.5.0
* @var array[]
*/
private $registered_patterns = array();
/**
* Patterns registered outside the `init` action.
*
* @since 6.0.0
* @var array[]
*/
private $registered_patterns_outside_init = array();
/**
* Container for the main instance of the class.
*
* @since 5.5.0
* @var WP_Block_Patterns_Registry|null
*/
private static $instance = null;
/**
* Registers a block pattern.
*
* @since 5.5.0
* @since 5.8.0 Added support for the `blockTypes` property.
* @since 6.1.0 Added support for the `postTypes` property.
* @since 6.2.0 Added support for the `templateTypes` property.
* @since 6.5.0 Added support for the `filePath` property.
*
* @param string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties {
* List of properties for the block pattern.
*
* @type string $title Required. A human-readable title for the pattern.
* @type string $content Optional. Block HTML markup for the pattern.
* If not provided, the content will be retrieved from the `filePath` if set.
* If both `content` and `filePath` are not set, the pattern will not be registered.
* @type string $description Optional. Visually hidden text used to describe the pattern
* in the inserter. A description is optional, but is strongly
* encouraged when the title does not fully describe what the
* pattern does. The description will help users discover the
* pattern while searching.
* @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled
* preview within the pattern inserter.
* @type bool $inserter Optional. Determines whether the pattern is visible in inserter.
* To hide a pattern so that it can only be inserted programmatically,
* set this to false. Default true.
* @type string[] $categories Optional. A list of registered pattern categories used to group
* block patterns. Block patterns can be shown on multiple categories.
* A category must be registered separately in order to be used here.
* @type string[] $keywords Optional. A list of aliases or keywords that help users discover
* the pattern while searching.
* @type string[] $blockTypes Optional. A list of block names including namespace that could use
* the block pattern in certain contexts (placeholder, transforms).
* The block pattern is available in the block editor inserter
* regardless of this list of block names.
* Certain blocks support further specificity besides the block name
* (e.g. for `core/template-part` you can specify areas
* like `core/template-part/header` or `core/template-part/footer`).
* @type string[] $postTypes Optional. An array of post types that the pattern is restricted
* to be used with. The pattern will only be available when editing one
* of the post types passed on the array. For all the other post types
* not part of the array the pattern is not available at all.
* @type string[] $templateTypes Optional. An array of template types where the pattern fits.
* @type string $filePath Optional. The full path to the file containing the block pattern content.
* }
* @return bool True if the pattern was registered with success and false otherwise.
*/
public function register( $pattern_name, $pattern_properties ) {
if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Pattern name must be a string.' ),
'5.5.0'
);
return false;
}
if ( ! isset( $pattern_properties['title'] ) || ! is_string( $pattern_properties['title'] ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Pattern title must be a string.' ),
'5.5.0'
);
return false;
}
if ( ! isset( $pattern_properties['filePath'] ) ) {
if ( ! isset( $pattern_properties['content'] ) || ! is_string( $pattern_properties['content'] ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Pattern content must be a string.' ),
'5.5.0'
);
return false;
}
}
$pattern = array_merge(
$pattern_properties,
array( 'name' => $pattern_name )
);
$this->registered_patterns[ $pattern_name ] = $pattern;
// If the pattern is registered inside an action other than `init`, store it
// also to a dedicated array. Used to detect deprecated registrations inside
// `admin_init` or `current_screen`.
if ( current_action() && 'init' !== current_action() ) {
$this->registered_patterns_outside_init[ $pattern_name ] = $pattern;
}
return true;
}
/**
* Unregisters a block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern was unregistered with success and false otherwise.
*/
public function unregister( $pattern_name ) {
if ( ! $this->is_registered( $pattern_name ) ) {
_doing_it_wrong(
__METHOD__,
/* translators: %s: Pattern name. */
sprintf( __( 'Pattern "%s" not found.' ), $pattern_name ),
'5.5.0'
);
return false;
}
unset( $this->registered_patterns[ $pattern_name ] );
unset( $this->registered_patterns_outside_init[ $pattern_name ] );
return true;
}
/**
* Prepares the content of a block pattern. If hooked blocks are registered, they get injected into the pattern,
* when they met the defined criteria.
*
* @since 6.4.0
*
* @param array $pattern Registered pattern properties.
* @param array $hooked_blocks The list of hooked blocks.
* @return string The content of the block pattern.
*/
private function prepare_content( $pattern, $hooked_blocks ) {
$content = $pattern['content'];
$before_block_visitor = '_inject_theme_attribute_in_template_part_block';
$after_block_visitor = null;
if ( ! empty( $hooked_blocks ) || has_filter( 'hooked_block_types' ) ) {
Block Hooks API: Insert metadata at the same time as hooked blocks. The Block Hooks UI relies on the `ignoredHookedBlocks` metadata when determining whether to show the toggle in the Site Editor. The problem is that for uncustomized templates we don't add this metadata. Currently the visitor functions have a default callback of `insert_hooked_blocks` and we only add the metadata when we're writing to the database via an available filter in the template controller. This changeset creates a new callback which both inserts the hooked blocks and adds the `ignoredHookedBlocks` metadata to the anchor block, and uses this new callback explicitly in the visitor functions that are run upon reading from the database. We continue to set the `ignoredHookedBlocks` metadata when writing to the database, i.e. this operation happens twice. Although not ideal, this is necessary to cover the following scenarios: * When the user adds an anchor block within the editor, we still need to add the `ignoredHookedBlocks` meta to it to prevent hooked blocks hooking on to it unexpectedly on the frontend. This is required to keep parity between the frontend and editor. * When a user writes template data to the database directly through the API (instead of the editor), we need to again ensure we're not inserting hooked blocks unexpectedly. It is worth noting that with this change, the first hooked block to insert relative to its anchor block will be accepted. Any additional blocks of the same type (e.g. a second `core/loginout` block) trying to hook onto the same anchor block will be ignored, irrespective of the position. Props tomjcafferkey, bernhard-reiter, gziolo. Fixes #59574. Built from https://develop.svn.wordpress.org/trunk@58186 git-svn-id: http://core.svn.wordpress.org/trunk@57649 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2024-05-23 20:35:14 +02:00
$before_block_visitor = make_before_block_visitor( $hooked_blocks, $pattern, 'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata' );
$after_block_visitor = make_after_block_visitor( $hooked_blocks, $pattern, 'insert_hooked_blocks_and_set_ignored_hooked_blocks_metadata' );
}
$blocks = parse_blocks( $content );
$content = traverse_and_serialize_blocks( $blocks, $before_block_visitor, $after_block_visitor );
return $content;
}
/**
* Retrieves the content of a registered block pattern.
*
* @since 6.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @param bool $outside_init_only Optional. Return only patterns registered outside the `init` action. Default false.
* @return string The content of the block pattern.
*/
private function get_content( $pattern_name, $outside_init_only = false ) {
if ( $outside_init_only ) {
$patterns = &$this->registered_patterns_outside_init;
} else {
$patterns = &$this->registered_patterns;
}
if ( ! isset( $patterns[ $pattern_name ]['content'] ) && isset( $patterns[ $pattern_name ]['filePath'] ) ) {
ob_start();
include $patterns[ $pattern_name ]['filePath'];
$patterns[ $pattern_name ]['content'] = ob_get_clean();
unset( $patterns[ $pattern_name ]['filePath'] );
}
return $patterns[ $pattern_name ]['content'];
}
/**
* Retrieves an array containing the properties of a registered block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @return array Registered pattern properties.
*/
public function get_registered( $pattern_name ) {
if ( ! $this->is_registered( $pattern_name ) ) {
return null;
}
$pattern = $this->registered_patterns[ $pattern_name ];
$pattern['content'] = $this->get_content( $pattern_name );
$pattern['content'] = $this->prepare_content( $pattern, get_hooked_blocks() );
Blocks: Implement automatic block insertion into Block Hooks. Block Hooks allow a third-party block to specify a position relative to a given block into which it will then be automatically inserted (e.g. a "Like" button block can ask to be inserted after the Post Content block, or an eCommerce shopping cart block can ask to be inserted after the Navigation block). The underlying idea is to provide an extensibility mechanism for Block Themes, in analogy to WordPress' [https://developer.wordpress.org/plugins/hooks/ Hooks] concept that has allowed extending Classic Themes through filters and actions. The two core tenets for Block Hooks are: 1. Insertion into the frontend should happen right after a plugin containing a hooked block is activated (i.e. the user isn't required to insert the block manually in the editor first); similarly, disabling the plugin should remove the hooked block from the frontend. 2. The user has the ultimate power to customize that automatic insertion: The hooked block is also visible in the editor, and the user's decision to persist, dismiss (i.e. remove), customize, or move it will be respected (and reflected on the frontend). To account for both tenets, the **tradeoff** was made to limit automatic block insertion to unmodified templates (and template parts, respectively). The reason for this is that the simplest way of storing the information whether a block has been persisted to (or dismissed from) a given template (or part) is right in the template markup. To accommodate for that tradeoff, [https://github.com/WordPress/gutenberg/pull/52969 UI controls (toggles)] are being added to increase visibility of hooked blocks, and to allow for their later insertion into templates (or parts) that already have been modified by the user. For hooked blocks to appear both in the frontend and in the editor (see tenet number 2), they need to be inserted into both the frontend markup and the REST API (templates and patterns endpoints) equally. As a consequence, this means that automatic insertion couldn't (only) be implemented at block ''render'' stage, as for the editor, the ''serialized'' (but ''unrendered'') markup needs to be modified. Furthermore, hooked blocks also have to be inserted into block patterns. Since practically no filters exist for the patterns registry, this has to be done in the registry's `get_registered` and `get_all_registered` methods. Props gziolo. Fixes #59313. Built from https://develop.svn.wordpress.org/trunk@56649 git-svn-id: http://core.svn.wordpress.org/trunk@56161 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2023-09-21 18:18:17 +02:00
return $pattern;
}
/**
* Retrieves all registered block patterns.
*
* @since 5.5.0
*
* @param bool $outside_init_only Return only patterns registered outside the `init` action.
* @return array[] Array of arrays containing the registered block patterns properties,
* and per style.
*/
public function get_all_registered( $outside_init_only = false ) {
$patterns = $outside_init_only
? $this->registered_patterns_outside_init
: $this->registered_patterns;
$hooked_blocks = get_hooked_blocks();
Blocks: Implement automatic block insertion into Block Hooks. Block Hooks allow a third-party block to specify a position relative to a given block into which it will then be automatically inserted (e.g. a "Like" button block can ask to be inserted after the Post Content block, or an eCommerce shopping cart block can ask to be inserted after the Navigation block). The underlying idea is to provide an extensibility mechanism for Block Themes, in analogy to WordPress' [https://developer.wordpress.org/plugins/hooks/ Hooks] concept that has allowed extending Classic Themes through filters and actions. The two core tenets for Block Hooks are: 1. Insertion into the frontend should happen right after a plugin containing a hooked block is activated (i.e. the user isn't required to insert the block manually in the editor first); similarly, disabling the plugin should remove the hooked block from the frontend. 2. The user has the ultimate power to customize that automatic insertion: The hooked block is also visible in the editor, and the user's decision to persist, dismiss (i.e. remove), customize, or move it will be respected (and reflected on the frontend). To account for both tenets, the **tradeoff** was made to limit automatic block insertion to unmodified templates (and template parts, respectively). The reason for this is that the simplest way of storing the information whether a block has been persisted to (or dismissed from) a given template (or part) is right in the template markup. To accommodate for that tradeoff, [https://github.com/WordPress/gutenberg/pull/52969 UI controls (toggles)] are being added to increase visibility of hooked blocks, and to allow for their later insertion into templates (or parts) that already have been modified by the user. For hooked blocks to appear both in the frontend and in the editor (see tenet number 2), they need to be inserted into both the frontend markup and the REST API (templates and patterns endpoints) equally. As a consequence, this means that automatic insertion couldn't (only) be implemented at block ''render'' stage, as for the editor, the ''serialized'' (but ''unrendered'') markup needs to be modified. Furthermore, hooked blocks also have to be inserted into block patterns. Since practically no filters exist for the patterns registry, this has to be done in the registry's `get_registered` and `get_all_registered` methods. Props gziolo. Fixes #59313. Built from https://develop.svn.wordpress.org/trunk@56649 git-svn-id: http://core.svn.wordpress.org/trunk@56161 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2023-09-21 18:18:17 +02:00
foreach ( $patterns as $index => $pattern ) {
$pattern['content'] = $this->get_content( $pattern['name'], $outside_init_only );
$patterns[ $index ]['content'] = $this->prepare_content( $pattern, $hooked_blocks );
Blocks: Implement automatic block insertion into Block Hooks. Block Hooks allow a third-party block to specify a position relative to a given block into which it will then be automatically inserted (e.g. a "Like" button block can ask to be inserted after the Post Content block, or an eCommerce shopping cart block can ask to be inserted after the Navigation block). The underlying idea is to provide an extensibility mechanism for Block Themes, in analogy to WordPress' [https://developer.wordpress.org/plugins/hooks/ Hooks] concept that has allowed extending Classic Themes through filters and actions. The two core tenets for Block Hooks are: 1. Insertion into the frontend should happen right after a plugin containing a hooked block is activated (i.e. the user isn't required to insert the block manually in the editor first); similarly, disabling the plugin should remove the hooked block from the frontend. 2. The user has the ultimate power to customize that automatic insertion: The hooked block is also visible in the editor, and the user's decision to persist, dismiss (i.e. remove), customize, or move it will be respected (and reflected on the frontend). To account for both tenets, the **tradeoff** was made to limit automatic block insertion to unmodified templates (and template parts, respectively). The reason for this is that the simplest way of storing the information whether a block has been persisted to (or dismissed from) a given template (or part) is right in the template markup. To accommodate for that tradeoff, [https://github.com/WordPress/gutenberg/pull/52969 UI controls (toggles)] are being added to increase visibility of hooked blocks, and to allow for their later insertion into templates (or parts) that already have been modified by the user. For hooked blocks to appear both in the frontend and in the editor (see tenet number 2), they need to be inserted into both the frontend markup and the REST API (templates and patterns endpoints) equally. As a consequence, this means that automatic insertion couldn't (only) be implemented at block ''render'' stage, as for the editor, the ''serialized'' (but ''unrendered'') markup needs to be modified. Furthermore, hooked blocks also have to be inserted into block patterns. Since practically no filters exist for the patterns registry, this has to be done in the registry's `get_registered` and `get_all_registered` methods. Props gziolo. Fixes #59313. Built from https://develop.svn.wordpress.org/trunk@56649 git-svn-id: http://core.svn.wordpress.org/trunk@56161 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2023-09-21 18:18:17 +02:00
}
return array_values( $patterns );
}
/**
* Checks if a block pattern is registered.
*
* @since 5.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern is registered, false otherwise.
*/
public function is_registered( $pattern_name ) {
return isset( $this->registered_patterns[ $pattern_name ] );
}
public function __wakeup() {
if ( ! $this->registered_patterns ) {
return;
}
if ( ! is_array( $this->registered_patterns ) ) {
throw new UnexpectedValueException();
}
foreach ( $this->registered_patterns as $value ) {
if ( ! is_array( $value ) ) {
throw new UnexpectedValueException();
}
}
$this->registered_patterns_outside_init = array();
}
/**
* Utility method to retrieve the main instance of the class.
*
* The instance will be created if it does not exist yet.
*
* @since 5.5.0
*
* @return WP_Block_Patterns_Registry The main instance.
*/
public static function get_instance() {
if ( null === self::$instance ) {
self::$instance = new self();
}
return self::$instance;
}
}
/**
* Registers a new block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties List of properties for the block pattern.
* See WP_Block_Patterns_Registry::register() for accepted arguments.
* @return bool True if the pattern was registered with success and false otherwise.
*/
function register_block_pattern( $pattern_name, $pattern_properties ) {
return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
}
/**
* Unregisters a block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern was unregistered with success and false otherwise.
*/
function unregister_block_pattern( $pattern_name ) {
return WP_Block_Patterns_Registry::get_instance()->unregister( $pattern_name );
}