Cấu hình (Configuration)

Giới thiệu (Introduction)

Tất cả file cấu hình của Laravel framework được lưu trong thư mục config. Mỗi tùy chọn đều được ghi chú (documented), vì vậy hãy thoải mái xem qua các file và làm quen với các tùy chọn.

Các file cấu hình cho phép bạn thiết lập thông tin kết nối database, thông tin mail server, cũng như nhiều giá trị cấu hình cốt lõi khác như URL ứng dụng và encryption key.

Lệnh about

Laravel có thể hiển thị tổng quan về cấu hình, drivers và môi trường ứng dụng thông qua lệnh Artisan about:

php artisan about

Nếu bạn chỉ quan tâm đến một phần cụ thể, bạn có thể lọc bằng tùy chọn --only:

php artisan about --only=environment

Hoặc, để xem chi tiết giá trị của một file cấu hình cụ thể, sử dụng lệnh config:show:

php artisan config:show database

Cấu hình môi trường (Environment Configuration)

Thường rất hữu ích khi có các giá trị cấu hình khác nhau tùy thuộc vào môi trường mà ứng dụng đang chạy. Ví dụ, bạn có thể muốn sử dụng cache driver khác ở môi trường local so với trên server production.

Để thực hiện điều này dễ dàng, Laravel sử dụng thư viện PHP DotEnv. Trong bản cài đặt Laravel mới, thư mục gốc ứng dụng sẽ chứa file .env.example định nghĩa nhiều biến môi trường phổ biến. Trong quá trình cài đặt, file này sẽ tự động được sao chép thành .env.

File .env mặc định của Laravel chứa một số giá trị cấu hình phổ biến có thể khác nhau tùy thuộc vào việc ứng dụng chạy cục bộ hay trên server production. Các giá trị này sau đó được đọc bởi các file cấu hình trong thư mục config sử dụng hàm env của Laravel.

Nếu phát triển nhóm, bạn nên tiếp tục duy trì và cập nhật file .env.example. Bằng cách đặt các giá trị placeholder trong file ví dụ, các developer khác trong nhóm có thể thấy rõ những biến môi trường nào cần thiết để chạy ứng dụng.

CẢNH BÁO

Bất kỳ biến nào trong file .env đều có thể bị ghi đè bởi biến môi trường bên ngoài như biến môi trường cấp server hoặc cấp hệ thống.

Bảo mật file môi trường (Environment File Security)

File .env không nên được commit vào source control, vì mỗi developer/server có thể cần cấu hình môi trường khác nhau. Hơn nữa, đây là rủi ro bảo mật nếu kẻ xâm nhập truy cập được repository, vì thông tin nhạy cảm sẽ bị lộ.

Tuy nhiên, bạn có thể mã hóa file môi trường bằng tính năng encryption môi trường tích hợp sẵn của Laravel. File môi trường đã mã hóa có thể được đưa vào source control an toàn.

File môi trường bổ sung (Additional Environment Files)

Trước khi tải biến môi trường, Laravel kiểm tra xem biến môi trường APP_ENV đã được cung cấp từ bên ngoài hay tham số CLI --env đã được chỉ định chưa. Nếu có, Laravel sẽ cố tải file .env.[APP_ENV] nếu tồn tại. Nếu không, file .env mặc định sẽ được tải.

Kiểu biến môi trường (Environment Variable Types)

Tất cả biến trong file .env thường được parse dưới dạng string, do đó một số giá trị dành riêng đã được tạo để cho phép bạn trả về nhiều kiểu dữ liệu hơn từ hàm env().

Nếu cần định nghĩa biến môi trường có giá trị chứa khoảng trắng, hãy đặt giá trị trong dấu ngoặc kép:

APP_NAME="My Application"

Lấy cấu hình môi trường (Retrieving Environment Configuration)

Tất cả biến trong file .env sẽ được tải vào biến super-global $_ENV của PHP khi ứng dụng nhận request. Tuy nhiên, bạn có thể sử dụng hàm env để lấy giá trị trong các file cấu hình. Thực tế, nếu xem các file cấu hình Laravel, bạn sẽ thấy nhiều tùy chọn đã sử dụng hàm này:

'debug' => (bool) env('APP_DEBUG', false),

Giá trị thứ hai truyền vào hàm env là "giá trị mặc định". Giá trị này sẽ được trả về nếu không tồn tại biến môi trường cho key đã cho.

Xác định môi trường hiện tại (Determining the Current Environment)

Môi trường ứng dụng hiện tại được xác định thông qua biến APP_ENV trong file .env. Bạn có thể truy cập giá trị này qua method environment trên facade App:

use Illuminate\Support\Facades\App;

$environment = App::environment();

Bạn cũng có thể truyền tham số vào method environment để kiểm tra xem môi trường có khớp với giá trị cho trước không. Method sẽ trả về true nếu môi trường khớp với bất kỳ giá trị nào:

if (App::environment('local')) {
    // Môi trường là local
}

if (App::environment(['local', 'staging'])) {
    // Môi trường là local HOẶC staging...
}

