Hướng dẫn cài đặt Laravel từ A-Z

Giới thiệu về Laravel

Laravel là một PHP framework mã nguồn mở, mạnh mẽ và hiện đại được phát triển bởi Taylor Otwell. Framework này được xây dựng với mục tiêu tạo ra trải nghiệm phát triển ứng dụng web một cách thanh lịch, đơn giản và dễ hiểu. Laravel đã trở thành một trong những PHP framework phổ biến nhất trên thế giới, được sử dụng bởi hàng triệu developers và các công ty lớn.

Với Laravel, bạn có thể xây dựng các ứng dụng web từ đơn giản đến phức tạp một cách nhanh chóng nhờ vào các tính năng như routing, ORM (Eloquent), authentication, caching, queue system, và nhiều công cụ mạnh mẽ khác. Tuy nhiên, trước khi có thể bắt đầu phát triển ứng dụng với Laravel, việc đầu tiên và quan trọng nhất là cài đặt Laravel framework một cách chính xác.

Yêu cầu hệ thống trước khi cài đặt Laravel

Trước khi bắt đầu cài đặt Laravel, bạn cần đảm bảo hệ thống của mình đáp ứng các yêu cầu tối thiểu sau:

Yêu cầu PHP

Laravel yêu cầu phiên bản PHP cụ thể tùy thuộc vào phiên bản Laravel bạn muốn cài đặt:

• Laravel 12.x: Yêu cầu PHP 8.2 trở lên
• Laravel 11.x: Yêu cầu PHP 8.2 trở lên
• Laravel 10.x: Yêu cầu PHP 8.1 trở lên
• Laravel 9.x: Yêu cầu PHP 8.0 trở lên

Ngoài ra, PHP cần có các extension sau được kích hoạt: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PCRE, PDO, Tokenizer, XML

Composer

Composer là dependency manager cho PHP, và đây là công cụ không thể thiếu khi làm việc với Laravel. Bạn cần cài đặt Composer trên hệ thống của mình. Composer giúp quản lý các thư viện và dependencies của dự án Laravel một cách tự động.

Node.js và NPM hoặc Bun

Để compile frontend assets (CSS, JavaScript) của ứng dụng, bạn cần cài đặt một trong các công cụ sau:

• Node.js và NPM: Package manager phổ biến nhất
• Bun: Runtime và package manager hiện đại, nhanh hơn NPM

Cả hai đều có thể được sử dụng với Laravel để compile assets thông qua Vite.

Các công cụ bổ sung (tùy chọn)

• Database: MySQL, PostgreSQL, SQLite, hoặc SQL Server tùy theo nhu cầu của dự án
• Web Server: Apache hoặc Nginx (hoặc sử dụng built-in server của PHP cho development)
• Laravel Herd: Development environment tích hợp cho macOS và Windows (bao gồm PHP, Nginx, và các công cụ khác)

Kiểm tra môi trường hiện tại

Trước khi cài đặt Laravel, hãy kiểm tra xem hệ thống của bạn đã đáp ứng các yêu cầu chưa:

Mở terminal (hoặc Command Prompt trên Windows) và chạy lệnh:

## Kiểm tra phiên bản PHP
php -v

# Để kiểm tra các extensions đã được cài đặt, chạy lệnh:
php -m

## Hoặc kiểm tra extension cụ thể:
php -m | grep -i openssl
php -m | grep -i pdo
php -m | grep -i mbstring

# Kiểm tra xem Composer đã được cài đặt chưa:
composer --version

Nếu chưa có Composer, bạn cần cài đặt nó trước. Composer có thể được cài đặt theo nhiều cách:

Trên Windows: Tải file Composer-Setup.exe từ getcomposer.org

Trên macOS/Linux: Sử dụng lệnh:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Các phương pháp cài đặt Laravel

Theo tài liệu chính thức của Laravel, có nhiều cách để cài đặt Laravel. Hãy cùng tìm hiểu từng phương pháp theo thứ tự được khuyến nghị:

Phương pháp 1: Sử dụng Laravel Installer (Khuyến nghị)

Theo tài liệu chính thức Laravel 12.x, Laravel Installer là phương pháp được khuyến nghị để tạo ứng dụng Laravel mới. Đây là cách nhanh nhất và đơn giản nhất để bắt đầu với Laravel.

