How to Create Page Templates with Laravel Blade in WordPress?

Integrating Laravel Blade was one of the first steps made here while building a custom WordPress theme. If you haven't had a chance to check out the full material about Blade, I insist you do it now, as we'll continue exploring this topic deeper here.

Recently I received a question from Ricardo, a reader concerning issues with page templates using this setup. It turned out they were right! We missed an important detail in our previous discussions which needs to be fixed.

How to create page template?

WordPress offers a built-in feature to create custom templates, which has been one of the nicest tools in my WordPress adventure. These custom templates are incredibly useful, especially when creating custom themes tailored to meet specific client needs.

To add a new template, you need to create a new file in the theme's root directory and add a specific header to it. A similar approach can be used with the Laravel Blade that we use in the system. You need to create a new Blade template in the resources/views directory and add a header, but be aware of a different comments style.

/**
 * Template Name: Example
 */

echo "Lorem Ipsum is simply dummy text of the printing and typesetting industry."

{{--
    Template Name: Custom
--}}

@extends('base')

@section('content')
    Lorem Ipsum is simply dummy text of the printing and typesetting industry.
@endsection

After you create a new template, WordPress will automatically display it in the admin area. Once selected, the content defined within that template will appear on the corresponding page giving you a flexibility to build what you need.

How to change WordPress theme's root?

Ricardo, one of our readers, raised a concern about the initial Laravel Blade integration we implemented. It seems that the custom page templates didn't function as expected there. While adding a new WordPress template in Blade format to resources/views with correct header, it did not appear in the admin area.

{{--
    Template Name: Custom
--}}

@extends('base')

@section('content')
    Lorem Ipsum is simply dummy text of the printing and typesetting industry.
@endsection

By default, WordPress searches for custom page templates in the theme's root directory, located at wp-content/themes/footmate. However, in our Blade setup, we defined views in a different directory: wp-content/themes/footmate/resources/views. Since we relocated these templates on the fly without informing WordPress about the new directory, it couldn't automatically find and display them in the admin area.

To resolve these issues, we need to inform WordPress about the new template location by changing the theme's root directory to wp-content/themes/footmate/resources. Here’s a fun fact about WordPress: The theme's root directory is determined by the location of the style.css file. Therefore, to change the theme's root, simply move the style.css file to the desired location and reactivate the theme in the admin panel.

Now that we've changed the theme's root, you can verify the directory from which WordPress loads its default assets using the get_template_directory function. It's crucial to move other default theme files, such as functions.php, index.php and screenshot.php, to this new location as well, because WordPress will now look for them there.

footmate
│   functions.php
│   index.php
│   LICENSE
│   screenshot.png
│   style.css

footmate
│   LICENSE
└───resources
│   │   functions.php
│   │   index.php
│   │   screenshot.png
│   │   style.css

I owe a big thank you to Ricardo for this contribution, which made this material possible! His impact on this project and the community is deeply appreciated. I'm always grateful for such valuable feedback ❤️

How to adjust the codebase to the change?

Moving the style.css file is just one step in the solution. We also need to tweak the function that maps the WordPress template paths to the Blade files. I’ll spare you the line-by-line breakdown - it’s enough to know that we must update the template paths from their original locations to those managed by Blade.

Array
(
    [0] => views/template-custom.blade.php
    [1] => page-test.php
    [2] => page-28.php
    [3] => page.php
)

Array
(
    [0] => views/template-custom.blade.php
    [1] => views/page-test.blade.php
    [2] => views/page-28.blade.php
    [3] => views/page.blade.php
)

I've already implemented this fix, so if you want to make the same change in your repository, simply modify the relocate function with the changes I've outlined. Also, remember that after changing the theme's root directory as described earlier, you'll need to adjust several other areas in your project codebase to correctly reflect the new paths. I recommend reviewing the entire pull request to see all the changes.

IMPORTANT: The fixes have been also implemented in the original article.

That wraps up today’s material! I’m curious to hear your thoughts on these. While it may not be significant to WordPress development, it offers a view into my debugging journey and the challenges I’ve documented along the way. If this information assists even one person, I consider it a success. Please share your feedback in the YouTube comments!