Add a 'template_file' hook to load_template()

[mikeschinkel]

Please consider adding a 'template_file' hook in load_template() to enable the capture of the template filename. I have built a panel for the Debug Bar to be able to show template files loaded but I need this 'template_file' hook to capture the template file names. This would be super useful for developers who are building sites with the complex template loading logic found in various theme frameworks et. al.

With the hook added the code for load_template() might look like this:

function load_template( $_template_file, $require_once = true ) {
  global $posts, $post, $wp_did_header, $wp_did_template_redirect, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;

  if ( is_array( $wp_query->query_vars ) )
    extract( $wp_query->query_vars, EXTR_SKIP );

  $_template_file = apply_filters( 'template_file', $_template_file, $require_once );

  if ( $require_once )
    require_once( $_template_file );
  else
    require( $_template_file );
}

Here's a screenshot showing the Theme Template Files panel I implemented so you can see the use-case. This plugin requires the hook I'm proposing in order to work and I have attached the plugin for other's review.

This hook could also allow the loading of the template file from other directories such as a shared directory on a server, as appropriate, but that's not the reason I found the need today.

The source for load_template() is found in /wp-includes/template.php.

[mikeschinkel]

Patch to add a 'template_file' hook to load_template()

[mikeschinkel]

Debug Bar Theme Files Panel plugin (requires proposed 'template_file' hook to work.)

[mbijon]

This would be a huge help to not only build with client-selected themes (that you may not know inside & out), but also to show clients how their chosen theme may be inefficient or non-performant.

++1

[scribu]

Similar proposal for locate_template(): #13239

[scribu]

If the purpose is logging, a do_action() would suffice, no?

[mikeschinkel]

Replying to scribu:

If the purpose is logging, a do_action() would suffice, no?

Logging is one purpose, but as stated above I could easily see wanting to change the directory from which a template file is loaded so make it a filter since an action would have effectively the same overhead.

[mikeschinkel]

To whom it may concern: Is there any chance this could be considered for 3.5?

[nacin]

I'm weary of adding hooks into load_template() and locate_template() without careful consideration, which are covered by a few other tickets. In this case, get_included_files() should be enough for debugging, yes?

[mikeschinkel]

Replying to nacin:

I'm weary of adding hooks intoload_template() and locate_template() without careful consideration

Weary? How can you be tired of adding hooks there, as there are no hooks there now!

Oh, you mean "wary"... ;-)

But seriously though, get_included_files() seems like a good solution, except the hook 'debug_bar_panels' is fired before /wp-includes/template-loader.php is included, so none of the theme files are available then.

Of course one can call get_included_files() and then use jQuery to add them back into the debug panel but personally I really much prefer to do things in PHP whenever possible; it's so much more testable and robust to use PHP.

That said, I'm curious what types of concerns you have able adding this hook, and hooks like @sival asks for in #18803? Aren't these little different than the 'template_include' hook which lets someone completely change the template?

[chriscct7]

Patch needs a regen from the correct directory as well as docs for the filter.

[johnbillion]

I'm closing this ticket as wontfix for the following reasons:

• Mike opened this ticket because he wanted to view the included template files in Debug Bar. All the cool kids use Query Monitor these days and there's a ​Query Monitor Included Files extension which provides this information and more.
• Allowing a low level file inclusion to be filtered like this is asking for trouble. I share Nacin's wariness. I can imagine plugins reverting to using this filter in order to override all manner of things in themes and other plugins. It sounds like a potential nightmare.

[MikeSchinkel]

Replying to johnbillion:

• Mike opened this ticket because he wanted to view the included template files in Debug Bar.

That was only one of several use-cases as I mentioned.

A useful use-case is to allow plugins to provide default templates for features when the theme developer has not (yet) provided a template.

Another would be to create wrappers for templates without having to modify the theme. Wrappers could allow instrumentation in theme comments when WP_DEBUG is on so that themers that only really know HTML+CSS can be given instructions in view source for what variables and/or object properties are available, etc. I have found that very helpful in the past, but it's only possible for a theme where we control the full callstack to loading template parts.

And there have been numerous times when I wanted more control over get_template_part() which this would provide, e.g. to be able to load a series of different templates based on meta field values in addition to just what was specified to get_template_part() in a parent theme.

All the cool kids use ​Query Monitor these days

Hmm. Haven't heard of that plugin. Wonder who wrote it? ;-p

• Allowing a low level file inclusion to be filtered like this is asking for trouble. I share Nacin's wariness. I can imagine plugins reverting to using this filter in order to override all manner of things in themes and other plugins. It sounds like a potential nightmare.

Given the purpose of plugins is to allow plugin developers to provide users with additional functionality that doesn't require the theme to be modified, not allow this hook seems contrary to the reason WordPress.org frowns on post types in themes. By not supporting this then if certain type of functionality needs to be added it must be added via a theme and not a plugin which means that the end-user will loose the functionality when they switch themes, or worse the them will break.

The downside of a plugin overriding something the user wants is the user stops using the plugin. The downside of switching themes with a plugin that can't protect the user is a broken site. It would seem to me that giving the plugin developer the control needed to ensure the site does not break would be better.

Any chance of delineating a few of the types of things you fear here?

[johnbillion]

I've been looking at the following tickets holistically over the last few weeks:

• #12877
• #13239
• #14310
• #21062
• #22355

I'm going to re-open this ticket as @MikeSchinkel brought up some good points. Further discussion pending.

[MikeSchinkel]

Replying to johnbillion:

I'm going to re-open this ticket as @MikeSchinkel brought up some good points. Further discussion pending.

Given the discussion on #42855 maybe it's time to restart the discussion? :-)

[johnbillion]

Where does time gooooo