How to fix common problems with Laravel Valet

Laravel's Valet is amazing. It makes setting up a new PHP Projects on macOS as easy as creating a folder. Valet has many advantages over for example Docker, as it has less overhead. No need to download images, no need to build them, no additional disk space is blocked by all the VM images, containers so on and so forth. Valet also takes advantage of your full CPU power as it doesn't have to share resources with a parent slash host OS. Of course, Docker has many advantages, too. In this article, however, we won't look at the things that make each of them stand out – instead I want to list all of those smaller and bigger problems one can run into when using Valet in your day to day web development. And of course how to fix them.

General advice

It might sound trivial, but sometimes emptying a browsers cache, or restarting a browser might do wonders. Keep that in mind, whenever you run into problems with Valet.

  • Empty your browsers’ cache. Even redirects might get cached
  • Make sure you use a recent version of Valet. You get updates by running composer global update
  • Look in the right place. Valet logs are actually here: tail -f ~/.config/valet/Log/*
  • Are you using OPCache (for example preloading), Redis or Symfony (var/cache)? Make sure in your logs, that you’re not seeing cached errors. (by either restarting php, doing a redis-cli flushall or rm -rf var/cache/*
  • Re-running valet install will not delete your projects. Sometimes it fixes things. Remember, that after re-install you’ll need to park your Sites folder again.
  • brew services list, brew services info <service name> and brew services restart <service name> can be helpful tools to debug Valet problems, as well.

1. Upgrading PHP can change your php.ini

I work on many computers and laptops, depending on where I am, but I have found myself, setting php memory limits more often than I should have been. The reason is that a brew upgrade of your locally installed PHP can sometimes mess up or overwrite your php.ini file or a new PHP release coming with a new php-memory-limits.ini file.

Solution

One simple approach is to backup your php.ini (or related config files) whenever you change them. What I like to do is, use mercurial or git to track changes. Of course this requires Mercurial to be installed (brew install mercurial} or alternatively you can use Git just as well.


cd /usr/local/etc/php/8.1/
hg init
hg add php.ini

or with Git


cd /usr/local/etc/php/8.1/
git init
git add php.ini

Even though these are local repositories, you have all the benefits of version control. you can see your modifications, as well as the ones done by brew or other processes such as pecl installs.

hg diff php.ini

2. Exotic document root names require a custom ValetDriver

Either you have a index.php in your project root, or inside a folder called public. Otherwise Valet can only find your bootstrap file if you’re using a supported CMS – by using so-called ValetDrivers.

You can actually verify if you have this problem, by appending your public folder name in the browser, eg. http://example.test/my-weird-docroot-path.

The concept of Valet’s Drivers is simple. They are plain PHP files a developer can understand. Take a look at the folders ~/.composer/vendor/laravel/valet/cli/drivers and ~/.config/valet/Drivers for that matter. While many CMS are supported out of the box, you might need a custom driver.

When you start a new project make sure you name your public folder public and you’re all set. For many other CMSs you will find pre-made drivers on gist.github.com. And if none of these steps work for you, write your own driver based off the SampleValetDriver.php.

3. 502 Bad Gateway Error

This one’s a bit tricky as it can have multiple causes.

Solution 1

The solution described in this comment worked for me several times:


sudo cp /usr/local/etc/php/8.1/php-fpm.d/valet-fpm.conf /usr/local/etc/php/8.1/php-fpm.conf
valet restart
Solution 2

If that didn’t do the trick for you, check your ~/.config/valet/Log/nginx-error.log file. If you see an *1 upstream sent too big header while reading response header from upstream error, then you should try to increase the fastcgi buffer sizes as described here.

Create ~/.valet/Nginx/all.conf with this:

~/.valet/Nginx/all.conf
proxy_buffer_size 4096k; proxy_buffers 128 4096k; proxy_busy_buffers_size 4096k;

Append this to /usr/local/etc/nginx/fastcgi_params

/usr/local/etc/nginx/fastcgi_params
fastcgi_buffer_size 4096k; fastcgi_buffers 128 4096k; fastcgi_busy_buffers_size 4096k;
Solution 3

Depending on the size of your codebase or autoloader, you might also need to increase the PHP memory limits. Sometimes PHPs default of 512M just isn’t enough.

You can use php -I | grep memory to verify your current value.

If necessary, then edit /usr/local/etc/php/8.1/conf.d/php-memory-limits.ini and put an appropriate amount (for example 2G) for your system.

4. 504 Gateway Timeout Error

This article in german describes a solution: basically increasing all sorts of Nginx default timeouts to higher values, thus giving your request the time to it needs to finish. After adding the lines to the php block, restart valet.

5. Switching PHP versions

When you’re working on several projects, or maintaining old codebases. Not all of them may play well with your currently installed PHP version. One project might require PHP 7.4 another PHP 8.0 or 8.1.

As of Valet 9.x this is now a problem of the past. If you haven’t done so yet, make sure to upgrade from Valet 8.x to the latest 9.x version.

Now there are a ton of new features which make the use of different PHP versions really easy on a per-project level.

In old versions a simple valet use php@8.0 was not enough. While the CLI reported PHP to be 8.0 the browser did still process requests with the version you don’t want to use. My solution of the past has been to use either valet use, brew’s php-switcher or simply brew link to force the use of a specific version and then adjust 2 PATHs in my .zshrc profile. The great news is, that this is no longer necessary.

There’s:

  • There’s the new .valetphprc file for use with valet use.
  • Then, there’s a brand new valet isolate which let’s you specify the version as well
  • Also there are new shortcuts valet php, valet composer to make sure the version defined in a project is used on the CLI as well, without the need to unlink/link or switch PHP completely
  • valet parked and valet isolated now also tell the PHP version in use on a per project level

What is your opinion on developing with Valet? What problems do you run into? Which ones are missing from this list?