Giới thiệu

[!NOTE] Bạn đang tìm một cách dễ dàng hơn để phát triển ứng dụng Laravel trên macOS hoặc Windows? Hãy xem Laravel Herd. Herd bao gồm mọi thứ bạn cần để bắt đầu phát triển Laravel, bao gồm cả Valet, PHP và Composer.

Laravel Valet là một môi trường phát triển cho người dùng macOS. Laravel Valet sẽ cấu hình máy Mac của bạn chạy Nginx ở background mỗi khi máy khởi động. Sau đó, dùng DnsMasq, Valet sẽ chuyển tất cả các request đến domain *.test vào site mà bạn đã cài đặt ở local.

Cụ thể là, Valet là một môi trường phát triển Laravel nhanh chóng chỉ dùng có khoảng 7 MB RAM. Valet không phải là một sự thay thế hoàn toàn cho Sail hoặc Homestead, nhưng cung cấp một sự thay thế tuyệt vời nếu bạn muốn những điều cơ bản, linh hoạt, thích tốc độ cực cao hoặc đang làm việc trên một máy có dung lượng RAM thấp.

Mặc định, Valet hỗ trợ những phần sau, nhưng không giới hạn:

Tuy nhiên, bạn có thể mở rộng Valet với custom drivers.

Cài đặt

[!WARNING] Valet yêu cầu macOS và Homebrew. Trước khi cài đặt, bạn nên đảm bảo rằng không có chương trình nào như Apache hoặc Nginx đang chạy ở cổng 80 trên máy local của bạn.

Để bắt đầu, trước tiên bạn cần đảm bảo là Homebrew đã được cập nhật bằng lệnh update:

brew update

Tiếp theo, bạn nên sử dụng Homebrew để cài đặt PHP:

brew install php

Sau khi cài đặt PHP xong, bạn đã sẵn sàng cài đặt Composer package manager. Ngoài ra, bạn nên đảm bảo là thư mục $HOME/.composer/vendor/bin nằm trong "PATH" của hệ thống. Sau khi cài đặt Composer xong, bạn có thể cài đặt Laravel Valet dưới dạng package Composer global:

composer global require laravel/valet

Cuối cùng, bạn có thể chạy lệnh install của Valet. Điều này sẽ cấu hình và cài đặt Valet và DnsMasq. Ngoài ra, các daemon mà Valet phụ thuộc cũng sẽ được cấu hình để khởi chạy khi hệ thống của bạn khởi động:

valet install

Sau khi cài đặt Valet xong, hãy thử ping đến bất kỳ domain *.test nào trên terminal của bạn bằng lệnh như ping foobar.test. Nếu Valet được cài đặt chính xác, bạn sẽ thấy domain này phản hồi trên 127.0.0.1.

Valet sẽ tự động khởi động các service cần thiết mỗi khi máy của bạn khởi động.

PHP Versions

[!NOTE] Thay vì sửa version PHP global, bạn có thể bảo Valet sử dụng các phiên bản PHP cho từng trang web thông qua lệnh isolate.

Valet cho phép bạn chuyển đổi các phiên bản PHP khác nhau bằng lệnh valet use php@version. Valet sẽ cài đặt phiên bản PHP được chỉ định thông qua Homebrew nếu nó chưa được cài đặt:

valet use [email protected]

valet use php

Bạn cũng có thể tạo file .valetrc trong thư mục root của dự án. File .valetrc phải chứa phiên bản PHP mà trang web của bạn sử dụng:

[email protected]

Khi file này đã được tạo, bạn có thể chỉ cần chạy lệnh valet use và lệnh này sẽ xác định phiên bản PHP mặc định của trang web bằng cách đọc file trên.

[!WARNING] Valet chỉ cung cấp một phiên bản PHP tại một thời điểm, kể cả khi bạn đã cài đặt nhiều phiên bản PHP.

Database

Nếu ứng dụng của bạn cần cơ sở dữ liệu, hãy xem DBngin sẽ cung cấp công cụ quản lý cơ sở dữ liệu tất cả trong một phần mền miễn phí bao gồm MySQL, PostgreSQL và Redis. Sau khi DBngin đã được cài đặt, bạn có thể kết nối đến cơ sở dữ liệu của bạn tại 127.0.0.1 bằng username là root và một empty password.

Resetting Your Installation

Nếu bạn gặp khó khăn trong việc cài đặt Valet của bạn chạy đúng cách, hãy chạy lệnh composer global require laravel/valet, theo sau là valet install để reset lại cài đặt của bạn và nó có thể giải quyết nhiều vấn đề. Trong một số trường hợp hiếm hoi, có thể cần phải "hard reset" Valet bằng cách chạy valet uninstall --force và sau đó là valet install.

