Cài đặt Laravel 13

Ở bài trước mình đã điểm qua những tính năng mới trong Laravel 13. Tiếp tục với series, bài này mình sẽ hướng dẫn mọi người cài đặt Laravel 13, tìm hiểu cấu trúc thư mục, file .env, vòng đời của một request và khởi tạo project TaskFlow mà chúng ta sẽ xây dựng trong suốt series.

1. Cài đặt PHP, Composer và Laravel installer.

Để tạo một ứng dụng Laravel 13, máy của các bạn cần có:

PHP 8.3 trở lên (series này dùng PHP 8.4).
Composer: trình quản lý package của PHP.
Laravel installer: công cụ dòng lệnh laravel dùng để tạo project mới.
Node.js và npm (hoặc Bun) để build các file CSS, JavaScript của ứng dụng.

Cài đặt qua php.new.

Nếu máy chưa có PHP và Composer, cách nhanh nhất là dùng script của php.new. Chỉ một câu lệnh là các bạn có đủ PHP, Composer và Laravel installer.

# macOS
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

# Linux
/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

Với Windows, các bạn mở PowerShell bằng quyền administrator và chạy lệnh tương ứng trên trang php.new. Số 8.4 ở cuối URL là phiên bản PHP muốn cài. Cài xong các bạn cần mở lại terminal. Muốn cập nhật PHP, Composer và Laravel installer thì chỉ cần chạy lại câu lệnh trên.

Cài đặt qua Laravel Herd.

Với macOS và Windows, các bạn có thể dùng Laravel Herd: một ứng dụng cài như phần mềm bình thường, có sẵn PHP, Nginx và các lệnh php, composer, laravel, node, npm.

Herd tạo sẵn thư mục ~/Herd. Mọi project Laravel đặt trong thư mục này sẽ tự chạy được ở tên miền .test theo tên thư mục, VD: ~/Herd/taskflow sẽ có địa chỉ http://taskflow.test.

Đã có sẵn PHP và Composer.

Nếu máy đã có PHP 8.3+ và Composer, các bạn chỉ cần cài thêm Laravel installer:

composer global require laravel/installer

Lưu ý: Thư mục chứa các lệnh cài global của Composer phải có trong biến PATH thì mới gọi được lệnh laravel. Các bạn xem thư mục đó bằng lệnh composer global config bin-dir --absolute.

2. Tạo project TaskFlow với laravel new.

Để tạo project mới, các bạn sử dụng lệnh laravel new ten-project, trong đó ten-project là tên thư mục sẽ chứa code của ứng dụng.

VD: Mình sẽ tạo project taskflow.

laravel new taskflow --no-boost

Option --no-boost để bỏ qua Laravel Boost, một công cụ cung cấp ngữ cảnh cho các AI agent khi code. Series này không cần đến nó, nếu thích các bạn có thể cài thêm sau.

Installer sẽ hỏi hai câu, mình trả lời như sau:

 ┌ Do you want to use a starter kit? ───────────────────────────┐
 │ No                                                           │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which frontend stack do you want to build on? ───────────────┐
 │ Blade                                                        │
 └──────────────────────────────────────────────────────────────┘

Starter kit là bộ code khởi đầu có sẵn giao diện và chức năng đăng ký, đăng nhập... viết bằng React, Svelte, Vue hoặc Livewire.

Series này không dùng starter kit vì nó sinh ra rất nhiều file mà khi mới học chúng ta chưa hiểu được. Chức năng đăng ký, đăng nhập sẽ được viết tay ở bài Xác thực người dùng (Bài 21).

Còn chọn Blade nghĩa là không thêm code giao diện nào, chỉ dùng Blade template của Laravel.

Những lựa chọn còn lại installer tự quyết định mà không hỏi: database mặc định là SQLite (tạo sẵn file database/database.sqlite và chạy migration), framework test là Pest, sau đó chạy npm install và npm run build. Nếu muốn chọn khác, các bạn truyền option, VD: --database=mysql, --phpunit.

Lưu ý: Không dùng installer thì các bạn vẫn có thể tạo project bằng Composer như các series trước: composer create-project laravel/laravel taskflow.

3. Chạy ứng dụng.

Để chạy ứng dụng ở môi trường phát triển, các bạn di chuyển vào thư mục project và chạy lệnh:

cd taskflow
composer run dev

Lệnh này gọi php artisan dev và chạy cùng lúc các tiến trình cần thiết khi code: web server (php artisan serve), queue worker (php artisan queue:listen), xem log (php artisan pail) và Vite (npm run dev) để tự build lại CSS, JavaScript mỗi khi sửa.

Nếu chỉ cần web server, các bạn chạy riêng lệnh serve:

php artisan serve

#   INFO  Server running on [http://127.0.0.1:8000].
#
#  Press Ctrl+C to stop the server

Lúc này mở trình duyệt và truy cập http://localhost:8000, các bạn sẽ thấy trang welcome của Laravel. Nếu dùng Herd và đặt project trong ~/Herd thì không cần chạy lệnh nào, chỉ cần vào http://taskflow.test (hoặc gõ herd open).

Trang welcome này được khai báo trong file routes/web.php:

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Đoạn code trên có nghĩa là khi truy cập đường dẫn /, Laravel sẽ trả về view resources/views/welcome.blade.php. Route sẽ được nói chi tiết ở bài sau.

Lưu ý: php artisan serve chỉ dùng trong quá trình phát triển. Trên production các bạn cần web server như Nginx + PHP-FPM, mình sẽ hướng dẫn ở bài cuối series (Bài 32).

