Hierarchy
, (*1)
Representation of the WordPress template hierarchy with PHP objects., (*2)
TOC
What / Why?
For every frontend request, WordPress runs a query, and then loads a template file depending on the query., (*3)
The map query => template follows rules defined in the template hierarchy., (*4)
However, given a query object, there's no way to programmatically:, (*5)
- know which template WordPress will load
- know which templates WordPress will search
- apply the same "query-to-template resolution" to a query
This library provides a way to do the 3 things listed above., (*6)
Template Hierarchy Representation
Given a query, this library provides a template hierarchy representation in form of a PHP array:, (*7)
Example:, (*8)
// we will show template hierarchy for the main query
global $wp_query;
$hierarchy = new Brain\Hierarchy\Hierarchy();
var_export($hierarchy->hierarchy($wp_query));
Assuming we're visiting an URL like example.com/category/foo/page/2, and the category ID
for the term "foo" is 123, the output of code above is:, (*9)
array(
'category' => array('category-foo', 'category-123', 'category'),
'archive' => array('archive'),
'paged' => array('paged'),
'index' => array('index'),
);
And if you compare that array with the visual overview of template hierarchy
you can verify what's above is an accurate representation of the template hierarchy for a category query., (*10)
Template Resolution
If the question you want to answer is:, (*11)
Which templates WordPress will try to find for this query?, (*12)
It can be simply answered using the Hierarchy::templates() method:, (*13)
// we will target the main query
global $wp_query;
$hierarchy = new Brain\Hierarchy\Hierarchy();
var_export($hierarchy->templates($wp_query));
Assuming the same query as above, the output will be:, (*14)
array(
'category-foo',
'category-123',
'category',
'archive',
'paged',
'index',
);
That is the list of templates WordPress will search, in the same order that WordPress will use., (*15)
Template Resolution Example
For this example, I will assume that a theme has template files stored in /templates subfolder and
using .phtml as file extension., (*16)
All the code necessary to load those templates according to template hierarchy is the following:, (*17)
add_action('template_redirect', function() {
$templates = (new Brain\Hierarchy\Hierarchy())->templates();
foreach($templates as $template) {
$path = get_theme_file_path("/templates/{$template}.phtml");
if (file_exists($path)) {
require $path;
exit();
}
}
});
The example above works, and is just an example of what you can do with this library., (*18)
However, for the purpose to load templates, this library provides a specific class: QueryTemplate., (*19)
Introducing QueryTemplate
QueryTemplate class makes use of the Hierarchy class to get a list of templates to search, then
it looks for those templates and loads the first found., (*20)
Example:, (*21)
add_action('template_redirect', function(): void {
global $wp_query;
$queryTemplate = new \Brain\Hierarchy\QueryTemplate();
echo $queryTemplate->loadTemplate($wp_query);
exit();
});
The code above does exactly what WordPress does: the proper template is found searching in the theme
folder and in parent theme folder (if current theme is a child theme) then the first template
found is loaded and its content is printed to page., (*22)
Please note how template content is returned by QueryTemplate::loadTemplate(), so echo is
necessary to actually display page content., (*23)
However, it is just the default behavior, and it can be customised., (*24)
Template Finders
By default, QueryTemplate class, searches for templates in theme (and parent theme, if any)
folder, just like WordPress does., (*25)
However, it is possible to use a different "template finder" class to do something different., (*26)
All the template finder classes have to implement the Brain\Hierarchy\Finder\TemplateFinder interface., (*27)
The library comes with a few classes implementing that interface, and of course, it is possible to
write a custom one., (*28)
Finder\ByFolders
The class Brain\Hierarchy\Finder\ByFolders can be used to search for templates in some
arbitrary folders, instead of theme and parent theme folders., (*29)
Example:, (*30)
add_action('template_redirect', function(): void {
$finder = new \Brain\Hierarchy\Finder\ByFolders([
__DIR__,
get_stylesheet_directory(),
get_template_directory(),
]);
$queryTemplate = new \Brain\Hierarchy\QueryTemplate($finder);
echo $queryTemplate->loadTemplate();
exit();
});
The snippet above will search for templates in the current folder and if templates are not found
there, they are searched in theme and parent theme folders., (*31)
Custom file extensions
Finder\ByFolders class, by default, searches for files with .php extension, but it is
possible to use different file extensions, by passing them as a second constructor argument (either
a string or an array of strings):, (*32)
// This will look for *.phtml files.
$phtml_finder = new \Brain\Hierarchy\Finder\ByFolders(
[get_stylesheet_directory(), get_template_directory()],
'phtml'
);
// This will look for Twig files first, and fall back to standard PHP files if
// no matching Twig file was found.
$twig_finder = new \Brain\Hierarchy\Finder\ByFolders(
[get_stylesheet_directory(), get_template_directory()],
'twig',
'php'
);
Finder\BySubfolder
This template finder class is very similar to Brain\Hierarchy\Finder\ByFolders, however it looks
for templates is a specific subfolder of theme (and parent theme) and use theme (and parent theme)
folder as fallback:, (*33)
add_action('template_redirect', function(): void {
$finder = new \Brain\Hierarchy\Finder\BySubfolder('templates');
$queryTemplate = new \Brain\Hierarchy\QueryTemplate($finder);
echo $queryTemplate->loadTemplate();
exit();
} );
Using code above the templates are searched, in order, in:, (*34)
/path/to/wp-content/child-theme/templates//path/to/wp-content/parent-theme/templates//path/to/wp-content/child-theme//path/to/wp-content/parent-theme/
Finder\BySubfolder, just like Finder\ByFolders, accepts (a variadic number of) custom file
extensions from the second constructor argument., (*35)
Finder\Localized
This finder class works in combination with another finder, and allows loading templates based on
the current locale:, (*36)
add_action('template_redirect', function(): void {
$foldersFinder = new \Brain\Hierarchy\Finder\ByFolders();
$finder = new \Brain\Hierarchy\Finder\Localized($foldersFinder);
$queryTemplate = new \Brain\Hierarchy\QueryTemplate($finder);
echo $queryTemplate->loadTemplate();
exit();
} );
Assuming the current locale is it_IT, using code above, the templates are searched, in order, in:, (*37)
/path/to/wp-content/child-theme/it_IT//path/to/wp-content/parent-theme/it_IT//path/to/wp-content/child-theme/it//path/to/wp-content/parent-theme/it//path/to/wp-content/child-theme//path/to/wp-content/parent-theme/
Finder\SymfonyFinderAdapter
This class allows to use the Symfony Finder Component
to find templates:, (*38)
add_action('template_redirect', function() {
$symfonyFinder = new \Symfony\Component\Finder\Finder();
$symfonyFinder = $symfonyFinder->files()->in(__DIR__);
$finder = new \Brain\Hierarchy\Finder\SymfonyFinderAdapter($symfonyFinder);
$queryTemplate = new \Brain\Hierarchy\QueryTemplate($finder);
echo $queryTemplate->loadTemplate();
exit();
} );
Finder\ByCallback
This class can be used to easily integrate 3rd party different loaders with QueryTemplate class., (*39)
In fact, you need to provide an arbitrary callback that will be called to find templates., (*40)
The callback will receive the template name without file extension, e.g. index and has to return
the full path of the template if found, or an empty string if the template is not found., (*41)
Example:, (*42)
add_action('template_redirect', function(): void {
$callback = fn(string $tpl): string => realpath(__DIR__ . "{$template}.php") ?: '';
$finder = new \Brain\Hierarchy\Finder\ByCallback($callback);
$queryTemplate = new \Brain\Hierarchy\QueryTemplate($finder);
echo $queryTemplate->loadTemplate();
exit();
} );
Core Filters for Template Loading
When WordPress searches for a template in template-loader.php, it triggers different filters in
the form of {$type}_template;
examples are 'single_template'. 'page_template' and so on., (*43)
Moreover, the found template passes through the 'template_include'
filter., (*44)
By default, QueryTemplate::loadTemplate() applies same filters, to maximize compatibility with
core behavior., (*45)
That happens no matter the template finder is used., (*46)
However, by passing false as second argument to the method it will stop to apply those core
filters., (*47)
Introducing Template Loaders
After a template is found with any of the finder classes, QueryTemplate has to "load" it., (*48)
By default, loading is just a require wrapped by ob_start() / ob_get_clean() so that the
template content is returned as-is., (*49)
However, is it possible to process the template in some ways, for example, by using a template
engine., (*50)
Custom template loaders have to implement Brain\Hierarchy\Loader\Loader interface, that has just
one method: load(), that receives the full path of the template and have to return the
template content., (*51)
Template loaders can be passed as second constructor argument to QueryTemplate., (*52)
Loader\FileRequire
This is the a loader class that ships with the library, and it provides the default behavior., (*53)
Aggregate Loaders
Aggregate loaders uses different "inner" loaders to load templates., (*54)
Aggregate loaders have to implement the interface Brain\Hierarchy\Loader\Aggregate that has two
methods:, (*55)
addLoader(Loader\TemplateLoader $loader, callable $predicate)addLoaderFactory(callable $loaderFactory, callable $predicate)
The first is used to add a template loader instance.
The second is used to add a factory that once called will return a template loader instance., (*56)
Both methods accept as second argument a "predicate": a callback that will receive the path of the
template file to load, and will return a boolean., (*57)
When the predicate returns true, the related loader is used to load the template., (*58)
Loader\Cascade
Loader\Cascade is a simple implementation of an aggregate loader, where the predicates are
evaluated in the same order they are added (FIFO)., (*59)
Loader\ExtensionMap
Loader\ExtensionMap is another aggregate loader implementation shipped with Hierarchy., (*60)
It is used to load different loaders based on template file extension., (*61)
It requires an extensions-to-loaders "map" to be passed to constructor., (*62)
The map keys are the template file extensions, the values are the loader to be used., (*63)
Loaders can be passed as:, (*64)
- template loader instances
- template loader fully qualified class names
- factory callbacks that once called return template loader instances
The same loader can be used for multiple file extensions, using as map key a string composed by many
file extensions separated by a pipe |., (*65)
Example:, (*66)
$loader = new Loader\ExtensionMap([
'php|phtml' => new Loader\FileRequire(),
'mustache' => fn() => new MyMustacheAdapter(new Mustache_Engine),
'md' => MyMarkdownRenderer::class
]);
QueryTemplate Usage Example: Loading and Rendering Mustache Templates
The following will present all the code necessary to find and render mustache
templates according to WordPress template hierarchy., (*67)
namespace My\Theme;
use Brain\Hierarchy\{Finder, Loader, QueryTemplate};
class MustacheTemplateLoader implements Loader\Loader
{
private $engine;
public function __construct(\Mustache_Engine $engine)
{
$this->engine = $engine;
}
public function load(string $templatePath): string
{
// let's use a filter to build some context for the template
$data = apply_filters('my_theme_data', ['query' => $GLOBALS['wp_query'], $templatePath);
return $this->engine->render(file_get_contents($templatePath), $data);
}
}
add_action('template_redirect', function() {
if (!QueryTemplate::mainQueryTemplateAllowed()) {
return;
}
$queryTemplate = new QueryTemplate(
// will look for "*.mustache" templates in theme's "/templates" subfolder
new Finder\BySubfolder('templates', 'mustache'),
// the loader class defined above
new MustacheTemplateLoader(new \Mustache_Engine())
);
// 3rd argument of loadTemplate() is passed by reference, and set to true if template is found
$content = $queryTemplate->loadTemplate(null, true, $found);
// if template was found, let's output it and exit, otherwise WordPress will continue its work
$found and die($content);
});
Requirements
Hierarchy requires PHP 7.1.3+ and Composer to be installed., (*68)
Installation
Best served by Composer, available on Packagist with name brain/hierarchy., (*69)
Migration from version 2.*
The library logic in version 3 is not changed, but now all classes use type declaration, and some of
them has been renamed., (*70)
Libraries based on Hierarchy which are implementing its loader/finder interfaces will have some work
to do to rename classes and add type declaration., (*71)
The class FileExtensionPredicate has a slightly changed signature., (*72)
Libraries which are only using Hierarchy class, should work without any change, even if the methods
getHierarchy() and getTemplates() are now deprecated in favor of, respectively, hierarchy()
and templates(), but old method will not removed in any version 3.* release., (*73)
License
Hierarchy is released under MIT., (*74)
Wallogit.com
