How to Use Laravel Sail with Docker for PHP 8.2 (No Global PHP Upgrade Needed)

Working on a Laravel project that requires a newer PHP version can be tricky if your system’s PHP is older. My personal computer is a Mac, but my work computer is a Linux machine where I sometimes run small projects for exploring and learning new technologies. In that case, upgrading my global PHP installation is not an option since I'd risk messing with work projects. This is exactly the kind of situation Laravel Sail is for. Laravel Sail lets you use Docker to run your Laravel app with the required dependencies, all while keeping your global system versions untouched.

Here is how I set up new Laravel projects on a Linux computer (works on macOS, Linux, or Windows via WSL2) with Sail and the latest versions of PHP (without touching the global version).

First, get your project and terminal ready

Once you have your Laravel project files ready it's time to run some commands.

• If you're using a Laravel starter kit with Inertia and React or Vue, the installation process might have already run npm install for you. If not, go ahead and run that. Otherwise, skip this command.

• Now, try running composer install.
  If you get an error because you have an older version of PHP than required...good! We're on the same page.

Next, we need to run a temporary Docker container to get the latest versions of the required dependencies. Run this command:
docker run --rm \ -u "$(id -u):$(id -g)" \ -v "$PWD":/var/www/html \ -w /var/www/html \ laravelsail/php82-composer:latest \ composer install

What the above command does:
It spins up a temporary Docker container using the Laravel Sail PHP 8.2 image, executes composer install inside the project folder, and then stops and removes the container.

• docker run --rm: Start a new container, and remove it (--rm) when it’s done (so it won’t hang around on your system).

• -u "$(id -u):$(id -g): Run the container with your user’s UID:GID. This ensures any files Composer creates (like the vendor folder) will have the correct permissions matching your user, not root.

• -v "$PWD":/var/www/html: This command mounts your current host directory into the container at /var/www/html, allowing the container to access and modify files in your project.

• -w /var/www/html: This sets the working directory inside the container to /var/www/html, ensuring that subsequent commands run in the correct context.

• laravelsail/php82-composer:latest: This specifies the Docker image to use. It’s an image with PHP 8.2 and Composer installed (provided by Laravel Sail).

• composer install: This is the command we want to run inside the container. It will install all the dependencies as if you ran it on a machine with PHP 8.2.

Configure Sail and Docker

Run the Sail installation (Artisan) command inside Docker. This command publishes the docker-compose.yml file and updates your .env with environment variables for Docker.

Note: If you want to use a different database in your project rather than the default MySQL, add the --with= flag to the command. To keep the default MySQL db, omit the additional flag.

Run:
docker run --rm \ -u "$(id -u):$(id -g)" \ -v "$(pwd)":/var/www/html \ -w /var/www/html \ laravelsail/php82-composer:latest \ php artisan sail:install --with=pgsql

This docker command is similar to the previous one, except now we're executing the artisan sail:install setting up Docker/Sail along with the optional PostgreSQL db configuration.

You should see a docker-compose.yml file in the root of your project now.

Note: The values added to your .env (and the ones in docker-compose.yml) are mostly default/local settings. For example, Sail might set DB_PASSWORD=password and DB_USERNAME=sail (or postgres) for your database, which are local credentials for the Docker containers.
If you're anything like me and have multiple Laravel projects running at the same time, you might need to adjust port numbers. For instance, you probably need to add APP_PORT in the .env file and customize the value with something like APP_PORT=7070 to have your app run on port 7070 instead of the default port 80, where 80 is already in use. Just make sure you update your docker-compose.yml file to match this. The same is true for SERVER_PORT, and SERVER_HOST (and VITE_PORT, if you have an inertia frontend).

It's time to launch Sail

Run:
./vendor/bin/sail up -d. OR
sail up -d, if you already created the alias for sail.
The -d flag runs containers in the background and frees up your terminal shell.

At this point, the above command should run successfully.

If you cloned a repo your .env file won't have an app key value. If this is true for you, run this command while Sail is running: sail artisan key:generate.

Now, run migrations: sail artisan migrate.

If you're using Inertia, this is where you want to start the frontend application: sail composer run dev.

Congrats, now you can happily code to your programmer hearts content. Go build, but don't forget to ship!