Add plugin template registration API #7125

Aljullu · 2024-08-01T14:13:45Z

This PR includes the changes that need to be backported from WordPress/gutenberg#61577 and WordPress/gutenberg#64610 into WC core.

Trac ticket: https://core.trac.wordpress.org/ticket/61804

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2024-08-01T14:18:57Z

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 props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props aljullu, peterwilsoncc, antonvlasenko, azaozz, youknowriad, noisysocks.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Aljullu · 2024-08-01T15:00:25Z

@youknowriad I've tested the PHP APIs in this PR and they are working as expected. Unfortunately, I didn't find a way to reproduce all the testing steps from WordPress/gutenberg#61577. This PR doesn't include the JS changes from the original PR so template revert/removal doesn't work. Is it expected that this kind of PRs can't be tested right away, or am I missing something?

youknowriad · 2024-08-05T16:32:14Z

@Aljullu yes, that's fine, it means this PR can only be merged after the package update on Core.

github-actions · 2024-08-09T11:09:24Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

…plugin-registered title and description

peterwilsoncc

Added a few notes for the wp-dev version.

src/wp-includes/block-template-utils.php

src/wp-includes/block-template.php

src/wp-includes/class-wp-block-templates-registry.php

Meant to comment, not approve.

Co-authored-by: Peter Wilson <[email protected]>

Aljullu · 2024-08-28T15:07:03Z

Thanks for the review @peterwilsoncc! I have applied all your feedback.

anton-vlasenko

I haven't had a chance to do a thorough review, but this caught my attention.
Thank you for considering my notes.

src/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

src/wp-includes/class-wp-block-templates-registry.php

azaozz · 2024-08-30T23:41:32Z

src/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

+					foreach ( $plugins as $plugin_file ) {
+						$plugin_basename = plugin_basename( $plugin_file );
+						// Split basename by '/' to get the plugin slug.
+						list( $plugin_slug, ) = explode( '/', $plugin_basename );
+
+						if ( $plugin_slug === $template_object->plugin ) {
+							$plugin_data = get_plugin_data( $plugin_file );
+
+							if ( ! empty( $plugin_data['Name'] ) ) {
+								return $plugin_data['Name'];
+							}
+
+							break;
+						}
+					}


This seems somewhat slow, mostly the get_plugin_data(). May be missing something but seems this is supposed to run on every page load for all templates that have a "plugin" in the settings. If that's the case, perhaps some caching would be nice here?

Or even better, is the readable plugin author name always necessary? Would it make sense to retrieve it only when it's needed, otherwise just return whatever is in $template_object->plugin?

I agree with Ozz that it would be good to avoid the performance impact here, the function is in the admin folder section because it's very slow.

Thanks for the comments!

Or even better, is the readable plugin author name always necessary? Would it make sense to retrieve it only when it's needed, otherwise just return whatever is in $template_object->plugin?

This code runs only when querying the templates endpoint. That means the code does not run on the frontend or on most wp-admin pages. It runs in the Site Editor, where the template author text is displayed in several UI elements, so I'm not sure how it can be optimized in that sense.

When making a call to the templates endpoint, this specific code path can be deactivated if the author_text attribute is not requested. That could be done in some specific cases, like when loading templates for the Swap template popup in the Post Editor, as AFAIK we don't display the author text anywhere in the UI, but I might be wrong. 🤔

If that's the case, perhaps some caching would be nice here?

I agree that caching could help. Since this is my first PR of this size in WP core, I'd appreciate any specific recommendations on implementing caching in this context. My initial thought is to store a transient that maps plugin slugs to plugin names, which would be invalidated whenever a plugin is activated, deactivated, or updated. But wondering if you have any better suggestions. 🙂

My initial thought is to store a transient that maps plugin slugs to plugin names, which would be invalidated whenever a plugin is activated, deactivated, or updated.

The various hooks for when a plugin is updated only run if the plugin is updated via the Dashboard. In the case of sites deployed by git, rsync or good old FTP this isn't the case which makes caching these functions persistently via a transient or the object cache unworkable.

This code runs only when querying the templates endpoint. That means the code does not run on the frontend

