Help me understand the Blade compile process—how are hashed files served?



[edit] I still don’t fully understand how Blade figures out which hashed template to load, but I was able to set up a CI pipeline on WPE. I found that Toby’s instructions don’t work precisely with the current WPE setup—the biggest difference is that I push templates to the plugins folder instead of the WP root. Specifically, I stuck it in mu-plugins. Will share exact config details after a little more testing. [/edit]

I’ve been struggling to hammer out a good workflow for deploying to the WPEngine environment. I’m close—but I can’t seem to get the right set of compiled templates into the live environment.

Theme in question is built on Sage 9.0.0-beta.2.

Because I can’t compile Blade templates at runtime, I’m building them with Blade Generate on a Gitlab CI runner, borrowing very heavily from the instructions @toby wrote up here.

My setup is slightly different from Toby’s: I’m using PHP 5.6.31 locally and in WPE, so I used a PHP 5.6.31 Docker container as well. I also find that I need to run Blade Generate twice—the WP CLI won’t let it run the first time.

The CI pipeline does work as I would expect, and pushes everything inside my theme root, along with the compiled blade templates at the WP dir root. The site doesn’t work normally after this push, however. I end up with a bunch of errors from Illuminate’s PhpEngine.php, which can’t seem to find the right hashed template. It tries to load files that don’t exist.

One odd observation: which each push, I should sending a completely new set of templates to WPE. So, I would think Blade could find all the files, or perhaps it would fine none? On the front end, SOME templates do typically load, but not all. Clearing the WPE object cache sometimes seems to help, but there are always some templates that stay missing.

So! How should Blade determine which hashes it’s looking for? Did I miss a step in forcing the theme to recognize new hashes? Should I just start shopping for another host?


Yikes… after a nice full day examining this issue I see Toby more or less laid out where I’ve run into a problem back in May.

That said… I am still a little stuck compiling at the correct path. For me, this command in the suggested deploy script:

doesn’t yield a dir structure that matches the WPE /nas/content/staging/${WPE_INSTALL}/

…back to poking around.


So close!

In my CI server, I am now building my theme in a dir structure that matches Toby’s instructions / WPE’s environment. The WP root is:


and the theme lives in:


…exactly as the WPE error logs indicate their dir structure looks .

However, I can’t seem to get the Blade templates to compile at the WP root, /nas/content/live/$WPE_INSTALL/

In setup.php, I have this:

$paths = [ 'dir.root'       => ABSPATH, ];
config([ 'view.compiled'   => "{$paths['dir.root']}/cache/compiled",

Also tried {$paths['dir.uploads']}../../cache/compiled and setting dir.root to get_home_path()

Locally the templates compile where I would expect. But on Gitlab, I get this:

I activate the theme before Blade compiling. What’s going on?


Man. I’m about ready to throw in the towel. As far as I can tell, the build on Gitlab is now working perfectly. The theme compiles how I expect it to, and it compiles with a path that perfectly aligns with WPE.

The git repo contains what I would expect it to contain—I build the theme and the appropriate template files / style assets turn up as modified. For example, making a change to a Blade template file results in a git push like this:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   cache/compiled/e44aff2943eb53187e579c802b5ef45def8c9655.php
	modified:   wp-content/themes/theme-xxx-theme/templates/partials/header.blade.php
	modified:   wp-content/themes/theme-xxx-theme/vendor/autoload.php
	modified:   wp-content/themes/theme-xxx-theme/vendor/composer/autoload_real.php
	modified:   wp-content/themes/theme-xxx-theme/vendor/composer/autoload_static.php
	new file:   wp-content/themes/theme-xxx-theme/yarn.lock

No dice—this push leads to a white screen of death, and the following WPE error message:

PHP Fatal error: Class 'Composer\\Autoload\\ComposerStaticInitf5a82a475bf50221871bc9038e73b976' not found in /nas/content/live/testnbt/wp-content/themes/theme-xxx-theme/vendor/composer/autoload_real.php on line 30

The string in the Composer class changes with every build… which sounds right to me. How is the autoloader supposed to work? The entire /vendor dir is under git. What am I missing here? I’d hate to pull Blade out and throw away a couple weeks’ worth of work but I can’t think of anything else to try here.


@jamesfacts I hope you haven’t given up. I blogged about it a while back and you’ll find the answers here

Feel free to reach out to me on Twitter @tobyschrapel since I don’t check here often if you are still struggling.


Thanks so much for chiming in, @toby! I did end up getting it to work, with a few small tweaks. Your guide was really, really helpful—I would have never figured it out without your tips.

The biggest thing I ended up changing was the location of the compiled templates. WPE didn’t like them in the root, so I stuck them under /mu-plugins.

The good news is that everything works—but I still don’t 100% understand how the autoloader knows which hash to look for.


I changed them to the root and did mention it in the article but perhaps not clear enough