4. Cấu trúc thư mục.

Từ Laravel 11, cấu trúc thư mục đã được tinh gọn khá nhiều so với Laravel 8. Các thư mục chính của project TaskFlow lúc này gồm:

app: chứa code chính của ứng dụng (namespace App). Mặc định chỉ có Http/Controllers, Models và Providers, các thư mục khác sẽ được tạo dần khi chạy các lệnh php artisan make:....
bootstrap: chứa file app.php khởi động framework, đồng thời là nơi cấu hình route, middleware và xử lý exception. File providers.php chứa danh sách service provider của ứng dụng.
config: chứa các file cấu hình (app.php, database.php, mail.php...).
database: chứa migration, factory, seeder và file SQLite database.sqlite.
public: thư mục gốc của web server, chứa file index.php nhận mọi request và các file tĩnh như ảnh, CSS, JS đã build.
resources: chứa view (Blade) và file CSS, JavaScript chưa build.
routes: chứa web.php (các route của web) và console.php (các command dạng closure và lịch chạy). File api.php không còn có sẵn, khi cần làm API chúng ta sẽ tạo bằng lệnh php artisan install:api.
storage: chứa log, cache, view đã biên dịch và file người dùng upload.
tests: chứa các test (Pest).
vendor: các package cài qua Composer.

Ngoài ra ở thư mục gốc còn có file artisan (công cụ dòng lệnh của Laravel), composer.json, package.json và .env.

5. File .env và cấu hình.

Cấu hình của Laravel nằm trong thư mục config, nhưng những giá trị thay đổi theo từng môi trường (máy local, server production...) như tên ứng dụng, thông tin database sẽ được khai báo trong file .env. Khi cài đặt, Laravel đã copy file .env.example thành .env và tạo sẵn APP_KEY (khóa dùng để mã hóa):

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=sqlite

Các file trong thư mục config đọc giá trị từ .env qua hàm env(), VD trong config/app.php:

'name' => env('APP_NAME', 'Laravel'),

Tham số thứ hai là giá trị mặc định, được dùng khi trong .env không có biến APP_NAME. Còn trong code của ứng dụng, các bạn lấy giá trị cấu hình bằng hàm config() với cú pháp tên-file.tên-key:

config('app.name');         // "TaskFlow"
config('database.default'); // "sqlite"

VD: Mình đổi tên ứng dụng thành TaskFlow. Các bạn sửa dòng APP_NAME trong cả .env và .env.example:

APP_NAME=TaskFlow

Sau đó kiểm tra lại bằng lệnh php artisan about:

php artisan about --only=environment

#  Environment ................................................................
#  Application Name .................................................. TaskFlow
#  Laravel Version .................................................... 13.42.0
#  PHP Version ......................................................... 8.4.27
#  Composer Version .................................................... 2.11.2
#  Environment .......................................................... local
#  Debug Mode ......................................................... ENABLED
#  URL ......................................................... localhost:8000
#  ...

Tải lại trang welcome, các bạn sẽ thấy tiêu đề của tab đã đổi thành TaskFlow, vì view welcome in ra config('app.name') trong thẻ <title>.

Chú ý: Không được commit file .env lên Git, vì mỗi máy có cấu hình riêng và file này thường chứa mật khẩu, API key. Laravel đã thêm .env vào .gitignore sẵn. File .env.example thì nên commit để người khác biết ứng dụng cần những biến nào. Ngoài ra, chỉ nên gọi env() trong các file config, còn ở chỗ khác hãy dùng config().

6. Vòng đời của một request.

Hiểu được một request đi qua Laravel như thế nào sẽ giúp các bạn thấy framework bớt "ma thuật" hơn. Web server (Nginx, Apache...) chuyển mọi request vào file public/index.php:

// Register the Composer autoloader...
require __DIR__.'/../vendor/autoload.php';

// Bootstrap Laravel and handle the request...
/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';

$app->handleRequest(Request::capture());

Từ đây, request sẽ đi qua các bước sau:

index.php nạp autoloader của Composer, rồi lấy instance của ứng dụng từ bootstrap/app.php. Việc đầu tiên Laravel làm là tạo ra ứng dụng, cũng chính là service container (sẽ nói ở Bài 25).
Request được chuyển cho HTTP kernel. Kernel chạy các bước chuẩn bị như cấu hình xử lý lỗi, logging, xác định môi trường từ .env và quan trọng nhất là nạp các service provider: gọi method register của tất cả provider trước, sau đó mới gọi method boot. Provider của ứng dụng nằm trong app/Providers và được khai báo trong bootstrap/providers.php.
Request đi qua các middleware (session, chế độ bảo trì, CSRF...), rồi đến router. Router tìm route khớp với request, chạy các middleware gắn với route đó và gọi closure hoặc controller tương ứng.
Response trả về sẽ đi ngược lại qua các middleware, cuối cùng được gửi về trình duyệt.

Các bạn chưa cần nhớ hết các khái niệm trên, mỗi phần đều sẽ có bài riêng trong series. Chi tiết về vòng đời request các bạn có thể xem thêm tại đây.

7. Lời kết.

Như vậy là chúng ta đã cài đặt Laravel 13, tạo xong project TaskFlow với SQLite và nắm được cấu trúc thư mục, file .env cũng như vòng đời của một request. Bài sau mình sẽ giới thiệu với mọi người về route trong Laravel 13 và tạo những route đầu tiên cho TaskFlow.