Học Laravel 13 – Bài 02: Cài đặt Laravel 13 và môi trường phát triển TaskFlow

Bài 2 của chuỗi Laravel 13: chuẩn bị một ứng dụng TaskFlow chạy được, có database và có thể kiểm thử. Đầu ra chưa phải phần mềm quản lý công việc hoàn chỉnh; đó là điểm xuất phát ổn định để các bài tiếp theo cùng phát triển. Đọc bài 1: lộ trình TaskFlow trước khi bắt đầu.

1. Chốt một môi trường thực hành

Trong nhánh thực hành chính, chúng ta dùng Laravel 13, Blade và SQLite. Chưa cần Docker, Redis, MySQL hay frontend tách rời. Những công cụ này sẽ xuất hiện khi bài học có nhu cầu cụ thể. Cách chọn này giúp tách lỗi cài đặt khỏi lỗi nghiệp vụ.

Laravel 13 có mức tối thiểu PHP 8.3, nhưng dependency được khóa cho dự án minh họa ở thời điểm kiểm chứng yêu cầu môi trường PHP 8.4 trở lên. Vì vậy hãy dùng PHP 8.4 tương thích cùng các extension cần thiết cho nhánh thực hành này. Mức tối thiểu của framework không đồng nghĩa mọi phiên bản package phát triển đều chạy trên mức đó. Tham khảo yêu cầu triển khai Laravel.

Đây là phiên bản thực tế của lần kiểm chứng, không phải cam kết rằng một lệnh cài mới trong tương lai sẽ resolve giống hệt. Giữ lock file để tái lập dependency. Đối chiếu yêu cầu Node của Vite nếu máy dùng một Node major khác.

2. Kiểm tra terminal trước khi tạo project

php -v
php --ini
php -m
composer --version
node --version
npm --version
git --version

Trên PowerShell, dùng Get-Command php và Get-Command composer để biết file thực thi nào được gọi. Trên macOS/Linux, dùng command -v php. PHP của terminal có thể khác PHP của Apache, Herd hoặc một container. Nếu máy đang dùng XAMPP PHP 8.2, chạy Composer bằng PHP đó sẽ không đáp ứng Laravel 13 dù trình duyệt vẫn mở được một website cũ.

Cần kiểm tra các extension như OpenSSL, Mbstring, PDO, Fileinfo, DOM/XML, Ctype, Tokenizer và driver pdo_sqlite; curl và zip giúp quá trình tải package thuận tiện. Đọc đường dẫn Loaded Configuration File trước khi sửa php.ini. Không chỉnh một file ini mà CLI không tải. Trên Windows, bản PHP phải tương thích kiến trúc và Visual C++ runtime; cài runtime chính thức khi cần, không tải DLL từ website không tin cậy.

3. Tạo TaskFlow trong thư mục mới

Các lệnh dưới đây giả định PHP phù hợp đã nằm trên PATH. Chạy ở thư mục cha, chưa có thư mục taskflow chứa dữ liệu quan trọng:

composer create-project laravel/laravel taskflow "^13.0" --prefer-dist
cd taskflow
php artisan --version
composer check-platform-reqs

Đây là cách tạo skeleton qua Composer đã dùng để kiểm chứng bài học. Laravel cũng cung cấp installer tương tác trong hướng dẫn cài đặt chính thức. Chỉ chọn một cách tạo project; không chạy cả hai vào cùng thư mục. Chưa cài starter kit ở bài này, vì chúng ta cần hiểu cấu trúc nền trước.

Nếu Composer báo version conflict, đọc package nào yêu cầu phiên bản PHP nào. Không dùng --ignore-platform-reqs để che lỗi. Nếu tải package thất bại vì TLS, kiểm tra CA bundle và đồng hồ máy thay vì tắt xác minh chứng chỉ. Nếu tiến trình vẫn đang giải nén, chờ nó kết thúc; không khởi chạy một Composer thứ hai vào cùng vendor.

4. Cấu hình local và database

Quy trình tạo project thường chuẩn bị .env và application key. Kiểm tra file tồn tại nhưng không chụp hoặc đăng nội dung chứa secret. Nếu khởi tạo từ một checkout chưa có .env, trên PowerShell dùng Copy-Item .env.example .env một lần, rồi chạy php artisan key:generate. Không ghi đè .env có sẵn và không tạo lại key trên ứng dụng đã có dữ liệu mã hóa.