GỢI Ý

Việc phát hiện môi trường ứng dụng hiện tại có thể bị ghi đè bằng cách định nghĩa biến môi trường APP_ENV ở cấp server.

Mã hóa file môi trường (Encrypting Environment Files)

File môi trường chưa mã hóa không bao giờ nên được lưu trong source control. Tuy nhiên, Laravel cho phép bạn mã hóa file môi trường để có thể thêm vào source control an toàn cùng phần còn lại của ứng dụng.

Mã hóa (Encryption)

Để mã hóa file môi trường, sử dụng lệnh env:encrypt:

php artisan env:encrypt

Chạy lệnh env:encrypt sẽ mã hóa file .env và đặt nội dung đã mã hóa trong file .env.encrypted. Key giải mã (decryption key) sẽ hiển thị trong output của lệnh và nên được lưu trữ trong trình quản lý mật khẩu an toàn. Nếu muốn cung cấp key riêng, sử dụng tùy chọn --key:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Độ dài key phải khớp với yêu cầu của thuật toán mã hóa. Mặc định, Laravel sử dụng cipher AES-256-CBC yêu cầu key 32 ký tự. Bạn có thể sử dụng bất kỳ cipher nào được Laravel encrypter hỗ trợ bằng cách truyền tùy chọn --cipher.

Nếu ứng dụng có nhiều file môi trường, như .env và .env.staging, bạn có thể chỉ định file cần mã hóa bằng tùy chọn --env:

php artisan env:encrypt --env=staging

Tên biến có thể đọc (Readable Variable Names)

Khi mã hóa file môi trường, bạn có thể sử dụng tùy chọn --readable để giữ tên biến có thể nhìn thấy trong khi mã hóa giá trị:

php artisan env:encrypt --readable

Lệnh này sẽ tạo file được mã hóa với định dạng sau:

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

Sử dụng định dạng readable cho phép bạn xem biến môi trường nào tồn tại mà không lộ dữ liệu nhạy cảm. Nó cũng giúp review pull requests dễ hơn vì bạn có thể thấy biến nào được thêm, xóa hoặc đổi tên mà không cần giải mã file.

Giải mã (Decryption)

Để giải mã file môi trường, sử dụng lệnh env:decrypt. Lệnh này yêu cầu decryption key, mà Laravel sẽ lấy từ biến môi trường LARAVEL_ENV_ENCRYPTION_KEY:

php artisan env:decrypt

Hoặc cung cấp key trực tiếp qua tùy chọn --key:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Khi lệnh env:decrypt được gọi, Laravel sẽ giải mã nội dung file .env.encrypted và đặt nội dung đã giải mã vào file .env.

Tùy chọn --cipher có thể được truyền để sử dụng cipher tùy chỉnh:

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

Để ghi đè file môi trường hiện có, sử dụng tùy chọn --force:

php artisan env:decrypt --force

Truy cập giá trị cấu hình (Accessing Configuration Values)

Bạn có thể dễ dàng truy cập giá trị cấu hình bằng facade Config hoặc hàm global config từ bất kỳ đâu trong ứng dụng. Giá trị cấu hình được truy cập bằng cú pháp "dấu chấm" (dot syntax), bao gồm tên file và tùy chọn cần truy cập. Giá trị mặc định cũng có thể được chỉ định:

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

// Lấy giá trị mặc định nếu cấu hình không tồn tại...
$value = config('app.timezone', 'Asia/Seoul');

Để thiết lập giá trị cấu hình trong runtime, gọi method set của facade Config hoặc truyền mảng vào hàm config:

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

Để hỗ trợ phân tích tĩnh (static analysis), facade Config cũng cung cấp các method truy xuất cấu hình có kiểu dữ liệu. Nếu giá trị cấu hình không khớp kiểu mong đợi, exception sẽ được ném ra:

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

Cache cấu hình (Configuration Caching)

Để tăng tốc ứng dụng, bạn nên cache tất cả file cấu hình thành một file duy nhất bằng lệnh Artisan config:cache. Lệnh này gộp tất cả tùy chọn cấu hình thành một file duy nhất có thể được framework tải nhanh chóng.

Bạn nên chạy lệnh php artisan config:cache như một phần của quy trình triển khai production. Lệnh này không nên chạy trong quá trình phát triển local vì các tùy chọn cấu hình sẽ thường xuyên thay đổi.

QUAN TRỌNG

Sau khi cấu hình đã được cache, file .env sẽ không được framework tải trong các requests hoặc lệnh Artisan; do đó, hàm env sẽ chỉ trả về các biến môi trường bên ngoài, cấp hệ thống.

Vì lý do này, bạn nên đảm bảo chỉ gọi hàm env từ bên trong các file cấu hình (config) của ứng dụng.

Lệnh config:clear có thể được sử dụng để xóa cấu hình đã cache:

php artisan config:clear

Xuất bản cấu hình (Configuration Publishing)