Cài đặt Laravel Installer

Trước tiên, bạn cần cài đặt Laravel Installer globally thông qua Composer:

composer global require laravel/installer

Sau đó, đảm bảo thư mục ~/.composer/vendor/bin (hoặc %APPDATA%\Composer\vendor\bin trên Windows) nằm trong PATH của hệ thống.

Trên macOS/Linux, thêm vào ~/.zshrc hoặc ~/.bashrc:

export PATH="$PATH:$HOME/.composer/vendor/bin"

Sau đó reload terminal:

source ~/.zshrc
# hoặc
source ~/.bashrc

Trên Windows, thêm vào biến môi trường PATH:

• Mở System Properties → Environment Variables
• Thêm %APPDATA%\Composer\vendor\bin vào PATH

Tạo ứng dụng Laravel mới

Sau khi cài đặt Laravel Installer, bạn có thể tạo ứng dụng Laravel mới bằng lệnh đơn giản:

laravel new my-laravel-app

Lệnh này sẽ tự động:

• Tạo project Laravel mới với phiên bản mới nhất
• Cài đặt tất cả dependencies thông qua Composer
• Tạo file .env từ .env.example
• Generate application key tự động
• Cấu hình sẵn các thiết lập cần thiết

Quá trình cài đặt

Khi chạy laravel new, quá trình cài đặt sẽ diễn ra:

1. Download Laravel framework: Tải xuống phiên bản Laravel mới nhất
2. Install dependencies: Cài đặt tất cả các packages vào thư mục vendor/
3. Create .env file: Tạo file môi trường từ template
4. Generate application key: Tự động tạo và cấu hình APP_KEY
5. Display success message: Hiển thị thông báo cài đặt thành công

Quá trình này thường mất từ 2-5 phút tùy thuộc vào tốc độ internet và cấu hình máy tính.

Ưu điểm của Laravel Installer

• Được khuyến nghị chính thức: Là phương pháp được đề xuất trong tài liệu Laravel
• Nhanh chóng: Tối ưu hóa cho việc tạo project mới
• Cú pháp đơn giản: Chỉ cần laravel new project-name
• Tự động cấu hình: Tự động setup các cấu hình cần thiết
• Tích hợp sẵn trong Laravel Herd: Nếu sử dụng Herd, Laravel CLI đã được cài đặt sẵn

Phương pháp 2: Cài đặt Laravel qua Composer

Composer là phương pháp phổ biến và đáng tin cậy khác để cài đặt Laravel. Phương pháp này phù hợp khi bạn muốn chỉ định phiên bản Laravel cụ thể hoặc không muốn cài đặt Laravel Installer globally.

Cài đặt Laravel project mới

Để tạo một Laravel project mới bằng Composer:

composer create-project laravel/laravel my-laravel-app

Lệnh này sẽ:

1. Tải xuống Laravel framework mới nhất
2. Cài đặt tất cả các dependencies thông qua Composer
3. Tạo cấu trúc thư mục chuẩn của Laravel
4. Tạo file .env từ .env.example
5. Generate application key tự động

Cài đặt phiên bản Laravel cụ thể

Nếu bạn muốn cài đặt một phiên bản Laravel cụ thể:

composer create-project laravel/laravel my-app "12.*"

Hoặc với Laravel 11:

composer create-project laravel/laravel my-app "11.*"

Với Laravel 10:

composer create-project laravel/laravel my-app "10.*"

Phương pháp 3: Sử dụng Laravel Herd (macOS và Windows)

Laravel Herd là một development environment tích hợp, đơn giản và mạnh mẽ cho macOS và Windows. Herd cung cấp PHP, Nginx, và các công cụ cần thiết đã được cấu hình sẵn, giúp bạn bắt đầu phát triển Laravel ngay lập tức mà không cần cấu hình phức tạp.

Laravel Herd trên macOS

Nếu bạn phát triển trên macOS, bạn có thể tải Laravel Herd từ trang web chính thức của Herd. Installer sẽ tự động tải phiên bản PHP mới nhất và cấu hình Mac của bạn để chạy Nginx trong background.