Thanks for the clarification. As peterwilsoncc pointed out above when plugins are updated by FTP (uploading) or from version control, WP doesn't know it unless an admin visits the Plugins screen. This makes caching of the plugins meta somewhat impractical as that cache will always be stale in some cases/on some sites.

On the other hand mapping the plugin's name to the plugin's slug may be acceptable even if a bit stale. It is very rare that a plugin is renamed, so probably can use a transient that expires every week or so? That may be an acceptable compromise as this information doesn't seem critical.

peterwilsoncc · 2024-09-01T22:07:36Z

src/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

+					foreach ( $plugins as $plugin_file ) {
+						$plugin_basename = plugin_basename( $plugin_file );
+						// Split basename by '/' to get the plugin slug.
+						list( $plugin_slug, ) = explode( '/', $plugin_basename );
+
+						if ( $plugin_slug === $template_object->plugin ) {
+							$plugin_data = get_plugin_data( $plugin_file );
+
+							if ( ! empty( $plugin_data['Name'] ) ) {
+								return $plugin_data['Name'];
+							}
+
+							break;
+						}
+					}


I agree with Ozz that it would be good to avoid the performance impact here, the function is in the admin folder section because it's very slow.

peterwilsoncc · 2024-09-01T22:17:51Z

src/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

+				 * Fall back to the theme name if the plugin is not defined. That's needed to keep backwards
+				 * compatibility with templates that were registered before the plugin attribute was added.
+				 */
+				$plugins         = get_plugins();


