Migrating Legacy Laravel Applications to Sail

I'll show you how to install Laravel Sail on your existing Laravel application that uses an older PHP version, using the correct PHP version for your project.

Understanding Version Compatibility

Before starting, you need to determine the correct versions:

1. Check your required PHP version in composer.json:

   "require": {
      "php": "^7.3"
   }

2. Check Laravel version in composer.json:

   "require": {
      "laravel/framework": "^8.0"
   }

3. Use LaravelVersions.com to verify PHP version compatibility with your Laravel version.
4. For Laravel 8 with PHP 7.4, you'll need Laravel Sail version ^1.12, as newer Sail versions require PHP 8.0+.

Step-by-Step Installation

1. Install Laravel Sail

We'll use a Docker container to avoid relying on local PHP installation. The command format is:

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php74-composer:latest \
    composer require laravel/sail:^1.12 --dev --ignore-platform-reqs

Note: Replace php74 with your required PHP version (e.g., php73 for PHP 7.3).

2. Install Sail's Docker Configuration

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

This command:

• Uses the same PHP version as before
• Skips interactive prompts with --with=mysql
• Creates the necessary Docker configuration files

3. Set Correct PHP Version and Node Version

After installation, modify your docker-compose.yml file.

First, find this line:

context: ./vendor/laravel/sail/runtimes/8.2

Change it to match your PHP version:

context: ./vendor/laravel/sail/runtimes/7.4

Then, change the Node.js version to avoid npm compatibility issues. Add NODE_VERSION: '18' to the Laravel container's build args:

laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/7.4
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
                NODE_VERSION: '18'

Then rebuild your containers:

sail down && sail build --no-cache && sail up -d

4. Configure Environment

Ensure your .env file exists:

cp .env.example .env

Update your .env database configuration:

DB_HOST=mysql
DB_USERNAME=sail
DB_PASSWORD=password

5. Start Sail

./vendor/bin/sail up -d

6. Run Migrations

./vendor/bin/sail artisan migrate

7. Optional: Add Sail Alias

Add this to your ~/.bashrc or ~/.zshrc:

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

Then reload your shell configuration:

source ~/.bashrc  # or ~/.zshrc if using zsh

Common Issues and Solutions

1. PHP Version Mismatch

If you see errors about PHP version compatibility, make sure you're using the correct Sail version:

• Sail ^1.12 for PHP 7.x projects
• Sail latest for PHP 8.x projects

2. Missing Extensions

If you see errors about missing PHP extensions during installation, use the --ignore-platform-reqs flag with Composer. The actual Docker environment will include all required extensions.

3. Database Connection Issues

If you can't connect to the database after setup, verify:

• The containers are running (sail ps)
• Your .env file has the correct database configuration

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com