Hầu hết file cấu hình của Laravel đã được xuất bản trong thư mục config ứng dụng; tuy nhiên, một số file cấu hình như cors.php và view.php không được xuất bản mặc định, vì hầu hết ứng dụng không cần sửa đổi chúng.

Bạn có thể sử dụng lệnh Artisan config:publish để xuất bản file cấu hình:

php artisan config:publish

php artisan config:publish --all

Chế độ Debug (Debug Mode)

Tùy chọn debug trong file cấu hình config/app.php quyết định lượng thông tin lỗi được hiển thị cho người dùng. Mặc định, tùy chọn này được thiết lập theo giá trị biến môi trường APP_DEBUG trong file .env.

CẢNH BÁO

Trong phát triển local, bạn nên đặt biến môi trường APP_DEBUG thành true. Trong môi trường production, giá trị này phải luôn là false. Nếu biến được đặt thành true trên production, bạn có nguy cơ lộ các giá trị cấu hình nhạy cảm cho người dùng cuối.

Chế độ bảo trì (Maintenance Mode)

Khi ứng dụng ở chế độ bảo trì (maintenance mode), một view tùy chỉnh sẽ được hiển thị cho tất cả requests. Điều này giúp dễ dàng "vô hiệu hóa" ứng dụng khi đang cập nhật hoặc bảo trì. Kiểm tra maintenance mode được bao gồm trong middleware stack mặc định. Nếu ứng dụng đang ở chế độ bảo trì, một HttpException với mã trạng thái 503 sẽ được ném ra.

Để bật chế độ bảo trì, thực thi lệnh Artisan down:

php artisan down

Nếu muốn HTTP header Refresh được gửi cùng tất cả response trong chế độ bảo trì, sử dụng tùy chọn refresh. Header Refresh sẽ chỉ thị trình duyệt tự động làm mới trang sau số giây chỉ định:

php artisan down --refresh=15

Bạn cũng có thể cung cấp tùy chọn retry, sẽ được đặt làm giá trị HTTP header Retry-After:

php artisan down --retry=60

Bỏ qua chế độ bảo trì (Bypassing Maintenance Mode)

Để cho phép bỏ qua chế độ bảo trì bằng secret token, sử dụng tùy chọn secret:

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Sau khi đặt ứng dụng vào chế độ bảo trì, bạn có thể truy cập URL ứng dụng khớp với token này và Laravel sẽ cấp cookie bypass cho trình duyệt:

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Nếu muốn Laravel tự tạo secret token, sử dụng tùy chọn with-secret:

php artisan down --with-secret

GỢI Ý

Secret token cho chế độ bảo trì nên chỉ chứa ký tự chữ-số và dấu gạch ngang. Tránh sử dụng ký tự có ý nghĩa đặc biệt trong URL như ? hoặc &.

Chế độ bảo trì trên nhiều server

Mặc định, Laravel xác định ứng dụng có đang ở chế độ bảo trì hay không bằng hệ thống dựa trên file. Điều này có nghĩa lệnh php artisan down phải được thực thi trên mỗi server lưu trữ ứng dụng.

Thay vào đó, Laravel cung cấp phương pháp dựa trên cache để xử lý chế độ bảo trì. Phương pháp này chỉ cần chạy lệnh php artisan down trên một server. Để sử dụng cách tiếp cận này, cập nhật biến maintenance mode trong file .env:

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Pre-render view bảo trì

Nếu sử dụng lệnh php artisan down trong quá trình triển khai, người dùng vẫn có thể gặp lỗi nếu truy cập ứng dụng khi Composer dependencies hoặc các thành phần hạ tầng khác đang cập nhật. Điều này xảy ra vì một phần đáng kể của Laravel framework phải khởi động để xác định ứng dụng đang ở chế độ bảo trì.

Vì lý do này, Laravel cho phép bạn pre-render view bảo trì sẽ được trả về ngay từ đầu chu kỳ request, trước khi bất kỳ dependency nào được tải:

php artisan down --render="errors::503"

Chuyển hướng requests trong chế độ bảo trì

Trong chế độ bảo trì, bạn có thể chỉ thị Laravel chuyển hướng tất cả requests đến URL cụ thể bằng tùy chọn redirect:

php artisan down --redirect=/

Tắt chế độ bảo trì

Để tắt chế độ bảo trì, sử dụng lệnh up:

php artisan up

GỢI Ý

Bạn có thể tùy chỉnh template mặc định cho chế độ bảo trì bằng cách tạo template tại resources/views/errors/503.blade.php.

Chế độ bảo trì và Queues

Khi ứng dụng ở chế độ bảo trì, không có queued jobs nào được xử lý. Các jobs sẽ tiếp tục được xử lý bình thường khi ứng dụng thoát khỏi chế độ bảo trì.

Các phương án thay thế cho chế độ bảo trì

Vì chế độ bảo trì yêu cầu ứng dụng có vài giây downtime, hãy xem xét chạy ứng dụng trên nền tảng được quản lý hoàn toàn như Laravel Cloud để triển khai zero-downtime với Laravel.