Sail trong Laravel 13

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 compose.yaml 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 compose.yaml.

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

Cài đặt và setup

Bạn có thể cài đặt Sail bằng cách sử dụng trình quản lý package 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 compose.yaml của Sail vào thư mục root của ứng dụng của bạn và bạn có thể sửa file .env của bạn bằng các biến môi trường cần thiết để kết nối với các service của Docker:

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

[!WARNING] Nếu bạn đang sử dụng Docker Desktop cho Linux, bạn nên sử dụng Docker context default bằng cách chạy lệnh sau: docker context use default. Ngoài ra, nếu bạn gặp lỗi truy cập file ở trong các container, bạn có thể cần set biến môi trường SUPERVISOR_PHP_USER thành root.

Adding Additional Services

Nếu bạn muốn thêm một service bổ sung vào cài đặt Sail hiện tại của bạn, bạn có thể chạy lệnh Artisan sail:add:

php artisan sail:add

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

Building lại Sail Images

Thỉnh thoảng bạn có thể muốn build lại hoàn toàn các image Sail của bạn để đảm bảo tất cả các package và phần mềm của image đều được cập nhật. Bạn có thể thực hiện điều này bằng cách sử dụng lệnh build:

docker compose down -v

sail build --no-cache

sail up

Cấu hình một shell 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 shell 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='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Để đảm bảo tính năng này luôn sẵn sàng, bạn có thể thêm lệnh này vào file cấu hình shell trong thư mục root của bạn, chẳng hạn như ~/.zshrc hoặc ~/.bashrc, sau đó khởi động lại shell.

Khi shell 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 compose.yaml 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 compose.yaml 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 compose.yaml 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ó sẵn bản cài đặt Composer:

sail composer require laravel/sanctum

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 dev

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 compose.yaml 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, lần đầu tiên container MySQL khởi động, nó sẽ tạo hai cơ sở dữ liệu cho bạn. Cơ sở dữ liệu đầu tiên được đặt tên bằng giá trị của biến môi trường DB_DATABASE và dành cho phát triển local của bạn. Cơ sở dữ liệu thứ hai là cơ sở dữ liệu test chuyên dụng có tên là testing và sẽ đảm bảo rằng các bài test của bạn không can thiệp vào dữ liệu phát triển 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 và thông tin xác thực truy cập tương ứng với các giá trị của biến môi trường DB_USERNAME và DB_PASSWORD. Hoặc, bạn có thể kết nối với tư cách là người dùng root, cũng sử dụng giá trị của biến môi trường DB_PASSWORD làm mật khẩu.

MongoDB

Nếu bạn chọn cài đặt service MongoDB khi cài đặt Sail, file compose.yaml của ứng dụng của bạn có chứa sẵn một mục cho container MongoDB Atlas Local cung cấp cơ sở dữ liệu document MongoDB với các tính năng của Atlas như Search Indexes. Container này sử dụng một Docker volume để dữ liệu có thể được lưu trữ trong cơ sở dữ liệu của bạn được duy trì ngay cả khi dừng và khởi động lại các container của bạn.

Sau khi bạn đã khởi động các container của bạn, bạn có thể kết nối đến instance MongoDB trong ứng dụng của bạn bằng cách set biến môi trường MONGODB_URI trong file .env của ứng dụng thành mongodb://mongodb:27017. Mặc định, xác thực sẽ bị tắt disable, nhưng bạn có thể set các biến môi trường MONGODB_USERNAME và MONGODB_PASSWORD để enable xác thực trước khi khởi động container mongodb. Sau đó, thêm thông tin xác thực vào chuỗi kết nối:

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

Để tích hợp MongoDB liền mạch với ứng dụng của bạn, bạn có thể cài đặt package chính thức do MongoDB cung cấp.

Để kết nối với cơ sở dữ liệu MongoDB của ứng dụng từ máy local của bạn, bạn có thể sử dụng ứng dụng như Compass. Mặc định, cơ sở dữ liệu MongoDB có thể truy cập được tại localhost cổng 27017.

Redis

File compose.yaml 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 instance 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.

Valkey

Nếu bạn chọn cài đặt service Valkey khi cài đặt Sail, file compose.yaml của ứng dụng của bạn sẽ chứa một mục cho Valkey. Container này sử dụng một Docker volume để dữ liệu được lưu trữ trong instance Valkey của bạn và được duy trì ngay cả khi dừng và khởi động lại các container của bạn. Bạn có thể kết nối với container này 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 valkey.

Để kết nối đến cơ sở dữ liệu Valkey của ứng dụng từ máy local của bạn, 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 Valkey 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 compose.yaml 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, nó đã được tích hợp sẵn trong 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.

Typesense

Nếu bạn chọn cài đặt service Typesense khi cài đặt Sail, file compose.yaml của ứng dụng sẽ chứa một mục cho công cụ tìm kiếm mã nguồn mở này và được tích hợp sẵn với Laravel Scout. Sau khi khởi động container, bạn có thể kết nối với phiên bản Typesense trong ứng dụng của bạn bằng cách set các biến môi trường sau:

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

Từ máy local của bạn, bạn có thể truy cập API của Typesense qua http://localhost:8108.

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 RustFS khi cài đặt Sail. RustFS 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 RustFS trong khi cài đặt Sail, phần cấu hình RustFS sẽ được thêm vào file compose.yaml 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ư RustFS 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 RustFS, cấu hình biến môi trường filesystem của bạn phải được định nghĩa như sau:

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://rustfs: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 Pest / 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

Mặc định, Sail sẽ tạo một cơ sở dữ liệu testing chuyên dụng để các bài test của bạn không can thiệp vào trạng thái hiện tại của cơ sở dữ liệu. Trong cài đặt mặc định của Laravel, Sail cũng sẽ cấu hình file phpunit.xml của bạn để sử dụng cơ sở dữ liệu này khi thực hiện các bài test của bạn:

<env name="DB_DATABASE" value="testing"/>

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 compose.yaml của ứng dụng của bạn:

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Tiếp theo, hãy đảm bảo là service laravel.test trong file compose.yaml 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 selenium/standalone-chromium:

selenium:
    image: 'selenium/standalone-chromium'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Previewing Emails

File compose.yaml mặc định của Laravel Sail có chứa một mục cho service Mailpit. Mailpit 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 Mailpit là mailpit và trên cổng 1025:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Khi Sail đang chạy, bạn có thể truy cập vào giao diện web Mailpit 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.4, 8.3, 8.2, 8.1, hoặc PHP 8.0. Phiên bản PHP mặc định được Sail sử dụng hiện tại là PHP 8.4. Để 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 compose.yaml của ứng dụng:

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

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

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

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

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

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

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 compose.yaml trong ứng dụng của bạn:

image: sail-8.2/app

Sau khi cập nhật file compose.yaml 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 24. Để 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 compose.yaml của ứng dụng của bạn:

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

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

sail build --no-cache

sail up

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 dùng phương thức middleware trustProxies trong file bootstrap/app.php của ứng dụng của bạn. 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:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

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

[!NOTE] 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, đảm bảo bạn đã export cấu hình Sail của bạn. Sau đó, thêm các biến sau vào file .env của ứng dụng để cấu hình Xdebug:

SAIL_XDEBUG_MODE=develop,debug,coverage

Tiếp theo, đảm bảo rằng file php.ini đã export của bạn có chứa cấu hình sau để Xdebug được kích hoạt ở các chế độ đã chỉ định:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Sau khi bạn sửa file php.ini, hãy nhớ build lại Docker images của bạn để các thay đổi của bạn cho file php.ini có hiệu lực ngay lập tức:

sail build --no-cache

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 và đang sử dụng Docker 20.10+, thì host.docker.internal sẽ có sẵn và không cần bạn phải cấu hình.

Đối với các phiên bản Docker cũ hơn 20.10, host.docker.internal không được hỗ trợ trên Linux và bạn sẽ cần tự định nghĩa IP của host. Để làm điều này, hãy cấu hình một IP tĩnh cho container của bạn bằng cách định nghĩa một network tùy chỉnh trong file compose.yaml của bạn:

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16

services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

Khi bạn đã set địa chỉ static IP, 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=172.20.0.2"

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.

[!WARNING] 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.

Tùy 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 compose.yaml 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

Prologue

Getting Started

Architecture Concepts

The Basics

Digging Deeper

Security

Database

Eloquent ORM

AI

Testing

Packages