Software Engineering in WordPress, PHP, and Backend Development

Tag: Laravel Herd

How To Use Roots Radicle with Laravel Herd

I’ve previously written about using Laravel Herd as my preferred PHP development environment. Outside of my day-to-day work, I’m also working with a couple of friends on a project that includes an iOS app that talks to a REST API via headless WordPress backend.

The web app is built using a set of tools from Roots including Radicle:

Radicle is an opinionated starting point for WordPress projects with the Roots stack.

In short, Radicle allows us to use features of Laravel within WordPress. But one of the challenges with my set up is getting Laravel Herd and Radicle to actually work.

Turns out, the solution isn’t that hard. And if you’re in a similar situation, here’s how to work with Radicle with Laravel Herd.


Roots Radicle with Laravel Herd

Project Set Up

First, I’m operating on the assumption that you have your project is already linked and secured with Herd.

In our case, we’re using a monorepo that contains both the iOS app and the web application. The web app in question is located in projects/monorepo-name/apps/wordpress. So I’ve issued the usual commands add that directly to Herd.

Secondly, I’ve got the .env file configured so that it has all of the necessary information for the database, various WP environmental variables, salts, and other information required to stand up the web app.

The Actual Problem

Third, and this was the most problematic, I had to add a custom driver that would allow Radicle to work with Laravel Herd. The path to custom drivers on your machine may vary but if you’re running the latest version of macOS and haven’t customized the Herd installation then it should look something like this:

/Users/yourname/Library/Application Support/Herd/config/valet/Drivers

Note that if the Drivers directory doesn’t exist, create it. Then touch a file named RadicleValetDriver.php in that directory and add the the following code (you shouldn’t need to change any of it):

<?php

namespace Valet\Drivers\Custom;

use Valet\Drivers\BasicValetDriver;

class RadicleValetDriver extends BasicValetDriver
{
    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return file_exists($sitePath.'/public/content/mu-plugins/bedrock-autoloader.php') &&
               file_exists($sitePath.'/public/wp-config.php') &&
               file_exists($sitePath.'/bedrock/application.php');
    }

    /**
     * Determine if the incoming request is for a static file.
     *
     * @return string|false
     */
    public function isStaticFile(string $sitePath, string $siteName, string $uri)/* : string|false */
    {
        $staticFilePath = $sitePath.'/public'.$uri;
        if ($this->isActualFile($staticFilePath)) {
            return $staticFilePath;
        }

        return false;
    }

    /**
     * Get the fully resolved path to the application's front controller.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        $_SERVER['PHP_SELF'] = $uri;
        if (strpos($uri, '/wp/') === 0) {
            return is_dir($sitePath.'/public'.$uri)
                            ? $sitePath.'/public'.$this->forceTrailingSlash($uri).'/index.php'
                            : $sitePath.'/public'.$uri;
        }

        return $sitePath.'/public/index.php';
    }

    /**
     * Redirect to uri with trailing slash.
     *
     * @return string
     */
    private function forceTrailingSlash(string $uri)
    {
        if (substr($uri, -1 * strlen('/wp/wp-admin')) == '/wp/wp-admin') {
            header('Location: '.$uri.'/');
            exit;
        }

        return $uri;
    }
}

Note this is running on PHP 8.4 so you may need to adjust your function signatures and other features if you’re running on a significantly lower version (though I didn’t really test thing on anything lower than 8).

Once done, you should be able to load your project in the web browser. If not, restarting Herd’s services should do the trick. And, on the off change you still have an error, the stack trace should be easy enough to follow to see where the problem lies.

Given a vanilla Herd set up and Radicle integration with your WordPress project, this custom driver should be all you need to get everything working with as little effort as possible.

Note: This was adapted directly from the Laravel source code which you can find on GitHub.

Catch Outgoing Emails From WordPress in Laravel Herd

Earlier this year, I swapped my local development environment over to Herd (along with a couple of other changes such as DBngin which is worth covering in another post).

There’s a lot to like about it one of which is how easy it is to begin capturing outgoing emails from whatever application you’re using.

From the docs:

Herd Pro provides an SMTP mail server on your local machine that catches all outgoing emails instead of sending them to the world. It displays them in Herds own email client and provides rich debugging capabilities for all types of emails.

Emails From WordPress in Laravel Herd

