[wp-trac] [WordPress Trac] #64465: Add locate_template_paths filter to allow extending template resolution paths

[WordPress Trac]

#64465: Add locate_template_paths filter to allow extending template resolution
paths
-----------------------------+--------------------------------------
 Reporter:  lucascarvalhopl  |      Owner:  (none)
     Type:  enhancement      |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  Themes           |    Version:  trunk
 Severity:  major            |   Keywords:  has-patch has-unit-tests
  Focuses:  template         |
-----------------------------+--------------------------------------
 The `locate_template()` function currently searches for templates in a
 fixed and hard-coded set of locations (child theme, parent theme, and
 `theme-compat`). While this works well for the default theme hierarchy, it
 does not provide a way for themes or plugins to participate in the
 template *resolution process* itself.

 A practical use case is a setup where:

 * A site uses a third-party parent theme that cannot be modified.
 * Child themes are developed for different clients with several template
 parts shared across them.
 * `get_template_part()` is used extensively to load reusable template
 fragments.

 Without a way to extend the template lookup paths, the only option today
 for this shared template parts is to copy the files into every child
 theme, which leads to unnecessary duplication and higher maintenance cost.

 This proposal introduces a new filter that allows developers to modify the
 list of template paths *before* the lookup occurs, without altering the
 existing template hierarchy.

 Example:
 {{{#!php
 <?php
 add_filter( 'locate_template_paths', function( $paths ) {
     // Insert shared default templates after the child theme path.
     $custom_path = WP_CONTENT_DIR . '/themes/shared-default/templates/';
     array_splice( $paths, 1, 0, array( $custom_path ) );

     return $paths;
 } );
 }}}


 With this approach:

 * `get_template_part()` and related APIs can resolve template parts from a
 shared default location.
 * No existing themes or plugins are affected unless they explicitly opt
 in.
 * This does not overlap with `template_include`, which operates at a
 different stage and does not affect template part resolution.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64465>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform