Giới thiệu

Laravel Sail là một giao diện command-line nhẹ để tương tác với môi trường phát triển Docker của Laravel. Sail cung cấp điểm khởi đầu tuyệt vời để xây dựng ứng dụng Laravel bằng PHP, MySQL và Redis mà không yêu cầu bất cứ kinh nghiệm Docker nào.

Về cơ bản, Sail là file docker-compose.yml và script sail được lưu ở thư mục root của project của bạn. Script sail cung cấp một CLI với các phương thức thuận tiện để tương tác với các Docker container được định nghĩa bởi file docker-compose.yml.

Laravel Sail được hỗ trợ trên macOS, Linux và Windows (thông qua WSL2).

Cài đặt và setup

Laravel Sail được cài đặt tự động cùng với tất cả các ứng dụng Laravel mới nên bạn có thể bắt đầu sử dụng nó ngay lập tức. Để tìm hiểu cách tạo ra một ứng dụng Laravel mới, vui lòng tham khảo tài liệu cài đặt của Laravel cho hệ điều hành của bạn. Trong quá trình cài đặt, bạn sẽ được yêu cầu chọn những service được Sail hỗ trợ mà ứng dụng của bạn sẽ tương tác cùng.

Cài đặt Sail vào trong application hiện tại

Nếu bạn quan tâm đến việc sử dụng Sail với ứng dụng Laravel hiện có, bạn có thể chỉ cần cài đặt Sail bằng Composer package manager. Tất nhiên, các bước này giả định rằng môi trường phát triển local hiện tại của bạn cho phép bạn cài đặt các library của Composer:

composer require laravel/sail --dev

Sau khi Sail đã được cài đặt, bạn có thể chạy lệnh Artisan sail:install. Lệnh này sẽ export file docker-compose.yml của Sail vào thư mục root của ứng dụng của bạn:

php artisan sail:install

Cuối cùng, bạn có thể bắt đầu Sail. Để tiếp tục tìm hiểu cách sử dụng Sail, vui lòng tiếp tục đọc phần còn lại của tài liệu này:

./vendor/bin/sail up

Using Devcontainers

Nếu muốn phát triển trong một Devcontainer, bạn có thể cung cấp tùy chọn --devcontainer cho lệnh sail:install. Tùy chọn --devcontainer sẽ hướng dẫn lệnh sail:install sẽ export file .devcontainer/devcontainer.json mặc định vào thư mục root của ứng dụng của bạn:

php artisan sail:install --devcontainer

Cấu hình một bash alias

Mặc định, các lệnh Sail được gọi bằng cách sử dụng tập lệnh script vendor/bin/sail có trong tất cả các ứng dụng Laravel mới:

./vendor/bin/sail up

Tuy nhiên, thay vì gõ liên tục vendor/bin/sail để chạy các lệnh Sail, bạn có thể muốn cấu hình một Bash alias cho phép bạn chạy các lệnh của Sail một cách dễ dàng hơn:

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

Khi Bash alias đã được cấu hình xong, bạn có thể chạy các lệnh Sail bằng cách chỉ cần gõ sail. Các ví dụ còn lại của tài liệu này sẽ giả sử là bạn đã cấu hình alias này:

sail up

Starting và Stopping Sail

File docker-compose.yml của Laravel Sail định nghĩa nhiều container Docker hoạt động cùng nhau để giúp bạn xây dựng các ứng dụng Laravel. Mỗi container này là một mục trong cấu hình services của file docker-compose.yml của bạn. Container laravel.test là container ứng dụng chính sẽ chạy ứng dụng của bạn.

Trước khi khởi động Sail, bạn phải đảm bảo rằng không có máy chủ web hoặc cơ sở dữ liệu nào khác đang chạy trên máy tính local của bạn. Để khởi động tất cả các container Docker được định nghĩa trong file docker-compose.yml của ứng dụng, bạn nên chạy lệnh up:

sail up

Để khởi động tất cả các container Docker ở background, bạn có thể khởi động Sail ở chế độ "detached":

sail up -d

Khi container của ứng dụng đã được khởi động xong, bạn có thể truy cập vào dự án trong trình duyệt web của bạn tại: http://localhost.

Để dừng tất cả các container, bạn chỉ cần nhấn Control + C để dừng quá trình chạy của container. Hoặc, nếu các container đang chạy ở background, bạn có thể sử dụng lệnh stop:

sail stop

Chạy commands

Khi sử dụng Laravel Sail, ứng dụng của bạn đang được chạy trong container Docker và được cách ly hoàn toàn khỏi máy tính local của bạn. Tuy nhiên, Sail cũng cung cấp một cách thuận tiện để chạy các lệnh khác nhau đối với ứng dụng của bạn, chẳng hạn như lệnh PHP, lệnh Artisan, lệnh Composer và lệnh Node/NPM.

Khi đọc tài liệu Laravel, bạn sẽ thường thấy các lệnh chạy thẳng đến các lệnh Composer, Artisan và Node/NPM mà không chạy đến Sail. Những ví dụ đó giả định là những công cụ này được cài đặt trên máy tính local của bạn. Nếu bạn đang sử dụng Sail cho môi trường phát triển Laravel local của bạn, bạn nên chạy các lệnh đó bằng Sail:

# Running Artisan commands locally...
php artisan queue:work

# Running Artisan commands within Laravel Sail...
sail artisan queue:work

Chạy PHP Commands

Các lệnh PHP có thể được chạy bằng lệnh php. Tất nhiên, các lệnh này sẽ chạy bằng phiên bản PHP được cấu hình cho ứng dụng của bạn. Để tìm hiểu thêm về các phiên bản PHP có sẵn cho Laravel Sail, hãy tham khảo tài liệu về phiên bản PHP:

sail php --version

sail php script.php

Chạy Composer Commands

Các lệnh của Composer có thể được chạy bằng lệnh composer. Container ứng dụng của Laravel Sail đã có bản cài đặt Composer version 2.x:

sail composer require laravel/sanctum

Installing Composer Dependencies For Existing Applications

Nếu bạn đang phát triển một ứng dụng với một nhóm của bạn, bạn có thể không phải là người đầu tiên tạo ra ứng dụng Laravel. Do đó, không có library Composer nào của ứng dụng, kể cả Sail, sẽ được cài đặt sau khi bạn clone repository của ứng dụng vào máy tính local của bạn.

Bạn có thể cài đặt các phần library của ứng dụng bằng cách điều hướng đến thư mục của ứng dụng và thực hiện lệnh sau. Lệnh này sử dụng một container Docker nhỏ chứa PHP và Composer để cài đặt các phần library của ứng dụng:

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v $(pwd):/var/www/html \
    -w /var/www/html \
    laravelsail/php81-composer:latest \
    composer install --ignore-platform-reqs

Khi sử dụng image laravelsail/phpXX-composer, bạn nên sử dụng cùng một phiên bản PHP mà bạn đang định sử dụng cho ứng dụng của bạn (74, 80 hoặc 81).

Chạy Artisan Commands

Các lệnh Laravel Artisan có thể được chạy bằng lệnh artisan:

sail artisan queue:work

Chạy Node và NPM Commands

Các lệnh Node có thể được chạy bằng lệnh node trong khi các lệnh NPM có thể được chạy bằng lệnh npm:

sail node --version

sail npm run prod

Nếu muốn, bạn có thể sử dụng Yarn thay vì NPM:

sail yarn

Tương tác với Databases

MySQL

Như bạn có thể nhận thấy, file docker-compose.yml của ứng dụng của bạn chứa một mục cho container MySQL. Container này sử dụng một Docker volume để lưu trữ dữ liệu trong cơ sở dữ liệu của bạn và nó sẽ được duy trì ngay cả khi dừng hoặc khởi động lại container. Ngoài ra, khi container MySQL khởi động, nó sẽ đảm bảo tồn tại cơ sở dữ liệu có tên khớp với giá trị của biến môi trường DB_DATABASE của bạn.

Sau khi khởi động container, bạn có thể kết nối với instance MySQL trong ứng dụng của bạn bằng cách set biến môi trường DB_HOST trong file .env của ứng dụng thành mysql.

Để kết nối đến cơ sở dữ liệu MySQL của ứng dụng từ máy local, bạn có thể sử dụng ứng dụng quản lý cơ sở dữ liệu như TablePlus. Mặc định, cơ sở dữ liệu MySQL có thể truy cập được tại localhost cổng 3306.

Redis

File docker-compose.yml của ứng dụng của bạn cũng chứa một mục cho container Redis. Container này sử dụng một Docker volume để lưu trữ dữ liệu Redis của bạn và nó sẽ được duy trì ngay cả khi dừng hoặc khởi động lại container của bạn. Sau khi khởi động container, bạn có thể kết nối với instance Redis trong ứng dụng của bạn bằng cách set biến môi trường REDIS_HOST trong file .env của ứng dụng thành redis.

Để kết nối đến cơ sở dữ liệu Redis của ứng dụng từ máy local, bạn có thể sử dụng ứng dụng quản lý cơ sở dữ liệu như TablePlus. Mặc định, cơ sở dữ liệu Redis có thể truy cập được tại localhost cổng 6379.

MeiliSearch

Nếu bạn chọn cài đặt service MeiliSearch khi cài đặt Sail, file docker-compose.yml của ứng dụng của bạn sẽ chứa một mục cho công cụ tìm kiếm mạnh mẽ này tương thích với Laravel Scout. Sau khi khởi động container, bạn có thể kết nối đến instance MeiliSearch trong ứng dụng của bạn bằng cách set biến môi trường MEILISEARCH_HOST thành http://meilisearch:7700.

Từ máy local của bạn, bạn có thể truy cập vào trang admin dựa trên web của MeiliSearch bằng cách vào http://localhost:7700 trong trình duyệt web của bạn.

File Storage

Nếu bạn dự định sử dụng Amazon S3 để lưu trữ file trong khi chạy ứng dụng của bạn trong môi trường production, bạn có thể muốn cài đặt service MinIO khi cài đặt Sail. MinIO cung cấp API tương thích với S3 mà bạn có thể sử dụng để phát triển local bằng driver storage file s3 của Laravel mà không cần tạo bucket lưu trữ "thử nghiệm" trong môi trường S3 production của bạn. Nếu bạn muốn chọn cài đặt MinIO trong khi cài đặt Sail, phần cấu hình MinIO sẽ được thêm vào file docker-compose.yml của ứng dụng của bạn.

Mặc định, file cấu hình filesystems của ứng dụng của bạn đã chứa cấu hình disk cho disk s3. Ngoài việc sử dụng disk này để tương tác với Amazon S3, bạn có thể sử dụng disk này để tương tác với bất kỳ dịch vụ lưu trữ file nào mà tương thích với S3 chẳng hạn như MinIO bằng cách sửa các biến môi trường liên quan đến kiểm soát cấu hình của nó. Ví dụ: khi sử dụng MinIO, cấu hình biến môi trường filesystem của bạn phải được định nghĩa như sau:

FILESYSTEM_DRIVER=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Running Tests

Laravel mặc định cung cấp khả năng testing tuyệt vời và bạn có thể sử dụng lệnh test của Sail để chạy các bài kiểm tra tính năng hoặc unit test cho ứng dụng của bạn. Bất kỳ tùy chọn CLI nào mà được PHPUnit chấp nhận cũng có thể được truyền cho lệnh test:

sail test

sail test --group orders

Lệnh Sail test tương đương với việc chạy lệnh Artisan test:

sail artisan test

Laravel Dusk