Trong file local, đặt các giá trị không bí mật sau; giữ APP_KEY đã được tạo:

APP_NAME=TaskFlow
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
DB_CONNECTION=sqlite

Với skeleton chuẩn, để cấu hình database dùng đường dẫn SQLite mặc định trong database/database.sqlite; đừng giữ một DB_DATABASE cũ trỏ tới database ngoài dự án. Sau đó chạy:

php artisan config:clear
php artisan migrate
php artisan migrate:status

Nếu được hỏi tạo file SQLite, chỉ đồng ý khi đang ở project local vừa tạo. Kết quả mong đợi là các migration users, cache và jobs đã chạy. Đây là hạ tầng mặc định, chưa có bảng projects hoặc tasks. Không dùng migrate:fresh như mẹo chữa lỗi chung: nó xóa toàn bộ bảng trên connection đang chọn.

5. Build giao diện và chạy ứng dụng

npm install --ignore-scripts
npm run build
php artisan test
php artisan serve --host=127.0.0.1 --port=8000

Mở http://127.0.0.1:8000. Giữ terminal serve chạy; dùng Ctrl+C để dừng. Việc bind vào loopback giữ server thực hành trong máy local. Đây không phải cách phục vụ production. Sau khi có package-lock.json, các lần cài sạch dùng npm ci --ignore-scripts để giữ dependency theo lock. Tùy chọn ignore-scripts bỏ lifecycle script trong bước cài; lệnh npm run build vẫn chạy script build được yêu cầu rõ ràng.

Lần kiểm chứng của bài này: Laravel báo 13.32.0, ba migration nền đã chạy, hai test skeleton pass với hai assertions, và Vite build thành công. Build có cảnh báo tùy chọn về fontaine cho tối ưu font fallback; đây không phải lỗi build. Kết quả này chỉ xác nhận skeleton hoạt động, chưa chứng minh các chức năng TaskFlow hoặc khả năng chịu tải.

Khi bắt đầu sửa giao diện ở bài sau, có thể chạy npm run dev trong terminal riêng để Vite cập nhật tài nguyên nhanh. Nếu xuất hiện lỗi manifest, kiểm tra đã chạy build trong đúng project; nếu trình duyệt tìm Vite server đã tắt, kiểm tra trạng thái dev server và file hot trước khi kết luận Laravel bị lỗi.

6. Checklist xử lý lỗi thường gặp

• Could not find driver: kiểm tra pdo_sqlite bằng đúng PHP đang chạy Artisan; bật extension và khởi động lại tiến trình.
• No application encryption key: chỉ với project local mới, kiểm tra .env rồi tạo key; nếu config đã cache thì clear cache.
• Unable to open database file: kiểm tra đường dẫn, file SQLite và quyền ghi thư mục database.
• Port 8000 bận: thử port 8001 và cập nhật URL truy cập; không dừng một tiến trình chưa xác định chủ sở hữu.
• 500: đọc lỗi gần nhất trong storage/logs; không gửi toàn bộ log nếu chứa token, cookie hoặc dữ liệu cá nhân.
• Composer chạy PHP cũ: sửa PATH có chủ đích hoặc gọi PHP mới với composer.phar; kiểm tra lại php -v trước khi cài.

7. Bài tập và điều kiện hoàn thành

Tạo project của riêng bạn, lưu kết quả phiên bản, migrate:status, test và build vào ghi chú học tập không chứa secret. Giải thích bằng lời vì sao Composer và npm là hai bước khác nhau, tại sao SQLite cần driver PDO, và vì sao giữ composer.lock cùng package-lock.json trong Git.

Không commit .env, vendor, node_modules, database local hoặc public/build nếu repository đã quy định build ở CI. Giữ .env.example không chứa secret để người khác biết các biến cần cấu hình. Bài hoàn thành khi bạn có thể dừng server, mở terminal mới, chạy lại ứng dụng và giải thích từng bước — không chỉ khi thấy trang welcome một lần.

Điều hướng: Bài 1 — Lộ trình. Bài tiếp theo sẽ đi qua cấu trúc project và vòng đời request, trước khi bổ sung nghiệp vụ TaskFlow.

Điều hướng khóa học Laravel 13

Bài trước (01) · Bài sau (03) · Mục lục trọn bộ 37 bài