[wp-trac] [WordPress Trac] #13239: Filter locate_template template_names variable

[WordPress Trac]

#13239: Filter locate_template template_names variable
-------------------------------------------------+-------------------------
 Reporter:  chrisjean                            |       Owner:  (none)
     Type:  enhancement                          |      Status:  reopened
 Priority:  normal                               |   Milestone:  Future
                                                 |  Release
Component:  Themes                               |     Version:  3.0
 Severity:  normal                               |  Resolution:
 Keywords:  has-patch dev-feedback has-unit-     |     Focuses:
  tests                                          |
-------------------------------------------------+-------------------------

Comment (by lucascarvalhopl):

 Hi everyone — I’d like to update this ticket with a concrete
 implementation that addresses the core use case discussed here.


 == Summary of the implementation

 * I added a focused filter, **`locate_template_paths`**, which allows
 modifying the list of paths that `locate_template()` will check **before**
 the lookup loop runs.
 * The default resolution order remains intact: *child theme* → *parent
 theme* → `theme-compat`.
 * Plugins or themes can control precedence explicitly using
 `array_splice()` / `array_unshift()` to inject paths at the desired
 position.
 * The implementation preserves the current early-exit behavior (breaking
 as soon as a template is found) and **does not introduce additional
 `file_exists()` calls** beyond what already exists — keeping performance
 impact minimal.
 * I added a PHPUnit test (e.g. in `tests/phpunit/tests/template.php`) that
 creates a temporary directory, injects it via the filter, and asserts that
 `locate_template()` resolves the expected file.
 * PHPDoc was added for the new filter to document intent and usage.

 == Example usage

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

 == Request for feedback

 1. Code review regarding performance, security, or edge cases (e.g.
 handling of absolute paths).
 2. Feedback on hook naming, if a different name would better align with
 core conventions.
 3. Guidance on next steps.

 Thanks for taking a look.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/13239#comment:129>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform