Tooling
Laravel Valet

PMC Local Using Laravel Valet

The current recommended local environment uses pmc-vvv but for Apple Silicon Macs that does require a paid version of Paralells Pro (opens in a new tab), vvv (opens in a new tab), and Vagrant (opens in a new tab). Valet offeres a free local environment but it does require a little bit more manual setup compared to VVV.

Benefits

  • No SSHing into Vagrant in order to interact with WordPress installs/brands.
  • Easy native folder structure for managing files.
  • Better performance.
  • Ability to debug, run code coverage, and test much quicker.

Requirements

Before We Start

  • By default the username and password are both pmcdev as defined by the install script.
  • You can “migrate” your VVV sites by rsyncing the uploads over the mounted directory + using wp db import/export for the database.
  • Reviewing phpinfo(); information can assist greatly with troubleshooting PHP versions and their different extensions, such as Xdebug and memcache.

Setup

  • Install Laravel Valet (opens in a new tab) by following the instructions. Really you can stop after valet install is run and continue below.
  • Install wp-cli (opens in a new tab).
  • Install mysql or mariadb via homebrew. Recommend mariadb as it's more scalable and generally more performant, via brew install mariadb.
  • Check running services using brew services list and if mariadb or mysql is not running run brew services start mariadb and then run mysql_secure_installation.
    • NOTE: Newer version of mariadb may require you run mysql-secure-installation.
  • You should also nginx and php running.
  • Install imagemagick, ghostscript, and zlib as helpers: brew install imagemagick ghostscript zlib.
  • Install igbinary (opens in a new tab) and imagick (opens in a new tab) via pecl (opens in a new tab). pecl install igbinary and pecl install imagick.
  • Install memcached (opens in a new tab) via brew install wget autoconf pkg-config libmemcached.
  • Start memcached by running brew services start memcached. It may be running already after install, but you can check brew services list to confirm.
  • Install memcache. 
    pecl install --onlyreqdeps --nobuild memcache
cd "$(pecl config-get temp_dir)/memcache"
phpize
./configure --with-zlib-dir=/opt/homebrew/opt/zlib
make && make install
  • Update php.ini file and add extension="memcache.so". 
    valet php --ini
sudo vim /path/to/php.ini

NOTE: This update of memcache (and xdebug below) needs to be done for every version of PHP in use. Running the above scripts with 8.1 running, if switching to 8.0 the scripts will need to be run again.

  • This may need to be a relative path to the memcache location. For example: /opt/homebrew/Cellar/[email protected]/8.2/memcache.so.
  • Restart valet with valet restart to utilize these values.
  • Follow the steps for setting up PHPUnit steps below.
  • Follow the Adding Your First Site steps below.