As above with get_plugins(), it gets a file listing of wp-content/plugins/*, filters for PHP files and opens each of them to look for a plugin header. In the case of Jetpack, this is 38 files.

get_plugins() is cached but the plugins group isn't persistent so the code runs on each http request calling the function.

In cases where a plugin is using the API and setting the namespace to match its slug, we will have already returned in this function, so this code would never run.

The main reason to keep it is for backwards compatibility, as this code already exists in WP 6.6 and some plugins rely on it: they don't use the new template registration API but they still set the template source to plugin.

…troller.php Co-authored-by: Anton Vlasenko <[email protected]>

noisysocks · 2024-09-09T04:23:51Z

Although this needs a little work before landing in the final release, I am a little tempted to merge the code in it's current form while performance is figured out so we can merge in the inital package update. What do you think @azaozz @noisysocks?

If there's no outstanding blocking comments I'm ok with this.

anton-vlasenko · 2024-09-09T09:19:21Z

Although this needs a little work before landing in the final release, I am a little tempted to merge the code in it's current form while performance is figured out so we can merge in the inital package update. What do you think @azaozz @noisysocks?

If there's no outstanding blocking comments I'm ok with this.

@noisysocks Speaking of blocking comments, the code currently has some compatibility issues with PHP 8.2, as it introduces a dynamic class property (WP_Block_Template::$plugin).
I also have concerns regarding #7125 (comment) (might not work as expected).
In my opinion, this PR may not be ready to be merged in its current state.

Co-authored-by: Anton Vlasenko <[email protected]>

Aljullu · 2024-09-09T10:37:11Z

Thanks for the review @anton-vlasenko! I have addressed all your feedback, I would appreciate it if you can take another look.

There is also this open discussion about finding a more performant way to retrieve the plugin author text, but I might need some assistance on how to proceed. Also I don't know if it's a blocker.

azaozz · 2024-09-09T23:36:43Z

Although this needs a little work before landing in the final release, I am a little tempted to merge the code in it's current form while performance is figured out

Sounds good to me too after all of @anton-vlasenko's suggestions and fixes were added. Would be nice to address/fix the performance improvements from above but as that affect only the site editor don't think it is a blocker.

peterwilsoncc · 2024-09-10T01:34:40Z

I've merged trunk in and renamed a class in the tests folder (ie, it won't effect your source code). If @anton-vlasenko is happy with the change a few hours ago then I think it's good to go.

anton-vlasenko

@Aljullu Please find another review below. Apologies for not including it with the previous one, as I just noticed it.

src/wp-includes/block-template-utils.php

tests/phpunit/tests/block-templates/WpBlockTemplatesRegistry.php

Co-authored-by: Anton Vlasenko <[email protected]>

anton-vlasenko · 2024-09-10T16:07:44Z

I've merged trunk in and renamed a class in the tests folder (ie, it won't effect your source code). If @anton-vlasenko is happy with the change a few hours ago then I think it's good to go.

@peterwilsoncc I don't see any blockers at the moment. Thanks!

peterwilsoncc · 2024-09-14T00:51:12Z

I've merged in trunk and pushed a couple of test nitpicks in e8b2b2c and some docs standards fixes in 9a18a25

peterwilsoncc · 2024-09-15T23:26:54Z

I think this is good to go in, @noisysocks are you able to take a look to make sure I am not missing something obvious that will effect the editor?

noisysocks · 2024-09-18T05:27:18Z

Looks OK to me. We'll have to wait until packages are synced before we commit.

noisysocks · 2024-09-20T02:06:26Z

Committed in r59073.

Aljullu added 2 commits August 1, 2024 15:21

Add plugin template registration API

fb5b81b

Rename 'templates' to 'block templates' in several APIs

356f341

Simplify get_block_file_template() logic

1cf666a

Aljullu force-pushed the add/plugin-template-registration-api branch from 56b304f to 1cf666a Compare August 1, 2024 14:19

Aljullu mentioned this pull request Aug 2, 2024

Add plugin template registration API WordPress/gutenberg#61577

Merged

Aljullu added 6 commits August 9, 2024 12:16

Change default author text from theme slug to the plugin slug

aa4ede2

Remove unnecessary usage of empty

5b8af2f

DRY when validating registry input

fe33355

Fix typo in error message

57bfe8e

Fix typo in variable name

01d62d7

Fix wrong register method signature

48351b4

github-actions bot mentioned this pull request Aug 13, 2024

PHP backports for WP 6.7 WordPress/gutenberg#63827

Open

Make plugin-registered templates overriden by themes to fall back to …

b9962d7

…plugin-registered title and description

peterwilsoncc mentioned this pull request Aug 24, 2024

Update packages for 6.7 Beta 1 (1/3) #7226

Closed

6 tasks

peterwilsoncc previously approved these changes Aug 27, 2024

View reviewed changes

Aljullu and others added 5 commits August 28, 2024 16:59

Remove 'gutenberg' domain from translation strings

cf747f8

Make variable as optional and clarify it's the plugin slug

b1f9ec2

Add since tags to new functions

8188a0f

Clarify registering functions refer to block templates

b3e73e0

Update src/wp-includes/block-template-utils.php

d843c49

Co-authored-by: Peter Wilson <[email protected]>

anton-vlasenko reviewed Aug 30, 2024

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php Outdated Show resolved Hide resolved

src/wp-includes/class-wp-block-templates-registry.php Outdated Show resolved Hide resolved

azaozz reviewed Aug 30, 2024

View reviewed changes

peterwilsoncc reviewed Sep 1, 2024

View reviewed changes

Update src/wp-includes/rest-api/endpoints/class-wp-rest-templates-con…

b6b0311

…troller.php Co-authored-by: Anton Vlasenko <[email protected]>

Aljullu and others added 8 commits September 9, 2024 12:07

Add property to WP_Template object

e96f28d

Fix wrong return type in register function

32bb1e2

Update src/wp-includes/block-template-utils.php

56222e4

Co-authored-by: Anton Vlasenko <[email protected]>

Update src/wp-includes/class-wp-block-templates-registry.php

ae88141

Co-authored-by: Anton Vlasenko <[email protected]>

Update src/wp-includes/class-wp-block-templates-registry.php

06443ea

Co-authored-by: Anton Vlasenko <[email protected]>

Remove duplicate args param

feaf88d

Fix wrong return type in unregister function

0252d6f

Remove unnecessary reassignment of ->origin

e9d8580

peterwilsoncc added 2 commits September 10, 2024 11:17

Merge branch 'trunk' into add/plugin-template-registration-api

5c8c19b

Rename test class.

cb65273

anton-vlasenko reviewed Sep 10, 2024

View reviewed changes

src/wp-includes/block-template-utils.php Outdated Show resolved Hide resolved

tests/phpunit/tests/block-templates/WpBlockTemplatesRegistry.php Outdated Show resolved Hide resolved

Aljullu and others added 3 commits September 10, 2024 11:16

Fix wrong object to get the slug from

6a6394d

Update tests/phpunit/tests/block-templates/WpBlockTemplatesRegistry.php

7d42b33

Co-authored-by: Anton Vlasenko <[email protected]>

Fix wrong docblock comments

18dcff4

Aljullu mentioned this pull request Sep 10, 2024

Fix some docblock types related to the Template Registration API WordPress/gutenberg#65187

Merged

Fix another wrong docblock comment

09d39d2

peterwilsoncc added 3 commits September 14, 2024 09:54

A few test nitpicks.

e8b2b2c

Merge branch 'trunk' into add/plugin-template-registration-api

bd7fc60

Doc standards fixes.

9a18a25

noisysocks closed this Sep 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add plugin template registration API #7125

Add plugin template registration API #7125

Aljullu commented Aug 1, 2024 •

edited

Loading

github-actions bot commented Aug 1, 2024 •

edited

Loading

Aljullu commented Aug 1, 2024

youknowriad commented Aug 5, 2024

github-actions bot commented Aug 9, 2024

peterwilsoncc left a comment

Aljullu commented Aug 28, 2024

anton-vlasenko left a comment •

edited

Loading

azaozz Aug 30, 2024

peterwilsoncc Sep 1, 2024

Aljullu Sep 2, 2024

peterwilsoncc Sep 2, 2024

azaozz Sep 10, 2024 •

edited

Loading

peterwilsoncc Sep 1, 2024

peterwilsoncc Sep 1, 2024

Aljullu Sep 2, 2024

noisysocks commented Sep 9, 2024

anton-vlasenko commented Sep 9, 2024 •

edited

Loading

Aljullu commented Sep 9, 2024

azaozz commented Sep 9, 2024

peterwilsoncc commented Sep 10, 2024

anton-vlasenko left a comment •

edited

Loading

anton-vlasenko commented Sep 10, 2024

peterwilsoncc commented Sep 14, 2024

peterwilsoncc commented Sep 15, 2024

noisysocks commented Sep 18, 2024

noisysocks commented Sep 20, 2024 •

edited

Loading

Add plugin template registration API #7125

Add plugin template registration API #7125

Conversation

Aljullu commented Aug 1, 2024 • edited Loading

github-actions bot commented Aug 1, 2024 • edited Loading

Aljullu commented Aug 1, 2024

youknowriad commented Aug 5, 2024

github-actions bot commented Aug 9, 2024

Test using WordPress Playground

Some things to be aware of

peterwilsoncc left a comment

Choose a reason for hiding this comment

Aljullu commented Aug 28, 2024

anton-vlasenko left a comment • edited Loading

Choose a reason for hiding this comment

azaozz Aug 30, 2024

Choose a reason for hiding this comment

peterwilsoncc Sep 1, 2024

Choose a reason for hiding this comment

Aljullu Sep 2, 2024

Choose a reason for hiding this comment

peterwilsoncc Sep 2, 2024

Choose a reason for hiding this comment

azaozz Sep 10, 2024 • edited Loading

Choose a reason for hiding this comment

peterwilsoncc Sep 1, 2024

Choose a reason for hiding this comment

peterwilsoncc Sep 1, 2024

Choose a reason for hiding this comment

Aljullu Sep 2, 2024

Choose a reason for hiding this comment

noisysocks commented Sep 9, 2024

anton-vlasenko commented Sep 9, 2024 • edited Loading

Aljullu commented Sep 9, 2024

azaozz commented Sep 9, 2024

peterwilsoncc commented Sep 10, 2024

anton-vlasenko left a comment • edited Loading

Choose a reason for hiding this comment

anton-vlasenko commented Sep 10, 2024

peterwilsoncc commented Sep 14, 2024

peterwilsoncc commented Sep 15, 2024

noisysocks commented Sep 18, 2024

noisysocks commented Sep 20, 2024 • edited Loading

Aljullu commented Aug 1, 2024 •

edited

Loading

github-actions bot commented Aug 1, 2024 •

edited

Loading

anton-vlasenko left a comment •

edited

Loading

azaozz Sep 10, 2024 •

edited

Loading

anton-vlasenko commented Sep 9, 2024 •

edited

Loading

anton-vlasenko left a comment •

edited

Loading

noisysocks commented Sep 20, 2024 •

edited

Loading