Set Up Valet on macOS for Local WordPress Development

This is a guide on how to set up Laravel Valet on macOS for a WordPress local development environment. Using Valet as a WordPress local development solution has the main benefits of speed, being lightweight and using fewer configurations to go wrong than say a solution like Vagrant.

There is a 2nd related article that looks at getting WordPress themes, plugins and settings already installed and ready to deploy.

Valet runs only on macOS and runs directly on top of the operating system, not in a virtual container.

The key software components needed are Homebrew; a package manager and Laravel; a PHP framework.

Valet itself has an Nginx, PHP 8.2 and DnsMasq and by default uses the .test domain name, you add in a database MariaDB or MySQL. Once the software is all installed Valet itself will launch automatically on startup of macOS.

Set Up Local Development Environment

Install Homebrew

First up is to install Homebrew so the key parts of the web stack such as PHP and MySQL/MariaDB can get installed easily.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This will install the Homebrew package manager and Xcode command line tools if not already installed.

If you need to install Apple’s command line tools manually, especially after a macOS upgrade you can run a command in the terminal:

xcode-select --install

Install Composer

Install composer with Homebrew

brew install composer

Get PHP set up

Install PHP

brew install php

This will install the latest version of PHP 8.2, after the Valet installation is done you can also install earlier versions of PHP such as 7.4 and 8.1, like so:

valet use [email protected] 

and/or:

valet use [email protected]

If the PHP packages are not present on the system then Homebrew will download and install – then you can toggle PHP versions with the valet use command.

If you get a syntax error .composer/vendor/illuminate/support/Collection.php on line 103 – run…

composer global update

Get MySQL set up

For MySQL I am using the latest MariaDB 11.1

Also if you are using a version of the app using @10.10 etc, after install you need to add the path to your shell as it is an older Homebrew formula, you are recommended of this at the shell prompt after Homebrew installs – example below of path with mariaDB path in .bash_profile

export PATH="/usr/local/opt/[email protected]/bin:~/bin:~/.composer/vendor/bin:/usr/local/sbin:$PATH"

Install MySQL/MariaDB – background service works after restart

brew install mariadb

or…

brew install mysql

or another supported version:

brew install [email protected]

Current mariadb versions available for install are listed on the Homebrew mariadb page or for MySQL versions check this Homebrew MySQL page.

Start it as background service

brew services start mariadb

or…

brew services start mysql

MariaDB installs with the active macOS user account shortname with no password.

Get Laravel Valet set up

Install Valet with composer

composer global require laravel/valet

Make sure your macOS shell path has the following location, this will allow you to easily use valet commands on the command line – if you don’t include it you will need to prefix all valet commands with ~/.composer/vendor/bin/

~/.composer/vendor/bin

Install valet

valet install

Now valet will will install dnsmasq and install and set up Nginx and PHP and start valet, some basic valet commands below…

valet stop
valet restart
valet --version

Do a ping test to a fictitious domain .test address, look for some pingbacks from 127.0.0.1

ping blah.test

A responding ping will verify dnsmasq and the other components have been successfully set up.

Confirm you have dnsmaq, mysql, Nginx and php running…

brew services list

Output should be…

admin@192-168-1-104 ~ % brew services list
Name      Status  User  Plist
dnsmasq   started root  ~/Library/LaunchAgents/homebrew.mxcl.dnsmasq.plist
mariadb   started neilg ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist
nginx     started root  ~/Library/LaunchAgents/homebrew.mxcl.nginx.plist
php       started root  ~/Library/LaunchAgents/homebrew.mxcl.php.plist

Your output may also show the Homebrew services list with errors and error numbers like below:

dnsmasq error  512 root  ~/Library/LaunchAgents/homebrew.mxcl.dnsmasq.plist
mariadb started    neilg ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist
nginx   error  256 root  ~/Library/LaunchAgents/homebrew.mxcl.nginx.plist
php     started    neilg ~/Library/LaunchAgents/homebrew.mxcl.php.plist

There may be nothing wrong – just as long as the services are working, the pingback from a .test domain will show DnsMasq is working and if you do a PHP test page with phpinfo() command from a local website and it displays that will show NGINX and PHP are working.

To update Laravel Valet

composer global update
valet install
valet restart

Webroot Directory & Valet park command

Probably the best method for a webroot directory is to use the Sites folder in your home, this was a traditional webroot in the past of the macOS user account filing system – if one is not there either make one in the Finder or via the Terminal

mkdir ~/Sites

Register the Sites folder with Valet, so any top level folders will be treated as a serving site – use the park command

cd ~/Sites
valet park

There is also a valet link command that allows a directory somewhere else in the filing system to serve its content as a webroot, it does so by putting a symbolic link in the park directory – Sites.

WordPress and Valet

So the best code to serve up ready made WordPress sites is wp-cli-valet-command it can spin up sites very quickly and can be further enhanced taking advantage of bash scripting.

First of all, you need to have wp-cli installed, use Homebrew to install or manually this guide can cover that process.