Herd sử dụng dnsmasq để hỗ trợ "parked" directories. Bất kỳ ứng dụng Laravel nào trong thư mục parked sẽ tự động được phục vụ bởi Herd. Theo mặc định, Herd tạo thư mục parked tại ~/Herd và bạn có thể truy cập bất kỳ ứng dụng Laravel nào trong thư mục này trên domain .test bằng tên thư mục.

Sau khi cài đặt Herd, cách nhanh nhất để tạo ứng dụng Laravel mới là sử dụng Laravel CLI (đã được tích hợp sẵn trong Herd):

cd ~/Herd
laravel new my-app
cd my-app
herd open

Bạn cũng có thể quản lý các thư mục parked và các cài đặt PHP khác thông qua UI của Herd, có thể mở từ menu Herd trong system tray.

Laravel Herd trên Windows

Bạn có thể tải Windows installer cho Herd từ trang web Herd. Sau khi cài đặt xong, bạn có thể khởi động Herd để hoàn tất quá trình onboarding và truy cập Herd UI lần đầu tiên.

Herd UI có thể truy cập bằng cách click trái vào icon Herd trong system tray. Click phải mở menu nhanh với quyền truy cập vào tất cả các công cụ bạn cần hàng ngày.

Trong quá trình cài đặt, Herd tạo thư mục "parked" trong home directory tại %USERPROFILE%\Herd. Bất kỳ ứng dụng Laravel nào trong thư mục parked sẽ tự động được phục vụ bởi Herd, và bạn có thể truy cập bất kỳ ứng dụng Laravel nào trong thư mục này trên domain .test bằng tên thư mục.

Để bắt đầu, mở PowerShell và chạy các lệnh sau:

cd ~\Herd
laravel new my-app
cd my-app
herd open

Ưu điểm của Laravel Herd

• Zero-configuration: Không cần cấu hình PHP, Nginx, hoặc database
• Tự động phát hiện: Tự động phát hiện và phục vụ các ứng dụng Laravel
• Domain .test tự động: Mỗi ứng dụng có domain riêng trên .test
• Laravel CLI tích hợp: Laravel Installer đã được cài đặt sẵn
• UI trực quan: Giao diện đồ họa để quản lý ứng dụng và cài đặt
• Database tích hợp: Bao gồm MySQL, Postgres, và Redis
• Mail và Log viewing: Xem mail và log trực tiếp trong UI

Để tìm hiểu thêm về Herd, hãy xem tài liệu Herd chính thức.

So sánh các phương pháp cài đặt Laravel

Dựa trên tài liệu chính thức Laravel 12.x, đây là bảng so sánh các phương pháp:

Cấu hình sau khi cài đặt

Sau khi cài đặt Laravel thành công, bạn cần thực hiện một số cấu hình cơ bản:

File .env

File .env là file cấu hình môi trường quan trọng nhất của Laravel. File này chứa các thông tin như database connection, application key, cache driver, và nhiều cấu hình khác.

Laravel tự động tạo file .env từ .env.example khi cài đặt, nhưng bạn cần kiểm tra và điều chỉnh các giá trị sau:

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

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

Generate Application Key

Application key được sử dụng để mã hóa dữ liệu trong Laravel. Nếu key chưa được generate, chạy lệnh:

php artisan key:generate

Lệnh này sẽ tự động thêm APP_KEY vào file .env.

Cấu hình Database

Nếu bạn muốn sử dụng database (không bắt buộc cho việc chạy Laravel cơ bản), cần cấu hình thông tin kết nối trong file .env:

1. Tạo database mới (MySQL, PostgreSQL, hoặc SQLite)
2. Cập nhật thông tin trong .env:
   • DB_CONNECTION: Loại database (mysql, pgsql, sqlite)
   • DB_HOST: Địa chỉ host database
   • DB_PORT: Port database
   • DB_DATABASE: Tên database
   • DB_USERNAME: Username database
   • DB_PASSWORD: Password database

Cấu hình Permissions (Linux/macOS)

Trên hệ điều hành Linux hoặc macOS, bạn cần set permissions cho các thư mục storage và bootstrap/cache:

chmod -R 775 storage
chmod -R 775 bootstrap/cache

Hoặc nếu bạn đang chạy trên web server:

