Gutenberg: FSE: PHP Theme Template Compatibility Proposal

[tomjn]

In order to provide a migration path, I propose that top level PHP templates should appear in the templates screen alongside template posts and be replaceable:

These can then be replaced and converted by FSE templates, which would work the same way as any other template via a convert to template action. It may even be best to provide a button to create a new post to act as a replacement. In the above example, clicking on the action will create a new post with the slug home that would be loaded instead of home.php.

Alternative UI

It may be tidier to list PHP templates in a secondary view similar to this:

This would be similar to how mu-plugins and drop-ins are displayed in the plugin screen, and provide more flexibility for UI. Replaced templates can then have links to the template posts that replace them referenced, and buttons where there is none for conversion.

What Would Be The Official Migration Path?

The goal is to be able to replace PHP templates one at a time, avoiding a full site rebuild.

Theme Vendors

Theme sellers would add the block templates folder to their themes, and retire their existing PHP templates as this is done or where possible. Users can then create FSE templates to further customize and capitalise on theme features.

A seller could provide individual block based replacements with each update rather than needing to convert the entire theme at once.

Site Owners

Taking myself as an example, I can create draft templates for each PHP template, deleting the PHP files once I'm happy with the results. Eventually my sites theme would no longer contain top level PHP templates, meaning I could remove all PHP template partials

Questions

Would we do the same for loading PHP template parts?

No. We would let the plugin eco-system handle this. There are lots of opportunities, such as turning template parts into blocks, wrapping get_template_part in a block, or even adjusting filters to load PHP templates. We should let the ecosystem decide, or at least open a separate issue.

What about loading FSE templates from PHP?

This can already be done via WP_Query and get_posts with the existing plugin, there is no need for work to be done on that front. An enterprising developer may release a plugin that adds FSE template parts to get_template_part, but I don't believe this is within the scope of Gutenberg core.

What if the user changes their mind?

Then they can delete or unpublish the FSE post to return to the old way

Could a user prepare an FSE template in advance and still use PHP?

Yes, by clicking convert and saving as a draft instead of publishing. They could even use the scheduled posts system to make the new templates go live at midnight

What about block templates in the theme?

This will work the same as it does currently, when the user converts the template the new template post will be populated with the block template files from the theme if they're present.

What would the template hierarchy precedence be?

1. child theme FSE template
2. parent theme FSE template
3. child theme FSE block template files
4. parent theme FSE block template files
5. child theme PHP templates
6. parent theme PHP templates

It may be desirable to swap the precedence of PHP templates and block template files, but FSE template posts always take precedence.

The reason block template files take precedence over PHP templates, is to allow for migration to occur without forcing the user to create posts. This will be important for commercial themes and theme vendors.

What About index.php?

Only if no other templates exist

functions.php sidebar.php header.php and footer.php?

No, these are not top level templates, and would not appear for conversion or be listed

Plugin Top Level Templates

We would not list these out of the box, but instead provide a filter for extra PHP templates to be added, e.g. WooCommerce could add entries for the WooCommerce top level templates stored in their plugin folder via a filter.

What About When Browsing With FSE?

If you browsed on to a page that used a PHP file as a top level template, the page would not be editable, but you could browse to other editable pages.

However, you would be prompted in the editor to replace the PHP template, leading to a standard FSE experience. This way the experience of browsing with FSE is not interrupted, and a user can browse a site, converting and recreating PHP templates as they go.

[tomjn]

As an aside, I would take the same approach as a site owner for an agency or freelance developer where a new build is not an option

[annezazu]

Thanks so much for writing this up, @tomjn ❤️

[mtias]

Thanks for the issue! This is something discussed in the very original formulation of the wp_template structure but never made it into concrete issues.

It's super important there's an elegant way to make the two template engines coexist, allowing gradual migrations as needed. It's also sensible that some templates might be configurable and other highly dynamic ones might be left forever in their current format. In that sense, we should frame the block templates as something that can coexist with regular templates, the same way blocks coexisted with classic blocks. I was also thinking of WooCommerce as a good example where the abundance of template can require gradual or partial adoptions.

Probably worth keeping two areas of work here — one about coexistence and one about conversion. Converting current theme templates into block templates is something that would be very cool to see explorations from the wide ecosystem.

[tomjn]

Probably worth keeping two areas of work here — one about coexistence and one about conversion. Converting current theme templates into block templates is something that would be very cool to see explorations from the wide ecosystem.

Are you suggesting that the work of loading top level PHP templates where no FSE template exists be split into a new issue?

[mtias]

Yes, if we can break it into concrete tasks we can start including them in milestones like https://github.com/WordPress/gutenberg/issues/24551

[Retrofitterdk]

Looks great, but I’m just wondering how custom page templates will fit into this - according to https://developer.wordpress.org/themes/template-files-section/page-template-files/ they would be first in template hierarchy. Will it stay that way, or will they fit in somewere else or not at all?