Nâng cấp Valet

Bạn có thể cập nhật cài đặt Valet của bạn bằng cách chạy lệnh composer global require laravel/valet trong terminal của bạn. Sau khi cập nhật, bạn nên chạy lệnh valet install để Valet có thể nâng cấp bổ sung thêm các file cấu hình nếu cần.

Upgrading to Valet 4

Nếu bạn đang nâng cấp từ Valet 3 lên Valet 4, hãy thực hiện các bước sau để nâng cấp cài đặt Valet của bạn đúng cách:

Tạo Site

Sau khi Valet được cài đặt xong, bạn có thể bắt đầu tạo application Laravel của bạn. Valet cung cấp hai lệnh để giúp bạn tạo application: park và link.

The park Command

Lệnh park sẽ đăng ký một thư mục trên máy của bạn để chứa các ứng dụng của bạn. Khi thư mục đã được "parked" vào Valet, tất cả các thư mục con có trong thư mục đó sẽ có thể truy cập được trong trình duyệt web của bạn tại địa chỉ http://<directory-name>.test:

cd ~/Sites

valet park

Đó là tất cả. Bây giờ, bất kỳ application nào được tạo trong thư mục mà đã được park thì nó sẽ tự động được tạo một site tương ứng theo quy tắc là http://<directory-name>.test. Vì vậy, nếu thư mục parked của bạn chứa một thư mục có tên là "laravel", ứng dụng trong thư mục đó sẽ có thể truy cập được tại địa chỉ http://laravel.test. Ngoài ra, Valet còn tự động cho phép bạn truy cập trang web bằng wildcard subdomain (http://foo.laravel.test).

The link Command

Lệnh link cũng có thể được dùng để tạo application Laravel cho bạn. Lệnh này hữu ích nếu bạn muốn tạo một site trong một thư mục chứ không phải là toàn bộ thư mục:

cd ~/Sites/laravel

valet link

Khi một ứng dụng đã được liên kết với Valet bằng lệnh link, bạn có thể truy cập vào ứng dụng bằng tên thư mục của nó. Vì vậy, trang web được liên kết trong ví dụ trên có thể được truy cập tại địa chỉ http://laravel.test. Ngoài ra, Valet còn tự động cho phép bạn truy cập trang web bằng cách sử dụng wildcard subdomain (http://foo.laravel.test).

Nếu bạn muốn chạy ứng dụng ở một hostname khác, bạn có thể truyền hostname đó cho lệnh link. Ví dụ: bạn có thể chạy lệnh sau để tạo ứng dụng tại địa chỉ http://application.test:

cd ~/Sites/laravel

valet link application

Tất nhiên, bạn cũng có thể cung cấp ứng dụng của bạn trên các sub-domain bằng lệnh link:

valet link api.application

Bạn có thể chạy lệnh links để hiển thị danh sách tất cả các thư mục đã được liên kết của bạn:

valet links

Lệnh unlink có thể được sử dụng để hủy liên kết cho một trang web:

cd ~/Sites/laravel

valet unlink

Securing Sites With TLS

Mặc định, Valet sẽ tạo site trên HTTP. Tuy nhiên, nếu bạn muốn tạo một trang web được mã hoá TLS bằng HTTP/2, bạn có thể sử dụng lệnh secure. Ví dụ: nếu trang web của bạn đang được Valet tạo trên tên miền là laravel.test, thì bạn nên chạy lệnh sau để bảo vệ trang web này:

valet secure laravel

Để bỏ lớp bảo mật và quay lại dùng HTTP, thì hãy dùng lệnh unsecure. Giống như lệnh secure, nó chấp nhận host name là bạn không muốn bảo mật:

valet unsecure laravel

Serving A Default Site

Thỉnh thoảng, bạn có thể muốn cấu hình Valet chạy một trang web "mặc định" thay vì trang 404 khi truy cập vào tên miền test không có. Để thực hiện điều này, bạn có thể thêm một tùy chọn default vào file cấu hình ~/.config/valet/config.json của bạn để chứa đường dẫn đến trang web sẽ đóng vai trò là trang web mặc định của bạn:

"default": "/Users/Sally/Sites/example-site",

Phiên bản PHP cho từng trang web