If you’re using WordPress and you’re looking for an extremely quick way to add this functionality to your local installation, add the following code to an mu-plugin:

<?php
/**
 * Initializes the PHPMailer instance before it is used to send an email.
 *
 * This action hook is used to configure the PHPMailer instance with the necessary
 * SMTP settings, such as the host, authentication, port, username, and password.
 *
 * @param PHPMailer $phpmailer The PHPMailer instance being initialized.
 */
add_action('phpmailer_init', function ($phpmailer) {
    $phpmailer->isSMTP();
    $phpmailer->Host = '127.0.0.1';
    $phpmailer->SMTPAuth = true;
    $phpmailer->Port = 2525;
    $phpmailer->Username = 'WordPress';
    $phpmailer->Password = '';
});

For example, I have a file – herd-mail.php – located in mu-plugins. Once this is added, any outgoing email from WordPress will be immediately captured and funneled to Herd’s email inbox for review.

Notes

  • PHPMailer is part of WordPress core so there’s no need to install a third-party library).
  • phpmailer_init is a native WordPress hook.
  • It’s also really easy to set up Xdebug in Visual Studio Code to work with Herd. If you’re interested in learning how, review this article.

How To Configure Laravel Herd, Xdebug, and Visual Studio Code

I’ve recently switched to Laravel Herd for local development. It uses Valet internally, which I obviously like, and comes with a lot of tools out of the box that make some of the overhead of development much easier.

It’s a hard hard at work.

And any utility that makes it easy to focus on actually writing code while reducing anything that deals with reading logs, configuring different versions of PHP, and even debugging is something I’m in favor of using.

Off the shelf, Herd makes debugging with PHPStorm easy; however, if you’re to get started with Laravel Herd, Xdebug, and Visual Studio Code then there’s a little more configuration to do.


Laravel Herd, Xdebug, and Visual Studio Code

A Word About Herd Documentation

I want to point out I think Herd’s documentation and file structure is one of the best I’ve seen. It’s easy to understand, easy to navigate, and easy to find various configuration files – say php.ini or debug.ini – regardless of the version of PHP you’re using.

A quick example of the directory structure of how Herd organizes its files and configuration.

Case in point, see the following pages:

That said, there’s not much in the way of how to configure Xdebug and Visual Studio code.

Herd, Xdebug, and Code

Here are the steps what worked for me to get my local environment setup. Note this was tested with PHP 7.4, 8.0, and 8.2.

For the following example, note I’m using Apple Silicon and am going to be using PHP 7.4. Very few things should be different save for the paths to the files references in the below code.

HERD

Changing PHP versions is trivial in Herd. This is a matter of selecting the version you want to install and/or marking it as active for your current site.

I mention this though, because it’s important to know which one you’ve got activated so you can properly update the relative Xdebug configuration.

XDEBUG

Unless you’ve set up Herd in some abnormal manner, you should find the extension in the following path:

/Applications/Herd.app/Contents/Resources/xdebug/xdebug-74-arm64.so

From here, you want to open the relative php.ini file and add the following. Note that this is different than what the Herd docs show. I don’t know if it’s because they are specific to PHPStorm or not, but this is what worked for me with Visual Studio Code.

First, locate the php.ini file in the following path:

/Library/Application Support/Herd/config/php/74/

Then append the following to the file:

zend_extension=/Applications/Herd.app/Contents/Resources/xdebug/xdebug-74-arm64.so
xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.start_upon_error=yes
xdebug.idekey=ECLIPSE
xdebug.client_port=9003

You should not need to touch the debug.ini related to the the PHP version in the same direction.

VISUAL STUDIO CODE

Finally, in Visual Studio Code, create a .vscode directory if it doesn’t already exist in the root of the project. Next, add launch.json to the directory.

In that file, add the following configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch Built-in web server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:0"
            ],
            "program": "",
            "cwd": "${workspaceRoot}",
            "port": 9003,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

You’ll likely need to restart Herd after this so issue the $ herd restart command in your terminal.

Conclusion

Now you should be able to set breakpoints, add watches, step into code, and all of the usual things you can do with the Xdebug but in a Herd environment.

And if you’re completely new to Xdebug, I wrote an extensive tutorial on it some time ago.

© 2025 Tom McFarlin

Theme by Anders NorenUp ↑