Valet Linux+

Upgrade Guide

Tip

Coming from the original genesisweb/valet-linux-plus package? Follow the Migrating from genesisweb guide instead.

Upgrading to 2.2

2.2 is a drop-in update. Run:

bash 
composer global require fernandoebert/valet-linux-plus -W
valet install

What is new in 2.2:

  • Per-project Nginx config: publish Valet's Nginx config of a site into the project (valet nginx:publish), customize it and activate it (valet nginx). The customization survives secure, unsecure, isolate, unisolate and domain, is validated with nginx -t before being applied, and can be reverted with valet nginx:reset.

Upgrading to 2.1 from 2.0

Version 2.1 is a drop-in update. Run:

bash 
composer global require fernandoebert/valet-linux-plus -W
valet install

What is new in 2.1:

  • Support for PHP 8.4 and 8.5 in valet use and valet isolate.
  • A contextual 404 page that explains why a site could not be served and how to fix it (see Troubleshooting).

Upgrading to 2.0 from 1.x

In this upgrade, several significant changes have been made. Please follow the steps below to ensure a smooth transition to Valet Linux+ v2.

Requirements

To upgrade to Valet Linux+ v2, ensure your system meets the following requirements:

  • PHP version: PHP 8.2 or higher.

Make sure your environment includes the required PHP extensions. Install or update PHP and the necessary extensions (Ubuntu/Debian example):

bash 
sudo apt install php8.2-cli php8.2-common php8.2-curl php8.2-mbstring php8.2-opcache \
  php8.2-readline php8.2-xml php8.2-zip php8.2-mysql php8.2-gd php8.2-intl

Major changes

Home directory

The configuration directory has moved from ~/.valet to ~/.config/valet. This migration is handled automatically during the upgrade process.

Isolation commands

New commands have been added to support older PHP versions for specific websites:

  • valet isolate {phpVersion} --site=siteName.test --secure
  • valet unisolate --site=siteName.test
  • valet isolated

For more information on these commands, see Isolate PHP Version.

Use command

The valet use command no longer installs older PHP versions. Use the isolate commands to install specific PHP versions for sites.

PHP bash file

A new PHP helper file is installed at /usr/local/bin/php. It supports isolated PHP versions: inside an isolated site's directory it runs the isolated PHP version; anywhere else it runs the system's default PHP version.

Minor changes

Removals

  • Removed the /valet-sites path, as it requires additional support in the new version.
  • Removed the subdomain commands, as they are equivalent to the valet link command since v2.0.

Upgrade steps

1. Update Valet Linux+

bash 
composer global require fernandoebert/valet-linux-plus -W

2. Run the migration process

After updating, run the valet command to start the migration process, which moves your configuration directory to the new location:

bash 
valet

3. Complete the installation

Finally, run valet install to complete the update and ensure all components are properly configured:

bash 
valet install

By following these steps, your Valet Linux+ setup will be updated to version 2 with the new configuration directory and the required PHP version.