Mặc định, Valet sử dụng cài đặt global PHP của bạn để chạy các trang web của bạn. Tuy nhiên, nếu bạn cần hỗ trợ nhiều phiên bản PHP trên nhiều trang web khác nhau, bạn có thể sử dụng lệnh isolate để chỉ định một phiên bản PHP sẽ được một trang web cụ thể sử dụng. Lệnh cấu hình isolate Valet sẽ sử dụng phiên bản PHP đã chỉ định cho trang web nằm trong thư mục hiện tại của bạn:

cd ~/Sites/example-site

valet isolate [email protected]

Nếu tên trang web của bạn không khớp với tên của thư mục chứa trang web đó, bạn có thể chỉ định tên trang web bằng tùy chọn --site:

valet isolate [email protected] --site="site-name"

Để thuận tiện, bạn có thể sử dụng các lệnh valet php, composer và which-php để proxy call đến PHP CLI hoặc công cụ phù hợp dựa trên phiên bản PHP đã được cấu hình cho trang web:

valet php
valet composer
valet which-php

Bạn có thể thực hiện lệnh isolated để hiển thị danh sách tất cả các trang web đã được chỉ định và phiên bản PHP của chúng:

valet isolated

Để khôi phục trang web về phiên bản PHP được Valet cài đặt global, bạn có thể gọi lệnh unisolate từ thư mục root của trang web:

valet unisolate

Chia sẻ site

Valet đã chứa một lệnh để chia sẻ các trang web ở local của bạn với thế giới, cung cấp một cách dễ dàng để kiểm tra trang web của bạn trên các thiết bị di động hoặc chia sẻ nó với các thành viên trong team của bạn hoặc khách hàng.

Mặc định, Valet hỗ trợ chia sẻ các trang web của bạn thông qua ngrok hoặc Expose. Trước khi chia sẻ một trang web, bạn nên cập nhật cấu hình Valet của bạn bằng lệnh share-tool thông qua chỉ định ngrok, expose, hoặc cloudflared:

valet share-tool ngrok

Nếu bạn chọn một công cụ và nó chưa được cài đặt thông qua Homebrew (cho ngrok) hoặc Composer (cho Expose và cloudflared), Valet vẫn sẽ tự động nhắc bạn cài đặt nó. Tất nhiên, cả hai công cụ đều yêu cầu bạn xác thực tài khoản ngrok hoặc Expose của bạn trước khi bạn có thể bắt đầu chia sẻ các trang web.

Để chia sẻ một trang web, hãy trỏ đến thư mục chứa trang web đó trong terminal của bạn và chạy lệnh share của Valet. Một URL sẽ được copy vào clipboard của bạn và sẵn sàng paste vào bất kỳ đâu, ví dụ như vào trong trình duyệt của bạn hoặc là chia sẻ với team của bạn:

cd ~/Sites/laravel

valet share

Để ngừng chia sẻ trang web của bạn, bạn có thể nhấn Control + C.

[!WARNING] Nếu bạn đang sử dụng máy chủ đổi DNS (như 1.1.1.1), chia sẻ ngrok có thể không hoạt động chính xác. Nếu đây là trường hợp trên máy của bạn, hãy mở cài đặt system setting của máy Mac, đi tới Network setting, mở Advanced setting, sau đó đi tới tab DNS và thêm 127.0.0.1 làm máy chủ DNS đầu tiên của bạn.

Sharing Sites via Ngrok

Việc chia sẻ trang web của bạn thông qua ngrok sẽ yêu cầu bạn phải một tạo tài khoản ngrok và cài đặt một mã authentication token. Sau khi bạn đã có mã authentication token, bạn có thể cập nhật cấu hình Valet của bạn bằng mã token đó:

valet set-ngrok-token YOUR_TOKEN_HERE

[!NOTE] Bạn có thể truyền thêm tham số ngrok cho lệnh share, chẳng hạn như valet share --region=eu. Để biết thêm thông tin, hãy tham khảo tài liệu ngrok.

Sharing Sites via Expose

Để chia sẻ trang web của bạn thông qua Expose, bạn phải tạo một tài khoản Expose và xác thực Expose thông qua mã authentication token của bạn.

Bạn có thể tham khảo tài liệu Expose để biết thêm thông tin về các tham số command-line mà nó có thể hỗ trợ.

Chia sẻ site trên mạng local

Mặc định, Valet sẽ hạn chế lưu lượng đến địa chỉ IP 127.0.0.1 nên máy local của bạn sẽ không bị ảnh hưởng bởi các rủi ro bảo mật từ Internet.

Nếu bạn muốn cho phép các thiết bị khác trong mạng nội bộ của mình truy cập được vào các trang web Valet trên máy của bạn thông qua địa chỉ IP của máy (ví dụ: 192.168.1.10/application.test), bạn sẽ cần phải chỉnh sửa file cấu hình Nginx cho trang web của bạn để loại bỏ các hạn chế đối với các lệnh listen. Bạn có thể làm điều đó bằng cách xóa tiền tố 127.0.0.1: trên lệnh listen cho các cổng 80 và 443.

Nếu bạn chưa chạy valet secure trong project, bạn có thể mở quyền truy cập mạng cho tất cả các trang web không phải HTTPS bằng cách chỉnh sửa file /usr/local/etc/nginx/valet/valet.conf. Tuy nhiên, nếu bạn đang chạy trang web của project thông qua HTTPS (bạn đã chạy lệnh valet secure cho trang web) thì bạn nên chỉnh sửa file ~/.config/valet/Nginx/app-name.test.

Khi bạn đã cập nhật cấu hình Nginx của bạn, hãy chạy lệnh valet restart để áp dụng các thay đổi cấu hình.

Các biến môi trường cho trang web

Một số ứng dụng sử dụng các framework khác có thể phụ thuộc vào các biến môi trường trên server nhưng lại không cung cấp cách thức để các biến đó được cấu hình trong project của bạn. Valet cho phép bạn cấu hình các biến môi trường cho trang web bằng cách thêm một file .valet-env.php vào trong thư mục gốc của project của bạn. File này sẽ trả về một mảng trang web gồm các cặp biến môi trường sẽ được thêm vào mảng global $_SERVER cho mỗi trang web được chỉ định trong mảng:

<?php

return [
    // Set $_SERVER['key'] to "value" for the laravel.test site...
    'laravel' => [
        'key' => 'value',
    ],

    // Set $_SERVER['key'] to "value" for all sites...
    '*' => [
        'key' => 'value',
    ],
];

Proxying Services

Thỉnh thoảng bạn có thể muốn proxy một tên miền Valet cho một service khác trên máy local của bạn. Ví dụ: đôi khi bạn có thể cần chạy Valet trong khi cũng cần chạy một trang web khác trong Docker; tuy nhiên, cả Valet và Docker không thể cùng liên kết đến cổng 80 cùng một lúc.

Để giải quyết vấn đề này, bạn có thể sử dụng lệnh proxy để tạo proxy. Ví dụ: bạn có thể proxy tất cả các lưu lượng truy cập từ http://elasticsearch.test đến http://127.0.0.1:9200:

# Proxy over HTTP...
valet proxy elasticsearch http://127.0.0.1:9200

# Proxy over TLS + HTTP/2...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

Bạn có thể xóa proxy đó bằng lệnh unproxy:

valet unproxy elasticsearch

Bạn có thể sử dụng lệnh proxies để hiển thị tất cả cấu hình trang web mà đang được proxy:

valet proxies

Tùy chỉnh Valet Drivers

Bạn có thể viết Valet "driver" của riêng bạn để tạo các application PHP chạy trên framework hoặc CMS mà không được Valet hỗ trợ. Khi bạn cài đặt Valet, một thư mục ~/.config/valet/Drivers sẽ được tạo và chứa file SampleValetDriver.php. File này sẽ chứa một driver mẫu để trình bày cách viết một driver tùy chỉnh. Để viết một driver tùy chỉnh thì nó chỉ yêu cầu bạn kế thừa 3 phương thức: serves, isStaticFile, và frontControllerPath.

Tất cả 3 phương thức này đều nhận các giá trị là $sitePath, $siteName, và $uri làm tham số của chúng. $sitePath là đường dẫn đến trang web mà đã được tạo trên máy của bạn, chẳng hạn như /Users/Lisa/Sites/my-project. $siteName là phần "host" hoặc phần "site name" của tên miền(my-project). $uri là request URI (/foo/bar).

Khi mà bạn đã tùy chỉnh xong Valet driver, hãy lưu nó vào trong thư mục ~/.config/valet/Drivers bằng cách sử dụng quy ước đặt tên như sau FrameworkValetDriver.php. Ví dụ: nếu bạn đang viết valet driver cho WordPress, thì nên đặt tên file của bạn phải là WordPressValetDriver.php.

Hãy xem cách làm mẫu của từng phương thức mà driver Valet của bạn nên làm.

Phương thức serves

Phương thức serves sẽ trả về true nếu driver của bạn sẽ xử lý request. Ngược lại, phương thức sẽ trả về false. Vì vậy, trong phương thức này, bạn nên xác định xem $sitePath đã cho có chứa loại dự án mà bạn đang tạo hay không.

Ví dụ: hãy nghĩ rằng, chúng ta đang viết một driver WordPressValetDriver. Phương thức serves của chúng ta có thể trông giống như thế này:

/**
 * Determine if the driver serves the request.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

Phương thức isStaticFile

IsStaticFile sẽ xác định xem request đến có phải là file "static" hay không, chẳng hạn như hình ảnh hoặc stylesheet. Nếu file là static, phương thức sẽ trả về đường dẫn đến file static trên disk. Nếu request đến không phải cho file static, phương thức sẽ trả về false:

/**
 * Determine if the incoming request is for a static file.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

[!WARNING] phương thức isStaticFile sẽ chỉ được gọi nếu phương thức serves trả về true và request URI không phải là /.

Phương thức frontControllerPath

Phương thức frontControllPath sẽ trả về đường dẫn "front controller" của application, thường là file "index.php" hoặc tương đương:

/**
 * Get the fully resolved path to the application's front controller.
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
{
    return $sitePath.'/public/index.php';
}

Local Drivers

Nếu bạn muốn định nghĩa một Valet driver tùy chỉnh cho một application, hãy tạo một file LocalValetDriver.php trong thư mục gốc của application. Valet driver tùy chỉnh của bạn có thể extent từ class ValetDriver hoặc extent từ một driver nào đó của một application hiện có, chẳng hạn nhưLaravelValetDriver:

use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

    /**
     * Get the fully resolved path to the application's front controller.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public_html/index.php';
    }
}

Các lệnh Valet khác

Thư mục và file valet

Các thông tin về thư mục và các file sau đây có thể hữu ích cho bạn, trong khi bạn khắc phục sự cố với môi trường Valet của bạn:

~/.config/valet

Chứa tất cả cấu hình của Valet. Bạn có thể muốn tạo một bản sao của thư mục này.

~/.config/valet/dnsmasq.d/

Thư mục này chứa cấu hình của DNSMasq.

~/.config/valet/Drivers/

Thư mục này chứa driver của Valet. Driver xác định cách chạy của một framework hoặc một CMS cụ thể.

~/.config/valet/Nginx/

Thư mục này chứa tất cả các cấu hình trang Nginx của Valet. Các file này sẽ được built lại khi chạy các lệnh install và secure.

~/.config/valet/Sites/

Thư mục này chứa tất cả các liên kết ảo cho các project đã được liên kết của bạn.

~/.config/valet/config.json

File này là file cấu hình chính của Valet.

~/.config/valet/valet.sock

File này là socket PHP-FPM được sử dụng bởi quá trình cài đặt Nginx của Valet. Nó sẽ chỉ tồn tại nếu PHP chạy đúng cách.

~/.config/valet/Log/fpm-php.www.log

File này là file user log cho các lỗi PHP.

~/.config/valet/Log/nginx-error.log

File này là file user log cho các lỗi Nginx.

/usr/local/var/log/php-fpm.log

File này là file system log cho các lỗi PHP-FPM.

/usr/local/var/log/nginx

Thư mục này chứa file error log và file log Nginx access.

/usr/local/etc/php/X.X/conf.d

Thư mục này sẽ chứa các file *.ini cho các cài đặt cấu hình PHP khác nhau.

/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf

File này là file cấu hình PHP-FPM pool.

~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf

File này là file cấu hình Nginx mặc định được sử dụng để tạo chứng chỉ SSL cho trang web của bạn.

Truy cập vào disk

Từ macOS 10.14, mặc định, quyền truy cập vào một số file hoặc thư mục sẽ bị hạn chế. Những hạn chế này bao gồm các thư mục Desktop, Documents và Downloads. Ngoài ra, quyền truy cập vào network volume và removable volume cũng bị hạn chế. Do đó, Valet khuyên bạn nên set các thư mục trang web của bạn nên bên ngoài các vị trí được bảo vệ này.

Tuy nhiên, nếu bạn vẫn muốn chạy các trang web từ một trong những vị trí đó, bạn sẽ cần cấp cho Nginx quyền "Full Disk Access". Nếu không, bạn có thể gặp lỗi server hoặc hành vi không thể đoán trước được từ Nginx, đặc biệt là khi chạy các asset tĩnh. Thông thường, macOS sẽ tự động nhắc bạn cấp cho Nginx quyền truy cập đầy đủ vào các vị trí này. Hoặc, bạn có thể thực hiện thủ công bằng cách thông qua System Preferences > Security & Privacy > Privacy và chọn Full Disk Access. Tiếp theo, hãy enable bất kỳ mục nginx nào có trong cửa sổ chính.