DEV Community

Cover image for Laravel Herd Setup: Sites, PHP Versions, HTTPS and Databases
devTalk
devTalk

Posted on Originally published at dev-talk.com

Laravel Herd Setup: Sites, PHP Versions, HTTPS and Databases

#laravel #herd #localdevelopment #php

Laravel Herd is a local development environment for macOS and Windows that runs PHP and nginx natively, with no Docker and no virtual machine. You put a project in a folder, and it is available at project-name.test a moment later. This guide covers what you get, how to set up a site, how to switch PHP versions per project, how to turn on HTTPS, and where databases fit, using the commands from Herd's own documentation.

What Herd is, and where it runs

Herd bundles PHP, nginx, a local DNS service (so .test domains resolve) and Node. It is available for macOS and Windows. Linux is not supported: the Herd website says the team is working on a Linux version but it is not ready to ship, so on Linux, Laravel Sail or a manual setup is still the route. Plans, as stated on the Herd site at the time of writing:

Plan Price Includes
Herd (free) No cost, no license PHP, nginx, DNS and Node; per-project site configuration; Herd Studio; the PHP Profiler; community support
Herd Pro $99 per year Everything in free, plus MySQL, PostgreSQL, Redis and more as managed services; Mail; Insights; Tinker; Xdebug detection; email support
Herd for Teams $299 per year 10 Pro licenses, a license portal, shared project configuration, priority email support

Prices and plan contents change, so check the Herd website before you budget around them.

Create your first site

Herd parks one directory for you by default: ~/Herd on macOS and %USERPROFILE%\Herd on Windows. Every folder inside a parked directory is served as http://folder-name.test. So the fastest start is:

cd ~/Herd
laravel new my-app
cd my-app
herd open
Enter fullscreen mode Exit fullscreen mode

laravel new creates the application and herd open opens http://my-app.test in your browser. The Herd documentation notes that new Laravel apps use SQLite by default, so this works before you install any database server.

A project that lives somewhere else

You do not have to move existing projects into the Herd directory. Link one from its own folder:

cd ~/code/client-portal
herd link client-portal      # served at http://client-portal.test
herd links                   # list linked sites
herd unlink client-portal
Enter fullscreen mode Exit fullscreen mode

Or park a whole folder of projects so that every subfolder becomes a site:

herd park ~/code
herd parked                  # list sites inside parked paths
herd forget ~/code           # stop serving that folder
Enter fullscreen mode Exit fullscreen mode

HTTPS for a local site

From the project directory, generate a trusted certificate for the site:

herd secure
herd secured      # lists secured sites and when their certificates expire
herd unsecure     # remove the certificate and the HTTPS redirect
Enter fullscreen mode Exit fullscreen mode

Do this when your app needs HTTPS to behave properly, for example secure cookies, OAuth callbacks, or webhooks that refuse plain HTTP. Remember to set APP_URL in .env to the https:// address afterwards.

PHP versions

Herd ships with the latest stable PHP, which its documentation lists as PHP 8.5 at the time of writing. You set a global version, and you can pin individual sites to another one:

herd php:list              # versions and install status
herd php:install 8.3       # install another version
herd use 8.4               # global version for sites that are not isolated

cd ~/Herd/legacy-app
herd isolate 8.2           # pin this site to PHP 8.2
herd isolated              # list pinned sites
herd unisolate             # go back to the global version
Enter fullscreen mode Exit fullscreen mode

If the folder name and the site name differ, add --site="site-name" to herd isolate. The same thing is available in the app: select the site in the Applications window and choose a version in the Environment section.

Use the right PHP in the terminal

The php that your shell finds is not necessarily the version Herd serves for that site. Herd provides wrappers that pick the version configured for the current directory:

herd php artisan migrate
herd composer install
herd which-php             # which PHP binary serves this path
Enter fullscreen mode Exit fullscreen mode

Use these when you see "works in the browser, fails in the terminal" or a Composer platform error that mentions the wrong PHP version. Node works the same way: herd node:install 22 installs a version through Herd's nvm, and herd isolate-node pins one to the current directory.

Databases

This is the part that differs between plans. Herd's PHP includes the extensions for MySQL, MariaDB, PostgreSQL, MongoDB, Redis, Valkey and SQLite, so your code can talk to any of them, but the database servers themselves are another matter:

  • Free: SQLite works out of the box. For MySQL, PostgreSQL or Redis, install the server from its vendor or use a free tool such as DBngin, and point your .env at it.
  • Pro: Herd manages the services for you. You switch an application to a service in the Applications window, Herd updates .env and can create the database. The CLI mirrors this, for example herd services:list, herd services:create <type> and herd db:create.

The documentation pages I read do not list default ports or credentials, so read them from herd db:connection (Pro) or from your own database tool instead of guessing.

Other things worth knowing

  • Health check: herd status shows whether Herd and its services are running. herd restart restarts them.
  • Logs: herd log tails Herd's log files, which is where to look when a site returns an nginx error.
  • Proxies: herd proxy my-api http://127.0.0.1:3000 creates an nginx proxy host, useful for a Node server or a frontend dev server next to Laravel. (Check the exact target format against herd proxy in your version.)
  • Sharing: herd share exposes a site through an Expose tunnel, handy for webhook testing.
  • Debugging: herd debug runs PHP with the site's version and a debug configuration, and herd coverage runs it with Xdebug coverage.
  • Project manifest: herd init configures a project from a herd.yml file, so a team can share setup. See the docs for the format.

Common problems

  • .testsite does not load. Run herd status to see whether nginx, DNS and PHP are running, then herd restart. Check that the folder really sits in a parked path (herd paths) or is linked (herd links).
  • Wrong PHP version. Compare herd which-php with herd isolated, and run commands through herd php and herd composer.
  • Another local server uses ports 80 or 443. Herd and another web server cannot both listen there. Stop the other one (MAMP, an old Valet install, a Docker container publishing those ports). This is general networking behaviour, not a documented Herd message.
  • Database connection refused. On the free plan nothing is running unless you installed a server yourself. Check DB_CONNECTION in .env: a new app uses SQLite.
  • Browser warns about the certificate. Run herd secure from the right directory, then restart the browser, since the certificate is issued per site.

Herd or Sail?

They solve different problems. Herd runs natively, starts fast and needs no container knowledge, but it exists for macOS and Windows only, and your machine's PHP stack is not your server's stack. Sail runs your app in Docker containers, works on Linux and can match production services more closely, at the cost of Docker's overhead and learning curve. Teams on mixed operating systems, or with strict production parity needs, often pick Sail. A solo developer on a Mac who wants a quick setup will usually be happier with Herd. Neither choice locks you in, because your application code does not change.

Sources

Originally published on DEV Talk.

Top comments (0)