Updating PHP Version for Laravel Forge and Sail: A Step-by-Step Guide

1. Update composer.json

The first step is to ensure that the version in composer.json matches the PHP version you plan to install. In this example, we will use 8.2.14.

{
  "require": {
    "php": "8.2.14"
  }
}

2. Run sail up -d

This command starts the Sail containers in case they aren't running.

3. Run sail composer update

It is important to run sail composer update to ensure that the composer.lock file is updated and synchronized with the changes made in the composer.json file.

4. Updates in Laravel Forge

Make sure you are running the exact version of PHP as set in the composer.json before pushing your changes to Laravel Forge. You can install security patches for the current PHP version by clicking "Patch". Note that Forge does not allow you to set a specific version, so you might need to update to the latest patch of the PHP version you are using and set that in composer.json to ensure they match.

5. Push Changes

Depending on your Forge configuration, you may need to deploy manually, or deployment may happen automatically based on commits to a certain branch.

Example of Deployment Errors If the PHP Versions Do Not Match

Root composer.json requires php 8.2.13 (exact version match: 8.2.13 or 8.2.13.0) but your PHP version (8.2.14) does not satisfy that requirement.

In such a case, ensure your composer.json reflects the correct version, and do not forget to run sail composer update to apply those changes to the composer.lock as well.

If the sail composer update command fails due to a mismatch in the Docker container version, you can run sail up --build to rebuild the Laravel container using the latest version of PHP set in your docker-compose.yml.

services:
  laravel.test:
    build:
      context: ./docker/8.2
      dockerfile: Dockerfile
      args:
        WWWGROUP: '${WWWGROUP}'
    image: sail-8.2/app

As I am using the /docker/8.2/Dockerfile, rebuilding the container installs the 8.2.14 version of PHP.