sudo chown -R www-data:www-data storage
sudo chown -R www-data:www-data bootstrap/cache

Chạy Laravel Application

Sau khi cài đặt và cấu hình xong, bạn có thể chạy Laravel application theo nhiều cách:

Sử dụng Built-in PHP Server (Development)

Laravel cung cấp một development server built-in rất tiện lợi:

php artisan serve

Lệnh này sẽ khởi động server tại http://localhost:8000. Bạn có thể truy cập ứng dụng Laravel qua trình duyệt.

Để chạy trên port khác:

php artisan serve --port=8080

Hoặc chỉ định host:

php artisan serve --host=0.0.0.0 --port=8000

Kiểm tra cài đặt thành công

Sau khi chạy Laravel, bạn có thể kiểm tra xem cài đặt đã thành công chưa:

1. Truy cập trang chủ: Mở trình duyệt và truy cập http://localhost:8000. Bạn sẽ thấy trang welcome của Laravel với logo và thông tin về framework.

2. Kiểm tra version: Chạy lệnh:

php artisan --version

3. Kiểm tra routes: Xem danh sách routes:

php artisan route:list

4. Kiểm tra environment: Xem thông tin môi trường:

php artisan about

Best Practices khi cài đặt Laravel

Để đảm bảo quá trình cài đặt và phát triển Laravel diễn ra suôn sẻ, hãy tuân theo các best practices sau:

1. Sử dụng PHP Version Manager

Thay vì cài đặt PHP trực tiếp, sử dụng version manager như:

• phpenv (Linux/macOS)
• phpbrew (Linux/macOS)
• XAMPP/WAMP (Windows)

Điều này giúp bạn dễ dàng switch giữa các phiên bản PHP khác nhau cho các projects khác nhau.

2. Sử dụng Virtual Environments

Với Laravel, bạn có thể sử dụng Laravel Sail (Docker) để tạo môi trường development nhất quán:

composer create-project laravel/laravel example-app
cd example-app
./vendor/bin/sail up

Laravel Sail cung cấp môi trường Docker đã được cấu hình sẵn với PHP, MySQL, Redis, và các services khác.

3. Cấu hình Git Ignore

File .gitignore của Laravel đã được cấu hình tốt, nhưng đảm bảo bạn không commit:

• File .env (chứa thông tin nhạy cảm)
• Thư mục vendor/ (dependencies)
• Thư mục node_modules/ (nếu có)

4. Sử dụng Environment Files

Luôn sử dụng file .env cho các cấu hình môi trường. Không hard-code các giá trị như database credentials, API keys vào code.

5. Cập nhật Dependencies thường xuyên

Định kỳ cập nhật dependencies để nhận các security patches và features mới:

composer update

Tuy nhiên, trong production, nên test kỹ trước khi update.

Kết luận

Cài đặt Laravel là bước đầu tiên và quan trọng trong hành trình phát triển ứng dụng web với framework này. Mặc dù quá trình cài đặt khá đơn giản, nhưng việc hiểu rõ các phương pháp cài đặt khác nhau, cách cấu hình môi trường, và cách xử lý các lỗi thường gặp sẽ giúp bạn tiết kiệm thời gian và tránh những rắc rối không cần thiết.

Phương pháp được khuyến nghị nhất là sử dụng Laravel Installer (laravel new) vì đây là cách nhanh chóng, đơn giản và được tối ưu hóa tốt nhất. Nếu bạn mới bắt đầu trên macOS hoặc Windows, Laravel Herd là lựa chọn tuyệt vời với môi trường development zero-configuration.

Sau khi cài đặt thành công, bạn có thể bắt đầu khám phá các tính năng mạnh mẽ của Laravel như routing, Eloquent ORM, Blade templating, và nhiều tính năng khác. Đừng quên cài đặt Node.js/NPM hoặc Bun để compile frontend assets của ứng dụng.

Hãy nhớ rằng Laravel có cộng đồng rất lớn và tài liệu phong phú. Nếu gặp vấn đề, bạn có thể tham khảo Laravel Documentation chính thức hoặc các forums như Laracasts, Laravel News, và Stack Overflow.

Chúc bạn thành công với việc cài đặt và phát triển ứng dụng Laravel!