Stabilize PHP-Only Block Registration#75543
Merged
Merged
Conversation
github-actions
Bot
added
[Package] Block library
t-hamano
commented
Feb 14, 2026
| $auto_register_blocks = array(); | ||
| $registered_blocks = WP_Block_Type_Registry::get_instance()->get_all_registered(); | ||
|
|
||
| foreach ( $registered_blocks as $block_name => $block_type ) { | ||
| $has_auto_register_flag = ! empty( $block_type->auto_register ) || ! empty( $block_type->supports['auto_register'] ); | ||
| $has_auto_register_flag = ! empty( $block_type->supports['auto_register'] ); |
Contributor
Author
There was a problem hiding this comment.
The current implementation does not check for the top-level auto_register field. Checking supports.auto_register seems sufficient.
|
Size Change: +5 B (0%) Total Size: 6.85 MB
ℹ️ View Unchanged
|
t-hamano
force-pushed
the
stabilize-php-only-blocks
branch
from
695193a to
26ea3a5
Compare
t-hamano
added
[Type] Enhancement
t-hamano
force-pushed
the
stabilize-php-only-blocks
branch
from
332d0fa to
5868968
Compare
t-hamano
changed the title
t-hamano
requested review from
adamziel,
ajitbohra,
draganescu,
fabiankaegy,
kevin940726,
spacedmonkey and
tellthemachines
as code owners
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
3 tasks
t-hamano
moved this from 🏗️ In Progress
to 🔎 Needs Review
in WordPress 7.0 Editor Tasks
|
Flaky tests detected in 5868968. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22018787029
|
Member
|
Hi @t-hamano I think maybe it's this: Context: #75137 (comment) |
Contributor
|
It's installed by default in the wp-env-test environment, so easiest thing would be to start that ( |
Contributor
Author
|
Thanks for letting me know. I tested it again using the code below and that plugin. Detailsfunction gutenberg_register_php_only_blocks() {
register_block_type(
'my-plugin/example',
array(
'title' => 'My Example Block',
'attributes' => array(
'title' => array(
'type' => 'string',
'default' => 'Hello World',
),
'count' => array(
'type' => 'integer',
'default' => 10,
),
'enabled' => array(
'type' => 'boolean',
'default' => false,
),
'size' => array(
'type' => 'string',
'enum' => array( 'small', 'medium', 'large' ),
'default' => 'medium',
),
),
'render_callback' => function ( $attributes ) {
return sprintf(
'<div %1$s>
<p>Title: %2$s</p>
<p>Count: %3$d</p>
<p>Enabled: %4$s</p>
<p>Size: %5$s</p>
</div>',
get_block_wrapper_attributes(),
esc_html( $attributes['title'] ),
$attributes['count'],
$attributes['enabled'] ? 'true' : 'false',
esc_html( $attributes['size'] )
);
},
'supports' => array(
'autoRegister' => true,
),
)
);
}
add_action( 'init', 'gutenberg_register_php_only_blocks' );
function gutenberg_add_binding_support_to_php_block() {
return array( 'title', 'count', 'enabled', 'size' );
}
add_filter( 'block_bindings_supported_attributes_my-plugin/example', 'gutenberg_add_binding_support_to_php_block' );
It certainly doesn't work with some fields, and I get errors in the response due to server-side rendering. I'm wondering where I should disable binding support for PHP-Only Blocks. For example, would it look like this? function gutenberg_get_block_bindings_supported_attributes( $block_type ) {
// ...
// For now, exclude attributes with `autoGenerateControl` flag from blocks with `autoRegister` support.
// These attributes are currently meant to be edited via auto-generated inspector controls, not via
// block bindings.
$block_type_registry = WP_Block_Type_Registry::get_instance();
$block_type_object = $block_type_registry->get_registered( $block_type );
if ( $block_type_object && ! empty( $block_type_object->supports['autoRegister'] ) ) {
$supported_block_attributes = array_filter(
$supported_block_attributes,
function ( $attribute_name ) use ( $block_type_object ) {
$attribute_schema = $block_type_object->attributes[ $attribute_name ] ?? null;
return ! ( isset( $attribute_schema['autoGenerateControl'] ) && $attribute_schema['autoGenerateControl'] );
}
);
$supported_block_attributes = array_values( $supported_block_attributes );
}
return $supported_block_attributes;
} |
Contributor
Sounds reasonable, but why not go further? Why not disable it entirely for block types with |
Contributor
Author
The hook that marks This means that if another plugin adds attributes via the This may be an edge case, but attributes added in that way do not auto-generate the control, so the block binding API should be available. |
Contributor
Right, I can understand how other attributes would end up there, but I'm wanting to understand what actual use cases this may correspond to, and whether bindings should be supported there. Maybe yes, so let's try that approach. |
Contributor
|
Apologies, I haven't gotten around to looking into this yet. I'll hopefully get a chance some time this week, once the 22.6 release is on track. |
Contributor
|
Proposed dev note below. Question: Which props are due? I started small and only credited Héctor, but obviously many more people were involved in various degrees (Aki, me, and many reviewers). PHP-only block registrationDevelopers can now create simple blocks using only PHP. This is meant for blocks that only need server-side rendering and aren’t meant to be highly interactive. To do so, call function gutenberg_register_php_only_blocks() {
register_block_type(
'my-plugin/example',
array(
'title' => 'My Example Block',
'attributes' => array(
'title' => array(
'type' => 'string',
'default' => 'Hello World',
),
'count' => array(
'type' => 'integer',
'default' => 5,
),
'enabled' => array(
'type' => 'boolean',
'default' => true,
),
'size' => array(
'type' => 'string',
'enum' => array( 'small', 'medium', 'large' ),
'default' => 'medium',
),
),
'render_callback' => function ( $attributes ) {
return sprintf(
'<div>%s: %d items (%s)</div>',
esc_html( $attributes['title'] ),
$attributes['count'],
$attributes['size']
);
},
'supports' => array(
'autoRegister' => true,
),
)
);
}
add_action( 'init', 'gutenberg_register_php_only_blocks' );These blocks will automatically appear in the editor without requiring any JavaScript registration, and, wherever possible, the editor will automatically generate controls in the Inspector Controls sidebar to allow users to edit block attributes: 
See https://core.trac.wordpress.org/ticket/64639 for more details. Props to @priethor for the implementation. |
Contributor
Author
|
@mcsf Thanks for writing a dev note! I think it's worth mentioning the following:
I think the props listed in the Dev Notes are generally not those who worked on the feature, but rather those who reviewed the Dev Notes. For example: |
Contributor
|
Thanks for the review, @t-hamano!
I did mention that, but I can reword it slightly for emphasis.
You're right. I only hinted at it ("wherever possible") but didn't expand.
Hm, right. I saw a block-binding dev note assignning implementation props and thought of doing the same. Actually, in this case, since @priethor was the main implementor and is currently on leave and unable to contribute, I'd still like to name him (he'd be the one writing the dev note if he were around). Is that ok? With all the feedback, see my revised draft: PHP-only block registrationDevelopers can now create simple blocks using only PHP. This is meant for blocks that only need server-side rendering and aren’t meant to be highly interactive. To do so, call function gutenberg_register_php_only_blocks() {
register_block_type(
'my-plugin/example',
array(
'title' => 'My Example Block',
'attributes' => array(
'title' => array(
'type' => 'string',
'default' => 'Hello World',
),
'count' => array(
'type' => 'integer',
'default' => 5,
),
'enabled' => array(
'type' => 'boolean',
'default' => true,
),
'size' => array(
'type' => 'string',
'enum' => array( 'small', 'medium', 'large' ),
'default' => 'medium',
),
),
'render_callback' => function ( $attributes ) {
return sprintf(
'<div>%s: %d items (%s)</div>',
esc_html( $attributes['title'] ),
$attributes['count'],
$attributes['size']
);
},
'supports' => array(
'autoRegister' => true,
),
)
);
}
add_action( 'init', 'gutenberg_register_php_only_blocks' );These blocks will automatically appear in the editor without requiring any JavaScript registration, and, wherever possible, the editor will automatically generate controls in the Inspector Controls sidebar to allow users to edit block attributes:
Note that controls will not be generated for attributes with the See https://core.trac.wordpress.org/ticket/64639 for more details. Props to priethor for the implementation. [edit: removed @ from usernames to prevent pinging the wrong GH user] |
Contributor
Author
|
Looks great!
Of course I agree 👍 |
Contributor
|
Post ready for publishing at https://make.wordpress.org/core/?p=121777&preview=1&_ppp=526c010ebc |
mcsf
added
has dev note
Contributor
I finally managed to look into this. Here's a PR to have auto-generated attribute controls reflect bound attributes: #76040 I hope that this will allow us to keep Block Bindings enabled for this class of blocks 😊 |
Contributor
Author
The Dev Note looks ready to be published 👍 |
Contributor
|
One more PR to handle |
|
Not sure if this is a potential bug because it's so new and I might miss something - but I can't get php only blocks to render properly in the template previews. Their content will be rendered, but CSS that is applied either globally or per block and works in the site editor itself won't be used in the template previews (which makes them look broken). I don't have that issue with js-based blocks that use serversiderender. |
Contributor
Author
|
@ts-mz, could you report the issue in more detail in a new issue? |
Preparing to post the issue, I tried again with just a div in the block and a background in the css and suddenly it worked in both the js and php block (when including the same css file as block style). Not sure why it wouldn't work before, as this is exactly what I did before, but I still suspect it was something on my side and won't post an issue unless the problem resurfaces. |
|
Would it be possible to support the /blocks/{blockname}/block.json |
Contributor
Author
|
@Xilonz Sorry, I'm not sure I follow. Could you explain that in a little more detail? |
|
@t-hamano I realized we can already render using the We use I was just looking wrong since A minimal example for this block.json would be: {
"$schema": "https://schemas.wp.org/trunk/block.json",
"name": "me/block",
"title": "Example Block",
"supports": {
"autoRegister": true,
}
"style": "file:./block.css",
"render": "block.php"
}Maybe its useful to add this as note to the documentation in case others get confused too. |
Contributor
Author
|
@Xilonz, I might be misunderstanding something, but I think this feature is, as the name suggests, for registering blocks "using PHP only." It doesn't seem like defining the |
|
There are 2 ways to register blocks using only PHP: I do suspect (i have to try it) that I think the confusion came from the linked Make article; this PR is has a much narrower scope. |
Contributor
Author
My understanding is that |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #71792
What?
Stabilizes the PHP-only block registration feature.
How?
autoRegisterBlocksvia theblock_editor_settings_allhook.registerPHPOnlyBlocks()function. We might be able to mark this function as public from the start. The reason I created a dedicated function for the block registration logic is that we can't accesssettingsin theregisterCoreBlocks()function, so I was hesitant to add a new argument toregisterCoreBlocks().__experimentalAutoInspectorControltoautoGenerateControl. This is a marker that is only applied to attributes explicitly added by users and is used to generate controls.Note
Note also that this PR changes the support keys from snake_case to camelCase.
Testing Instructions
Use the following code to register a sample PHP-only block:
Make sure this block works across the post editor, site editor, widget editor, and customizer.