Laravel Dusk cung cấp API testing và automation browser dễ sử dụng và mang tính hàm ý. Nhờ Sail, bạn có thể chạy các bài test này mà không cần cài đặt Selenium hoặc các công cụ khác trên máy tính local của bạn. Để bắt đầu, hãy uncomment service Selenium trong file docker-compose.yml của ứng dụng của bạn:

selenium:
    image: 'selenium/standalone-chrome'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Tiếp theo, hãy đảm bảo là service laravel.test trong file docker-compose.yml trong ứng dụng của bạn có một mục depends_on cho selenium:

depends_on:
    - mysql
    - redis
    - selenium

Cuối cùng, bạn có thể chạy bài test Dusk bằng cách khởi động Sail và chạy lệnh dusk:

sail dusk

Selenium On Apple Silicon

Nếu máy local của bạn dùng chip Apple Silicon, service selenium của bạn phải được sử dụng image seleniarm/standalone-chromium:

selenium:
    image: 'seleniarm/standalone-chromium'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Previewing Emails

File docker-compose.yml mặc định của Laravel Sail có chứa một mục cho service MailHog. MailHog sẽ chặn các email được gửi đi bởi ứng dụng của bạn trong quá trình phát triển local và cung cấp giao diện web thuận tiện để bạn có thể xem các email đã được gửi trong trình duyệt của bạn. Khi sử dụng Sail, máy chủ mặc định của MailHog là mailhog và trên cổng 1025:

MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Khi Sail đang chạy, bạn có thể truy cập vào giao diện web MailHog tại: http://localhost:8025

Container CLI

Thỉnh thoảng bạn có thể muốn bắt đầu một Bash session trong container ứng dụng của bạn. Bạn có thể sử dụng lệnh shell để kết nối với container ứng dụng của bạn, cho phép bạn kiểm tra các file của nó và các service đã cài đặt cũng như chạy các lệnh shell tùy ý trong container:

sail shell

sail root-shell

Để bắt đầu một session Laravel Tinker mới, bạn có thể chạy lệnh tinker:

sail tinker

PHP Versions

Sail hiện hỗ trợ chạy ứng dụng của bạn thông qua PHP 8.1, PHP 8.0 hoặc PHP 7.4. Phiên bản PHP mặc định được Sail sử dụng hiện tại là PHP 8.1. Để thay đổi phiên bản PHP được sử dụng để chạy ứng dụng của bạn, bạn nên cập nhật định nghĩa build của container laravel.test trong file docker-compose.yml của ứng dụng:

# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1

# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

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

Ngoài ra, bạn có thể muốn cập nhật tên image của bạn để phản ánh phiên bản PHP đang được ứng dụng của bạn sử dụng. Tùy chọn này cũng được định nghĩa trong file docker-compose.yml trong ứng dụng của bạn:

image: sail-8.1/app

Sau khi cập nhật file docker-compose.yml của ứng dụng, bạn nên build lại image container của bạn:

sail build --no-cache

sail up

Node Versions

Mặc định, Sail cài đặt Node 16. Để thay đổi phiên bản Node được cài đặt khi build image của bạn, bạn có thể cập nhật định nghĩa build.args của service laravel.test trong file docker-compose.yml của ứng dụng của bạn:

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '14'

Sau khi cập nhật file docker-compose.yml của ứng dụng, bạn nên build lại image container của bạn:

sail build --no-cache

sail up

Sharing Your Site

Thỉnh thoảng, bạn có thể cần share trang web của bạn để cho người khác có thể xem qua trang web của bạn hoặc để test khả năng tích hợp webhook với ứng dụng của bạn. Để share trang web của bạn, bạn có thể sử dụng lệnh share. Sau khi thực hiện lệnh này, bạn sẽ được nhận được một URL laravel-sail.site ngẫu nhiên mà bạn có thể sử dụng để truy cập vào ứng dụng của bạn:

sail share

