About Laravel Sail

Laravel Sail is the official development environment for the Laravel framework. Sail provides a lightweight command-line interface (CLI) to easily set up and manage a Laravel application development environment using Docker. Below, we explain the main features and usage of Laravel Sail.

Benefits of Using Laravel Sail

1. Build a development environment independent of the OS
   • Sail uses Docker to containerize the development environment for Laravel applications. This allows you to build a development environment that is independent of the OS.
2. Easy setup of the development environment
   • With Sail, you can set up a Laravel development environment with just a few commands. Even complex development environments using MySQL, Redis, MailHog, etc., can be easily built.
3. Easy management of projects with different versions
   • For example, the version of Laravel depends on the version of PHP, but by setting the environment for each project in the docker-compose.yml file, you can easily switch versions.

When you create a project using Docker with Laravel Sail, the structure will look like the diagram above.

Usage

Development Environment

• Mac
• PHP v8.3
• Laravel v11
• Docker

Prerequisites

Before creating a Laravel project, download and start Docker Desktop.
https://www.docker.com/products/docker-desktop/

1. Creating a Laravel Project

Run the following command to create a new Laravel project and set up Laravel Sail.

curl -s "https://laravel.build/example-app" | bash
cd example-app

This will create the Laravel project files. The development environment is described in the generated docker-compose.yml file.

Specify services with the with query

If you want to specify the PHP version or use PostgreSQL instead of MySQL, you can specify with=,,... in the command when generating the project.

curl -s "https://laravel.build/example-app?php=81&with=pgsql,redis" | bash

2. Starting Sail

Move to the project directory and start Sail.

./vendor/bin/sail up -d

This command starts the Docker containers and runs the Laravel application.

※Registering an alias

Typing ./vendor/bin/sail an be cumbersome, so save it as an alias sail in your shell's configuration file.

Check the path of the shell you are using with the following command

echo $SHELL

Example: /bin/zsh

Editing the Shell configuration file

• For zsh

The Shell configuration file is ~/.zshrc.
To add an alias, run the following command

curl -s "https://laravel.build/example-app" | bash
cd example-app

• For bash

The shell configuration file is ~/.bash_profile or ~/.bashrc.
To add an alias, run the following command:

curl -s "https://laravel.build/example-app?php=81&with=pgsql,redis" | bash

With the above settings, you can run the sail command in a shortened form.

./vendor/bin/sail up -d

3. Using Sail Commands

You can use Sail to perform various development tasks. Here are some examples.

• Starting the application:

echo $SHELL

• Stopping the application:

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.zshrc
source ~/.zshrc

• Running Artisan commands:

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.bash_profile
source ~/.bash_profile

• Running Composer commands:

sail up -d

• Running npm commands:

sail up -d

4. Changing Services

Even after creating the project, you can change the services by modifying the docker-compose.yml file, which is the Docker configuration file. Here, we will change the PHP version and the database used.

Changing the PHP version

First, check the current PHP version

sail down

Next, modify the development environment information described in the docker-compose.yml file.

sail artisan migrate

Change build context and image to 8.1 .

sail composer install

After modifying docker-compose.yml, stop the application.

sail npm install

Next, rebuild the Docker containers to reflect the changes.

sail php -v
PHP 8.3.12 (cli) (built: Sep 27 2024 03:53:05) (NTS)

Restart the application.

services:
    laravel.test:
        build:
            context: "./vendor/laravel/sail/runtimes/8.3"
            dockerfile: Dockerfile
            args:
                WWWGROUP: "${WWWGROUP}"
        image: "sail-8.3/app"

Check if the PHP version has changed.

services:
    laravel.test:
        build:
            context: "./vendor/laravel/sail/runtimes/8.1"
            dockerfile: Dockerfile
            args:
                WWWGROUP: "${WWWGROUP}"
        image: "sail-8.1/app"

The PHP version has been changed from PHP 8.3 to PHP 8.1.

Changing the database used

Change a project created with MySQL to PostgreSQL.

Run the Sail installation command

sail down

Select pgsql

sail build --no-cache

Check the docker-compose.yml file and confirm that the pgsql entries have been added.

sail up -d

ext, open the .env file in the project directory and confirm that DB_CONNECTION=pgsql and DB_HOST=pgsql are set.
If not, change them manually.

sail php -v
PHP 8.1.30 (cli) (built: Sep 27 2024 04:07:29) (NTS)

After confirming the changes in docker-compose.yml and .env, stop the application.

sail php artisan sail:install

Next, rebuild the Docker containers to reflect the changes.

 ┌ Which services would you like to install? ───────────────────┐
 │   ? mysql                                                  ┃ │
 │ ? ? pgsql                                                  │ │
 │   ? mariadb                                                │ │
 │   ? redis                                                  │ │
 │   ? memcached                                              │ │
 └────────────────────────────────────────────────── 1 selected ┘
  Use the space bar to select options.

Restart the application.

services:
    laravel.test:
...
        depends_on:
            - mysql
            - redis
            - meilisearch
            - mailpit
            - selenium
            - pgsql
...
        pgsql:
            image: 'postgres:17'
            ports:
                - '${FORWARD_DB_PORT:-5432}:5432'
            environment:
                PGPASSWORD: '${DB_PASSWORD:-secret}'
                POSTGRES_DB: '${DB_DATABASE}'
                POSTGRES_USER: '${DB_USERNAME}'
                POSTGRES_PASSWORD: '${DB_PASSWORD:-secret}'
            volumes:
                - 'sail-pgsql:/var/lib/postgresql/data'
                - './vendor/laravel/sail/database/pgsql/create-testing-database.sql:/docker-entrypoint-initdb.d/10-create-testing-database.sql'
            networks:
                - sail
            healthcheck:
                test:
                    - CMD
                    - pg_isready
                    - '-q'
                    - '-d'
                    - '${DB_DATABASE}'
                    - '-U'
                    - '${DB_USERNAME}'
                retries: 3
                timeout: 5s

Run the migration files.

DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=******

Start a shell in Docker and check pgsql

Display the list of currently running Docker containers.

curl -s "https://laravel.build/example-app" | bash
cd example-app

curl -s "https://laravel.build/example-app?php=81&with=pgsql,redis" | bash

Check the container name of the application and start the bash of the application inside Docker.

./vendor/bin/sail up -d

Connect to pgsql.

echo $SHELL

You will be prompted for a password, so enter the DB_PASSWORD specified in the .env file.

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.zshrc
source ~/.zshrc

Check the tables in pgsql

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.bash_profile
source ~/.bash_profile

In this way, you can change from MySQL to PostgreSQL even after creating the project.

Conclusion

Through this article, you will understand how to efficiently set up and manage a development environment using Laravel Sail. By selecting appropriate services and customizing the settings according to the project's requirements, you can achieve a more flexible and powerful development environment.

The above is the detailed content of [Laravel vx Docker] Efficiently Set Up a Laravel App Dev Environment with Laravel Sail. For more information, please follow other related articles on the PHP Chinese website!