1<?php
  2/**
  3 * Block template loader functions.
  4 *
  5 * @package WordPress
  6 */
  7
  8/**
  9 * Adds necessary hooks to resolve '_wp-find-template' requests.
 10 *
 11 * @access private
 12 * @since 5.9.0
 13 */
 14function _add_template_loader_filters() {
 15	if ( isset( $_GET['_wp-find-template'] ) && current_theme_supports( 'block-templates' ) ) {
 16		add_action( 'pre_get_posts', '_resolve_template_for_new_post' );
 17	}
 18}
 19
 20/**
 21 * Renders a warning screen for empty block templates.
 22 *
 23 * @since 6.8.0
 24 *
 25 * @param WP_Block_Template $block_template The block template object.
 26 * @return string The warning screen HTML.
 27 */
 28function wp_render_empty_block_template_warning( $block_template ) {
 29	wp_enqueue_style( 'wp-empty-template-alert' );
 30	return sprintf(
 31		/* translators: %1$s: Block template title. %2$s: Empty template warning message. %3$s: Edit template link. %4$s: Edit template button label. */
 32		'<div id="wp-empty-template-alert">
 33			<h2>%1$s</h2>
 34			<p>%2$s</p>
 35			<a href="%3$s" class="wp-element-button">
 36				%4$s
 37			</a>
 38		</div>',
 39		esc_html( $block_template->title ),
 40		__( 'This page is blank because the template is empty. You can reset or customize it in the Site Editor.' ),
 41		get_edit_post_link( $block_template->wp_id, 'site-editor' ),
 42		__( 'Edit template' )
 43	);
 44}
 45
 46/**
 47 * Finds a block template with equal or higher specificity than a given PHP template file.
 48 *
 49 * Internally, this communicates the block content that needs to be used by the template canvas through a global variable.
 50 *
 51 * @since 5.8.0
 52 * @since 6.3.0 Added `$_wp_current_template_id` global for editing of current template directly from the admin bar.
 53 *
 54 * @global string $_wp_current_template_content
 55 * @global string $_wp_current_template_id
 56 *
 57 * @param string   $template  Path to the template. See locate_template().
 58 * @param string   $type      Sanitized filename without extension.
 59 * @param string[] $templates A list of template candidates, in descending order of priority.
 60 * @return string The path to the Site Editor template canvas file, or the fallback PHP template.
 61 */
 62function locate_block_template( $template, $type, array $templates ) {
 63	global $_wp_current_template_content, $_wp_current_template_id;
 64
 65	if ( ! current_theme_supports( 'block-templates' ) ) {
 66		return $template;
 67	}
 68
 69	if ( $template ) {
 70		/*
 71		 * locate_template() has found a PHP template at the path specified by $template.
 72		 * That means that we have a fallback candidate if we cannot find a block template
 73		 * with higher specificity.
 74		 *
 75		 * Thus, before looking for matching block themes, we shorten our list of candidate
 76		 * templates accordingly.
 77		 */
 78
 79		// Locate the index of $template (without the theme directory path) in $templates.
 80		$relative_template_path = str_replace(
 81			array( get_stylesheet_directory() . '/', get_template_directory() . '/' ),
 82			'',
 83			$template
 84		);
 85		$index                  = array_search( $relative_template_path, $templates, true );
 86
 87		// If the template hierarchy algorithm has successfully located a PHP template file,
 88		// we will only consider block templates with higher or equal specificity.
 89		$templates = array_slice( $templates, 0, $index + 1 );
 90	}
 91
 92	$block_template = resolve_block_template( $type, $templates, $template );
 93
 94	if ( $block_template ) {
 95		$_wp_current_template_id = $block_template->id;
 96
 97		if ( empty( $block_template->content ) ) {
 98			if ( is_user_logged_in() ) {
 99				$_wp_current_template_content = wp_render_empty_block_template_warning( $block_template );
100			} else {
101				if ( $block_template->has_theme_file ) {
102					// Show contents from theme template if user is not logged in.
103					$theme_template               = _get_block_template_file( 'wp_template', $block_template->slug );
104					$_wp_current_template_content = file_get_contents( $theme_template['path'] );
105				} else {
106					$_wp_current_template_content = $block_template->content;
107				}
108			}
109		} elseif ( ! empty( $block_template->content ) ) {
110			$_wp_current_template_content = $block_template->content;
111		}
112		if ( isset( $_GET['_wp-find-template'] ) ) {
113			wp_send_json_success( $block_template );
114		}
115	} else {
116		if ( $template ) {
117			return $template;
118		}
119
120		if ( 'index' === $type ) {
121			if ( isset( $_GET['_wp-find-template'] ) ) {
122				wp_send_json_error( array( 'message' => __( 'No matching template found.' ) ) );
123			}
124		} else {
125			return ''; // So that the template loader keeps looking for templates.
126		}
127	}
128
129	// Add hooks for template canvas.
130	// Add viewport meta tag.
131	add_action( 'wp_head', '_block_template_viewport_meta_tag', 0 );
132
133	// Render title tag with content, regardless of whether theme has title-tag support.
134	remove_action( 'wp_head', '_wp_render_title_tag', 1 );    // Remove conditional title tag rendering...
135	add_action( 'wp_head', '_block_template_render_title_tag', 1 ); // ...and make it unconditional.
136
137	// This file will be included instead of the theme's template file.
138	return ABSPATH . WPINC . '/template-canvas.php';
139}
140
141/**
142 * Returns the correct 'wp_template' to render for the request template type.
143 *
144 * @access private
145 * @since 5.8.0
146 * @since 5.9.0 Added the `$fallback_template` parameter.
147 *
148 * @param string   $template_type      The current template type.
149 * @param string[] $template_hierarchy The current template hierarchy, ordered by priority.
150 * @param string   $fallback_template  A PHP fallback template to use if no matching block template is found.
151 * @return WP_Block_Template|null template A template object, or null if none could be found.
152 */
153function resolve_block_template( $template_type, $template_hierarchy, $fallback_template ) {
154	if ( ! $template_type ) {
155		return null;
156	}
157
158	if ( empty( $template_hierarchy ) ) {
159		$template_hierarchy = array( $template_type );
160	}
161
162	$slugs = array_map(
163		'_strip_template_file_suffix',
164		$template_hierarchy
165	);
166
167	// Find all potential templates 'wp_template' post matching the hierarchy.
168	$query     = array(
169		'slug__in' => $slugs,
170	);
171	$templates = get_block_templates( $query );
172
173	// Order these templates per slug priority.
174	// Build map of template slugs to their priority in the current hierarchy.
175	$slug_priorities = array_flip( $slugs );
176
177	usort(
178		$templates,
179		static function ( $template_a, $template_b ) use ( $slug_priorities ) {
180			return $slug_priorities[ $template_a->slug ] - $slug_priorities[ $template_b->slug ];
181		}
182	);
183
184	$theme_base_path        = get_stylesheet_directory() . DIRECTORY_SEPARATOR;
185	$parent_theme_base_path = get_template_directory() . DIRECTORY_SEPARATOR;
186
187	// Is the active theme a child theme, and is the PHP fallback template part of it?
188	if (
189		str_starts_with( $fallback_template, $theme_base_path ) &&
190		! str_contains( $fallback_template, $parent_theme_base_path )
191	) {
192		$fallback_template_slug = substr(
193			$fallback_template,
194			// Starting position of slug.
195			strpos( $fallback_template, $theme_base_path ) + strlen( $theme_base_path ),
196			// Remove '.php' suffix.
197			-4
198		);
199
200		// Is our candidate block template's slug identical to our PHP fallback template's?
201		if (
202			count( $templates ) &&
203			$fallback_template_slug === $templates[0]->slug &&
204			'theme' === $templates[0]->source
205		) {
206			// Unfortunately, we cannot trust $templates[0]->theme, since it will always
207			// be set to the active theme's slug by _build_block_template_result_from_file(),
208			// even if the block template is really coming from the active theme's parent.
209			// (The reason for this is that we want it to be associated with the active theme
210			// -- not its parent -- once we edit it and store it to the DB as a wp_template CPT.)
211			// Instead, we use _get_block_template_file() to locate the block template file.
212			$template_file = _get_block_template_file( 'wp_template', $fallback_template_slug );
213			if ( $template_file && get_template() === $template_file['theme'] ) {
214				// The block template is part of the parent theme, so we
215				// have to give precedence to the child theme's PHP template.
216				array_shift( $templates );
217			}
218		}
219	}
220
221	return count( $templates ) ? $templates[0] : null;
222}
223
224/**
225 * Displays title tag with content, regardless of whether theme has title-tag support.
226 *
227 * @access private
228 * @since 5.8.0
229 *
230 * @see _wp_render_title_tag()
231 */
232function _block_template_render_title_tag() {
233	echo '<title>' . wp_get_document_title() . '</title>' . "\n";
234}
235
236/**
237 * Returns the markup for the current template.
238 *
239 * @access private
240 * @since 5.8.0
241 *
242 * @global string   $_wp_current_template_id
243 * @global string   $_wp_current_template_content
244 * @global WP_Embed $wp_embed                     WordPress Embed object.
245 * @global WP_Query $wp_query                     WordPress Query object.
246 *
247 * @return string Block template markup.
248 */
249function get_the_block_template_html() {
250	global $_wp_current_template_id, $_wp_current_template_content, $wp_embed, $wp_query;
251
252	if ( ! $_wp_current_template_content ) {
253		if ( is_user_logged_in() ) {
254			return '<h1>' . esc_html__( 'No matching template found' ) . '</h1>';
255		}
256		return '';
257	}
258
259	$content = $wp_embed->run_shortcode( $_wp_current_template_content );
260	$content = $wp_embed->autoembed( $content );
261	$content = shortcode_unautop( $content );
262	$content = do_shortcode( $content );
263
264	/*
265	 * Most block themes omit the `core/query` and `core/post-template` blocks in their singular content templates.
266	 * While this technically still works since singular content templates are always for only one post, it results in
267	 * the main query loop never being entered which causes bugs in core and the plugin ecosystem.
268	 *
269	 * The workaround below ensures that the loop is started even for those singular templates. The while loop will by
270	 * definition only go through a single iteration, i.e. `do_blocks()` is only called once. Additional safeguard
271	 * checks are included to ensure the main query loop has not been tampered with and really only encompasses a
272	 * single post.
273	 *
274	 * Even if the block template contained a `core/query` and `core/post-template` block referencing the main query
275	 * loop, it would not cause errors since it would use a cloned instance and go through the same loop of a single
276	 * post, within the actual main query loop.
277	 *
278	 * This special logic should be skipped if the current template does not come from the current theme, in which case
279	 * it has been injected by a plugin by hijacking the block template loader mechanism. In that case, entirely custom
280	 * logic may be applied which is unpredictable and therefore safer to omit this special handling on.
281	 */
282	if (
283		$_wp_current_template_id &&
284		str_starts_with( $_wp_current_template_id, get_stylesheet() . '//' ) &&
285		is_singular() &&
286		1 === $wp_query->post_count &&
287		have_posts()
288	) {
289		while ( have_posts() ) {
290			the_post();
291			$content = do_blocks( $content );
292		}
293	} else {
294		$content = do_blocks( $content );
295	}
296
297	$content = wptexturize( $content );
298	$content = convert_smilies( $content );
299	$content = wp_filter_content_tags( $content, 'template' );
300	$content = str_replace( ']]>', ']]&gt;', $content );
301
302	// Wrap block template in .wp-site-blocks to allow for specific descendant styles
303	// (e.g. `.wp-site-blocks > *`).
304	return '<div class="wp-site-blocks">' . $content . '</div>';
305}
306
307/**
308 * Renders a 'viewport' meta tag.
309 *
310 * This is hooked into {@see 'wp_head'} to decouple its output from the default template canvas.
311 *
312 * @access private
313 * @since 5.8.0
314 */
315function _block_template_viewport_meta_tag() {
316	echo '<meta name="viewport" content="width=device-width, initial-scale=1" />' . "\n";
317}
318
319/**
320 * Strips .php or .html suffix from template file names.
321 *
322 * @access private
323 * @since 5.8.0
324 *
325 * @param string $template_file Template file name.
326 * @return string Template file name without extension.
327 */
328function _strip_template_file_suffix( $template_file ) {
329	return preg_replace( '/\.(php|html)$/', '', $template_file );
330}
331
332/**
333 * Removes post details from block context when rendering a block template.
334 *
335 * @access private
336 * @since 5.8.0
337 *
338 * @param array $context Default context.
339 *
340 * @return array Filtered context.
341 */
342function _block_template_render_without_post_block_context( $context ) {
343	/*
344	 * When loading a template directly and not through a page that resolves it,
345	 * the top-level post ID and type context get set to that of the template.
346	 * Templates are just the structure of a site, and they should not be available
347	 * as post context because blocks like Post Content would recurse infinitely.
348	 */
349	if ( isset( $context['postType'] ) && 'wp_template' === $context['postType'] ) {
350		unset( $context['postId'] );
351		unset( $context['postType'] );
352	}
353
354	return $context;
355}
356
357/**
358 * Sets the current WP_Query to return auto-draft posts.
359 *
360 * The auto-draft status indicates a new post, so allow the the WP_Query instance to
361 * return an auto-draft post for template resolution when editing a new post.
362 *
363 * @access private
364 * @since 5.9.0
365 *
366 * @param WP_Query $wp_query Current WP_Query instance, passed by reference.
367 */
368function _resolve_template_for_new_post( $wp_query ) {
369	if ( ! $wp_query->is_main_query() ) {
370		return;
371	}
372
373	remove_filter( 'pre_get_posts', '_resolve_template_for_new_post' );
374
375	// Pages.
376	$page_id = isset( $wp_query->query['page_id'] ) ? $wp_query->query['page_id'] : null;
377
378	// Posts, including custom post types.
379	$p = isset( $wp_query->query['p'] ) ? $wp_query->query['p'] : null;
380
381	$post_id = $page_id ? $page_id : $p;
382	$post    = get_post( $post_id );
383
384	if (
385		$post &&
386		'auto-draft' === $post->post_status &&
387		current_user_can( 'edit_post', $post->ID )
388	) {
389		$wp_query->set( 'post_status', 'auto-draft' );
390	}
391}
392
393/**
394 * Register a block template.
395 *
396 * @since 6.7.0
397 *
398 * @param string       $template_name  Template name in the form of `plugin_uri//template_name`.
399 * @param array|string $args           {
400 *     @type string        $title                 Optional. Title of the template as it will be shown in the Site Editor
401 *                                                and other UI elements.
402 *     @type string        $description           Optional. Description of the template as it will be shown in the Site
403 *                                                Editor.
404 *     @type string        $content               Optional. Default content of the template that will be used when the
405 *                                                template is rendered or edited in the editor.
406 *     @type string[]      $post_types            Optional. Array of post types to which the template should be available.
407 *     @type string        $plugin                Optional. Slug of the plugin that registers the template.
408 * }
409 * @return WP_Block_Template|WP_Error The registered template object on success, WP_Error object on failure.
410 */
411function register_block_template( $template_name, $args = array() ) {
412	return WP_Block_Templates_Registry::get_instance()->register( $template_name, $args );
413}
414
415/**
416 * Unregister a block template.
417 *
418 * @since 6.7.0
419 *
420 * @param string $template_name Template name in the form of `plugin_uri//template_name`.
421 * @return WP_Block_Template|WP_Error The unregistered template object on success, WP_Error object on failure or if the
422 *                                    template doesn't exist.
423 */
424function unregister_block_template( $template_name ) {
425	return WP_Block_Templates_Registry::get_instance()->unregister( $template_name );
426}
427