Fix template resolution to give precedence to child theme PHP templates over parent theme block templates with equal specificity (alternative approach)

[ockham]

Alternative approach to #1961. For a general idea of the challenges that a solution to this issue faces, and some design choices, see the code comments in the diff.

Make sure to smoke test with an FSE theme.

Description of the issue (as found in the corresponding Trac ticket) below:

---

When a theme has a PHP template of a certain specificity (e.g. page-home.php), and it happens to be a child theme of another theme which has a block template for the same specificity (e.g. page-home.html), WordPress will currently pick the parent theme’s block template over the child theme's PHP template to render the page.

This is a regression. If the PHP and block template have equal specificity, the child theme's template should be used. This issue was fixed before in WordPress/gutenberg#31123. The relevant logic has since been modified and eventually backported to Core , so the fix now needs to happen in Core (plus GB's pre-WP-5.9 compat layer, but that's somewhat secondary).

We have a unit test for this (but obviously had to disable it). The unit test existed in Gutenberg before but didn’t fail there due to a faulty test setup. In fact, the issue was only found while backporting the unit test.

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

---

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.

[ockham]

cc/ @WordPress/gutenberg-core for review 🙂

[youknowriad]

Is it possible that the fallback is actually different than the block template slug but has more priority. Ex: single.php, index.html. Which one would win here?

[ockham]

Is it possible that the fallback is actually different than the block template slug but has more priority.

No, we prevent that by truncating the list of candidate templates that we pass from locate_block_template() to resolve_block_template() to only include equal or higher specificity than the PHP fallback template:

wordpress-develop/src/wp-includes/block-template.php

Lines 25 to 48 in 8bd1509

	if ( $template ) {
	/*
	* locate_template() has found a PHP template at the path specified by $template.
	* That means that we have a fallback candidate if we cannot find a block template
	* with higher specificity.
	*
	* Thus, before looking for matching block themes, we shorten our list of candidate
	* templates accordingly.
	*/
	// Locate the index of $template (without the theme directory path) in $templates.
	$relative_template_path = str_replace(
	array( get_stylesheet_directory() . '/', get_template_directory() . '/' ),
	'',
	$template
	);
	$index = array_search( $relative_template_path, $templates, true );
	// If the template hiearchy algorithm has successfully located a PHP template file,
	// we will only consider block templates with higher or equal specificity.
	$templates = array_slice( $templates, 0, $index + 1 );
	}
	$block_template = resolve_block_template( $type, $templates );

[youknowriad]

Ok I guess this looks good to me then.

[ockham]

Back-backport to GB: WordPress/gutenberg#37074

[audrasjb]

Committed in https://core.trac.wordpress.org/changeset/52308