Adding Your First Site

  • Copy the following bash script into the ~/pmc directory and in your .bashrc or .zshrc file add the following line alias setupwp="~/pmc/install-site.sh".
  • Create a directory at ~/pmc/sites.
  • Link this to Valet using valet park. All subdirectories in the ~/pmc/sites directory will serve at https://<directory-name>.test.
  • Add the wordpress-develop code using git clone git://develop.git.wordpress.org/ wordpress-develop && cd wordpress-develop to the ~/pmc/sites directory.
  • Change directories to your sites folder: cd ~/pmc/sites.
  • Run setupwp and define, at minimum, the brand name. Additional details below at Install Script.
  • Run valet secure <directory-name>.test eg. valet secure indiewire.test which will ensure that your sites will serve up via https.
  • Add /_static/ location and fasctcgi buffer directives to the site's nginx server block by using the injection script. If that script can't be executed, open the ~/.config/valet/Nginx/site-name file and in the secure and non-secure server { objects add the following code, replacing USERNAME and SITENAME with the respective values:
    # Enable concat scripts/styles (per https://github.com/Automattic/nginx-http-concat#installation--configuration)
    location /_static/ {
        fastcgi_pass "unix:/Users/USERNAME/.config/valet/valet.sock";
        fastcgi_index "/Users/USERNAME/.composer/vendor/laravel/valet/server.php";
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /Users/USERNAME/pmc/sites/SITENAME/wp-content/mu-plugins/http-concat/ngx-http-concat.php;
    }
 
    # Increase buffer size for larger requests (like in editor)
    fastcgi_buffers 16 16k;
    fastcgi_buffer_size 32k;

Install Script

Site Installation Script

  1. Make it executable: chmod +x install-site.sh

Example usage: setupwp -b indiewire -v false -t pmc-indiewire-2023 where the brand is indiewire, it is not in a vip theme directory, and the theme slug is pmc-indiewire-2023.

This script will do the following.

  • Create a database using mysql. Recommend looking at Accessing Databases with SequelAce or Similar below.
  • Create a directory for your first site. For example mkdir indiewire which will serve up at https://indiewire.test.
  • Install WordPress and configure.
  • Install all of the necessary plugins and themes.
  • Activate the theme.
  • Install the PHPUnit test and configure.

Options

  • -d or --database: Set the database name.
  • -u or --username: Define the mysql username. Default root.
  • -p or --password: Define the mysql password. Default (empty string).
  • -b or --brand: Define the brand name and directory to created. Required.
  • -t or --theme: Define the brand theme slug to be pulled. Required.
  • -v or --vip: Define whether or not the theme should be installed in the vip directory. Default true.
  • -w or --wp: Define the WordPress version. Default 6.2.2.
  • -c or --child: Installs the PMC Core V2 parent theme. Default false.

NOTE: The brand and the theme are the only required values.

Nginx Site Configuration Injection Script

Nginx Configuration Injection Script

Valet creates an Nginx server block for each site that has been provisioned with a self-signed SSL certificate (valet secure). Unfortunately these server blocks can be regenerated under certain circustances, such as changing the Valet domain, re-valet secureing a site, etc. To componesate for this, the location/buffers can be automatically injected for all sites in a designated directory:

Installation

  1. Download the script
  2. Make it executable: chmod +x inject-server-block-configurations.sh
  3. Verify that its sites_directory variable points to your Valet sites directory (default ~/pmc/sites)

NOTE: You can run this for all sites at the root ~/pmc/sites or likely if you've run the script on sites previously, cd into the site you want to update and run the script.

Usage

Execute the script with

  • ./inject-server-block-configurations.sh in its directory
  • bash ~/path/to/script/inject-server-block-configurations.sh elsewhere

Xdebug on Valet

Install xdebug with pecl. For Apple Silicon run arch -arm64 pecl install xdebug else run pecl install xdebug.

Valet should automatically configure xdebug for you and you can confirm that it's running by running valet php -v and seeing the "Zend xDebug" information.

If it does not display:

  • Open the php.ini file (for your version of PHP) and add the following lines. It will be the same "Configuration File (php.ini) Path" defined by your valet php --ini command above.
  • pecl should add the extension="xedbug.so" to the top of your php.ini file.
  • If extension doesn't work try zend_exension.
  • We will need to define the mode, below, in our php.ini.
[xdebug]
xdebug.mode = debug,develop,coverage
xdebug.start_with_request = yes
  • Run valet restart.
  • Rerun valet php -v and confirm that it is active.

PHPUnit

  • Install phpunit-polyfillsusing composer (opens in a new tab) with composer global require --dev yoast/phpunit-polyfills:"^2.0"
  • Install phpunit globally with composer (opens in a new tab): composer global require --dev phpunit/phpunit ^9.
  • Once installed, add this to your .bashrc or .zshrc file:
# Local PHPUnit 9 (for Laravel Valet sites)
phpunit9() {
    export PHPUNIT_BIN="$(which phpunit)"
    export CURRENT_PROJECT_NAME="$(cut -d/ -f6 <<<"$(pwd)")"
    export PMC_PHPUNIT_BOOTSTRAP="${HOME}/pmc/sites/${CURRENT_PROJECT_NAME}/wp-content/plugins/pmc-plugins/pmc-unit-test/bootstrap.php"
    export WP_TESTS_DIR="${HOME}/pmc/sites/${CURRENT_PROJECT_NAME}/tests/phpunit"
    if [[ -f ${PHPUNIT_BIN} ]]; then
        echo "Setting PHPUnit 9 binaries";
        echo "Boostrap: ${PMC_PHPUNIT_BOOTSTRAP}";
        echo "Testing Directory: ${WP_TESTS_DIR}";
        ${PHPUNIT_BIN} $@
    else
        echo "Cannot locate the PHPUnit binaries"
    fi
}

NOTE: This assumes that your local sites are located at /Users/USERNAME/pmc/sites and may need to be updated if you choose to house theme elsewhere.

Nginx Buffer Size

By default the buffer and buffer size should be set appropriately, but It's recommended that the FastCGI Response Buffer be updated if they are not.

Check your buffer size using getconf PAGESIZE which should report back ~16k. If it does not add the following to /opt/homebrew/etc/nginx/valet/valet.conf in the group that has the php location, eg: location ~ [^/]\.php(/|$) {:

# ADDED CUSTOM － NOT VALET DEFAULT
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
# END CUSTOM

Activate by running valet restart or brew services start nginx.

Additional reading here (opens in a new tab) which is unrelated to Valet, but a good rundown of the issues associated with smaller fastcgi buffers.

Managing PHP Versions

Valet offers a php switcher that can be used by calling valet use -- 8.0 for example to change the php version to PHP 8.0.

NOTE: The memcache update made above will only apply to the PHP version in use, so you may need to add the memcache line to other php.ini files if the PHP version is changed.

Other Tools

It's recommend to install phpmon (opens in a new tab) for a nice GUI for managing PHP and other related values. It also helps to resolve any related PHP issues by flagging them and offering suggestions for resolving them. Several issues in finding the php.ini file and versions were resolved with this tool.

Accessing Databases with SequelAce (opens in a new tab) or Similar GUI

  • Host: 127.0.0.1
  • Username: root
  • Password: (Empty) or your password set manually with mysql_secure_installation.

NOTE: If you still don't have access with an empty string as the password try running mysql_secure_installation and setting the root password that way.

Troubleshooting

  • I removed a pmc-vvv site, but I'm unable to access the site with valet.
    • On macOS, Remove the site from the /etc/hosts file. sudo vim /etc/hosts and remove the line or entry for the site you can't access.
    • Run sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder to flush host cash.
    • Run valet restart.
  • mariadb or mysql won't start if Docker is in use.
    • Look to confirm that Docker isn't running which utilizes similar dependencies.
  • Valet is running, but my site doesn't load.
    • Run valet status and make sure that everything is "Yes".
  • I updated my PHP version and now my sites are broken.
    • Try running valet restart.
      • Note any errors that may be displayed which might point to a configuration directory issue. What to do with: Xdebug requires Zend Engine API version xxxxxxxx. The Zend Engine API version 2xxxxxxxx which is installed, is newer.
        • Make sure the extension_dir value in the php.ini is mapped to the current PHP version defined by Valet.

Errors

  • Valet requires PHP 8.0 or later.. Update to PHP 8. By default some macs may have PHP 7.4 installed.
  • PHP Startup: Unable to load dynamic library 'memcache.so'. Confirm that you are updating the php.ini that valet is using, which differs from the MacOS version.
  • Warning: file_get_contents(/var/root/.valet/config.json): failed to open stream: Permission denied in /Users/Username/.composer/vendor/laravel/valet/server.php on line XX: Run cd ~/.composer && sudo chown -R $(whoami) vendor
  • zsh: permission denied: /Users/USERNAME/pmc/install-site.sh: Give the script permission using chown -R USERNAME:owner /Users/USERNAME/pmc/install-site.sh.
  • [...] "fastcgi_buffers" directive is duplicate in [...]: Remove the fastcgi_buffers values set during the setup process and restart nginx.
  • Composer dependency requires a higher version of PHP. Check your version of valet. Valet 4.1.3 was the last version to support PHP 8.0.
  • ERROR 1698 (2002) access denied for user 'root'@'localhost'. Run mysql without any username or password to see if it connects. If it does, type ALTER USER 'userName'@'localhost' IDENTIFIED BY 'New-Password-Here';
PMC VVVConnecting Jetpack