I’m a fan of using both Homebrew and Valet when it comes to setting up and configuring a basic WordPress development environment. Though using package managers and simple software for such like this should make things easier, it doesn’t absolve us from the occasional problems.
Case in point: There are times in which we may have to update our TLD to play nicely with Chrome and other browsers, or even upgrade the entire installation.
Unfortunately, it’s not always as easy as it should be. Technically, we should be able to uninstall Valet and update it via Composer. But I’ve personally run into some problems that relegated having to:
- manually uninstall Valet,
- use Homebrew to uninstall PHP and clean up what was left completely,
- reinstall Homebrew packages,
- install Valet,
- verify the browser uses the same version of PHP as the installation of Valet.
It sounds like a lot of work for something that should more or less “just work” and it is quite a few steps, but they are pretty quick to set up.
When Valet Stops Working
So if you find yourself in a situation where Valet isn’t working with WordPress or Homebrew or any either of them, then perhaps the following steps will help.
1. Manually Remove Valet
According to the documentation, we should be able to run:
$ valet uninstall
To complete remove the software, but that doesn’t work. Instead, we need to completely remove it by removing its directory and associated binary.
If you’re running macOS, the way to do this is to remove the .vendor directory and the valet binary found in /usr/local/bin/valet.
To do this, enter the following commands in the terminal:
$ rm -rf ~/.valet $ rm ~/usr/local/bin/valet
Though you shouldn’t receive any error messages, you may have to run sudo to remove the binary (but if this is the case, then it was likely removed installed improperly the first time.
2. Use Homebrew to Remove PHP
One of the nice things about Homebrew is that it allows us to run multiple versions of PHP and switch between them. This is especially useful if you’re working with various projects for widespread use or specialized environments.
To see what versions of PHP are on your system, you can run the following:
$ brew list
And you should see something like this:
Next, remove the following packages:
- dnsmasq
- nginx
- php
And if you have multiple versions of PHP, then you’re going to want to remove all versions of the software. To do this, enter the following commands:
$ brew uninstall dnsmasq && brew uninstall nginx && brew uninstall php $ brew cleanup
You may also need to run brew uninstall for each version of PHP if you have multiple versions that are running on your system.
Note that if you have several versions of PHP running, you may also run into problems removing each of them.
If that’s the case, then you’re going to need to force remove (by using the –force command), or you may need to recursive remove a given directory that brew reports. This will need to be done for each of the installations of PHP.
Once done, remember to run cleanup.
Next, you may want to go ahead and run doctor to see if there are any problems and resolve them if there are any. In many cases, you’ll find broken symbolic links which can then removed by typing brew prune.
If you do that and run brew doctor again, then everything should look good:
And you’ll be ready to begin moving forward repairing the installation.
3. Reinstall Homebrew Packages
Next, let’s install the most recent version of PHP. You can, of course, opt to install any given version of PHP that but that’s the content for another post (or you can see what’s available on this page).
First, you may need to tap the homebrew/php repository if it’s not already in your list of available repositories; however, you can check to see what you do have by simply entering
$ brew tap
If you see homebrew/php then you’re good to go.
So, from there, let’s update brew:
$ brew update
Then install the latest version of PHP by entering:
$ brew install homebrew/core/php
At the time of this writing, this is PHP 7.2.5.
To verify that it’s been installed correctly, you can enter which php in your terminal and /usr/local/bin/php should be returned. Next, if you run php -v you should see 7.2.5 returned as the version.
4. Reinstall Valet
Now it’s time to reinstall Valet. Do to this, enter the following command in your terminal:
$ composer global require laravel/valet
Next, make sure you execute the following command:
export PATH="$PATH:$HOME/.composer/vendor/bin"
This ensures the global Composer binaries are located in your system’s environmental variables and are available anywhere on your system.
Next, run valet install. This will install dnsmasq and nginx which are components necessary to run Valet.
5. Verify the Browser Works as Expected
Before testing the browser, we want to ping the local environment to make sure the web server is working as expected. To do this, enter the following in the terminal:
$ ping foo.test
Assuming all is set up correctly, you should get a response:
Now it’s time to make sure that the browser is using the same version PHP that we installed in the previous step. To do this, create a directory anywhere on your system, call index.php and then enter the following in the file:
<?php phpinfo();
Next, navigate to the directory in your terminal – I’ve called mine beta – and then enter the following command in your terminal:
$ valet link && valet secure
Next, load up https://beta.test in your browser. Assuming all goes well, this is what you should see:
Notice that the version of PHP that’s being used is the same that we installed earlier.
Why Do This Manually?
At this point, you have a fully working Valet installation with the latest version of all of the necessary packages. Unfortunately, the uninstall command doesn’t do what you’d expect it does and it leaves some artifacts behind.
Thus, this is why I’m a fan of removing everything manually, doing an update, and then reinstalling Valet.
If you run into problems with your installation – especially if you’re using BrowserSync, Yarn, or the like – then this should resolve those problems (along with any other that you may be experiencing).