Custom php file directory in Wordpress with Timber Twig

Question

I am using Timber with Wordpress (version 5.4.2). I have installed Timber's starter theme as a boilerplate.

Timber leverages the Wordpress template hierarchy allowing you to create a custom PHP file for a given route.

Page.php (default in Timber starter theme)

/**
 * The template for displaying all pages.
 *
 * This is the template that displays all pages by default.
 * Please note that this is the WordPress construct of pages
 * and that other 'pages' on your WordPress site will use a
 * different template.
 *
 * To generate specific templates for your pages you can use:
 * /mytheme/templates/page-mypage.twig
 * (which will still route through this PHP file)
 * OR
 * /mytheme/page-mypage.php
 * **(in which case you'll want to duplicate this file and save to the above path)**
 *
 * Methods for TimberHelper can be found in the /lib sub-directory
 *
 * @package  WordPress
 * @subpackage  Timber
 * @since    Timber 0.1
 */

$context = Timber::context();

$timber_post = new Timber\Post();

$context['post'] = $timber_post;

Timber::render( [ 'page-' . $timber_post->post_name . '.twig', 'page.twig' ], $context );

As per the comments in page.php and the Timber docs, I can create a custom PHP file to load a template for a given page by create it in the root directory of the theme (mytheme/my-custom-php-file.php)

But I will be creating a lot of custom PHP files for the project I'm working on - it would be pretty messy and hard to manage if I just drop them all into the root directory of the theme.

I would instead like to place these files into their own directory mytheme/src/. ex. mytheme/src/my-custom-php-file.php.

Currently, Timber/Wordpress will not recognize this file in this directory.

Where in Timber and/or Wordpress is the directory in which to look for pages' PHP files defined and how can I update this to indicate mytheme/src/?

Answer 1

This is possible, but a little differently than you might expect. You have to put all theme-related files to a subfolder, including functions.php and style.css. WordPress recognizes themes in subfolders.

So here’s what a possible structure could look like:

.
└── wp-content/themes/mytheme/
    ├── theme/
    │   ├── functions.php
    │   ├── index.php
    │   ├── page.php
    │   ├── single.php
    │   └── style.css
    ├── vendor/
    ├── views/
    ├── .gitignore
    ├── composer.json
    ├── package.json
    └── README.md

We’re putting the template files that WordPress needs into a theme subfolder. You can still put your views folder in the theme root, because Timber also looks for Twig templates in that folder.

In your functions.php file, you would then require your Composer dependencies from the parent folder:

require_once dirname( __DIR__ ) . '/vendor/autoload.php';

And there might be some other places where you would have to update paths.

We’re currently thinking about making this the default for the Timber Starter Theme (see this pull request).