Khi chia sẻ trang web của bạn thông qua lệnh share, bạn nên cấu hình các proxy đáng tin cậy của ứng dụng của bạn trong middleware TrustProxies. Nếu không, các helper tạo URL như url và route sẽ không thể xác định HTTP host chính xác sẽ được sử dụng trong quá trình tạo URL:

/**
 * The trusted proxies for this application.
 *
 * @var array|string|null
 */
protected $proxies = '*';

Nếu bạn muốn chọn subdomain cho trang web được chia sẻ của bạn, bạn có thể cung cấp tùy chọn subdomain khi chạy lệnh share:

sail share --subdomain=my-sail-site

{tip} Lệnh share được hỗ trợ bởi Expose, một service nguồn mở của BeyondCode.

Debugging With Xdebug

Cấu hình Docker của Laravel Sail có hỗ trợ cho Xdebug, một trình debug phổ biến và mạnh mẽ cho PHP. Để bật Xdebug, bạn cần thêm một vài biến vào file .env của ứng dụng để cấu hình Xdebug. Để bật Xdebug, bạn phải set (các) chế độ thích hợp trước khi khởi động Sail:

SAIL_XDEBUG_MODE=develop,debug

Linux Host IP Configuration

Bên trong, biến môi trường XDEBUG_CONFIG sẽ được định nghĩa là client_host=host.docker.internal để Xdebug sẽ được cấu hình đúng cho Mac và Windows (WSL2). Nếu máy local của bạn đang chạy Linux, bạn sẽ cần định nghĩa thủ công biến môi trường này.

Trước tiên, bạn nên xác định chính xác địa chỉ IP máy chủ để thêm vào biến môi trường bằng cách chạy lệnh sau. Thông thường, <container-name> phải là tên của container chạy ứng dụng của bạn và thường kết thúc bằng _laravel.test_1:

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

Khi bạn đã có được chính xác địa chỉ IP máy chủ, bạn nên định nghĩa biến SAIL_XDEBUG_CONFIG trong file .env của ứng dụng của bạn:

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

Xdebug CLI Usage

Lệnh sail debug có thể được sử dụng để bắt đầu session debug khi chạy lệnh Artisan:

# Run an Artisan command without Xdebug...
sail artisan migrate

# Run an Artisan command with Xdebug...
sail debug migrate

Xdebug Browser Usage

Để debug ứng dụng trong khi tương tác với ứng dụng đó qua trình duyệt web, bạn hãy làm theo hướng dẫn do Xdebug cung cấp để bắt đầu session Xdebug từ trình duyệt web.

Nếu bạn đang sử dụng PhpStorm, thì vui lòng xem lại tài liệu của JetBrain về debug không cần cấu hình.

{note} Laravel Sail dựa vào artisan Serve để chạy ứng dụng của bạn. Lệnh artisan Serve chỉ chấp nhận các biến XDEBUG_CONFIG và XDEBUG_MODE kể từ phiên bản Laravel 8.53.0. Các phiên bản cũ hơn của Laravel (8.52.0 trở xuống) sẽ không hỗ trợ các biến này và sẽ không chấp nhận khi kết nối debug.

Tuỳ chỉnh

Vì Sail chỉ là Docker nên bạn có thể tự do tùy chỉnh hầu hết mọi thứ về nó. Để export Dockerfiles của Sail, bạn có thể chạy lệnh sail:publish:

sail artisan sail:publish

Sau khi chạy lệnh này, Dockerfiles và các file cấu hình khác được Laravel Sail sử dụng sẽ được lưu vào trong thư mục docker trong thư mục root của ứng dụng của bạn. Sau khi tùy chỉnh cài đặt của Sail, bạn có thể muốn thay đổi tên image cho container ứng dụng trong file docker-compose.yml của ứng dụng. Sau khi làm như vậy, hãy build lại container ứng dụng của bạn bằng lệnh build. Gán một tên duy nhất cho image ứng dụng sẽ đặc biệt quan trọng nếu bạn đang sử dụng Sail để phát triển nhiều ứng dụng Laravel trên một máy local:

sail build --no-cache