brew install wp-cli

Increase your PHP memory size, especially if you installed PHP with Homebrew – otherwise, a fatal error will occur when installing wp-cli-valet-command package, find your PHP memory limits .ini config file

php --ini
nano /usr/local/etc/php/7.4/conf.d/php-memory-limits.ini

Change limits to 1024M in all 3 places.

This is the config file where you can increase resources in the future for processes such as max_input_vars etc

Also, make sure your MySQL or mariadb is running…

brew services start mariadb

Once you have wp-cli add the wp-cli-valet-command package

wp package install [email protected]:aaemnnosttv/wp-cli-valet-command.git

Once this is installed you are ready to create some WordPress sites…

To install a new site, move into your Sites folder and run a wp valet command

cd ~/Sites
wp valet new newsitename

This will set up https://newsitename.test ready to go WP-Admin defaults are admin/admin for username and password.

All new sites are by default set up with https – to set one up just as http – run…

wp valet new newsitename --unsecure

To remove a site…

wp valet destroy newsitename

For more commands and options check out the GitHub repo for wp-cli-valet and also you can create custom sites with a certain theme, plugins, etc by rolling your own bash scripts.

Toggle SSL

To toggle between whether or not a site uses an SSL cert..

valet unsecure mysitename

or

valet secure mysitename

Terminal output

Restarting nginx...
The [mysitename.test] site has been secured with a fresh TLS certificate.

phpMyAdmin

To deal with MySQL via phpmyAdmin – create a new site

cd ~/Sites
wp valet new phpmyadmin

So now you have a https://phpmyadmin.test – remove all the WordPress files and download and move into the folder the latest phpmyadmin files – if your MySQL install is no password then change the config file as prompted to AllowNoPassword. Now all your databases are easily accessible.

You can take WordPress site installation further with Valet by adding a bash script that includes further refining the install with plugins and themes tailoring – see the next article on Valet, wp-cli and bash scripting.

mariaDB 10.4 ERROR 1698 (28000): Access denied for user ‘root’@’localhost’

Since v10.4 mariadb has had some root/password major changes, if you are getting this error  when creating new sites with valet use your macos shortname instead with a db user variable like so…

wp valet new sitename --dbuser="admin"

So a new site ‘sitename’ is created with the macOS shortname of the account ‘admin

If you get a syntax error .composer/vendor/illuminate/support/Collection.php on line 103 – run…

composer global update

Using Valet without an admin password

The default behaviour is for an admin password to be requested for each valet command, this can be surpasses with…

valet trust

Which allows both valet and Homebrew commands to be password free.

Sudoers entries have been added for Brew and Valet.

References

Install valet

Install wp-cli-valet-command

Install wp-cli

Install Homebrew

Older PHP 5.6 & 7

10 Comments

  1. Tahoe on January 26, 2021 at 5:19 pm

    Couldn’t managed to make it work on M1 Mac/Big Sur unfortunately. wp-cli-valet-command doesn’t seem to be compatible with PHP 8 (see this GitHub issue https://github.com/aaemnnosttv/wp-cli-valet-command/issues/70), and you can’t downgrade to PHP 7 since it’s not compatible with Apple Silicon :(

  2. Nil Mel on May 22, 2020 at 10:59 am

    I want to buy a new MAC which one can you advise to me?

  3. Marcy Diaz on December 26, 2019 at 11:23 pm

    Thanks for this, Neil! It made installing valet on a new system super easy (It had changed a bit, since my last install, and my notes were out of date.)

    For anyone who doesn’t know how to add to the $PATH, add in terminal:
    export PATH=$PATH:~/.composer/vendor/bin

  4. Andrew Holdun on December 12, 2019 at 8:51 pm

    Thanks, Martin! I was going crazy until I read your suggestion!

  5. Constant Solutions on May 2, 2019 at 4:44 pm

    I had a small migrene running into memory leak issues, and intially I thought memory limits were not being changed to 512megabytes, only to learn that it actually was set, but 512megabytes was not enough.

    Setting memory limits to 1024 megabytes solved the issue.

    • Neil Gowran on October 18, 2019 at 8:31 am

      Thanks – updated the post with that increase

  6. Conaba on May 2, 2019 at 3:13 pm

    I needed to run `composer self-update` before running `composer global require “laravel/installer”`

  7. Kash on February 27, 2019 at 12:56 pm

    Thank you for sharing this.
    It helped me twice! once on ubuntu and now on Mac OS

  8. Martin on August 13, 2018 at 5:15 pm

    Thanks for taking the time to document this, very helpful!

    Just in case it helps others, I got the message “valet install” command not found. Used the command below instead
    test -d ~/.composer && bash ~/.composer/vendor/bin/valet install || bash ~/.config/composer/vendor/bin/valet install

    This is on a fairly fresh install of High Sierra so I’m guessing others will have the issue?

    • Tom on July 2, 2019 at 6:11 pm

      Had this same issue and this seems to be working, thanks!

Leave all Comment