Cấu trúc Thư mục (Directory Structure)

Giới thiệu (Introduction)

Cấu trúc thư mục mặc định của Laravel được thiết kế để cung cấp điểm khởi đầu tuyệt vời cho cả ứng dụng lớn và nhỏ. Nhưng bạn hoàn toàn tự do tổ chức ứng dụng theo cách bạn muốn. Laravel gần như không áp đặt giới hạn về vị trí của bất kỳ class nào — miễn là Composer có thể autoload class đó.

Thư mục gốc (The Root Directory)

Thư mục app

Thư mục app chứa code cốt lõi của ứng dụng. Chúng ta sẽ khám phá thư mục này chi tiết hơn bên dưới; tuy nhiên, hầu hết tất cả các class trong ứng dụng sẽ nằm trong thư mục này.

Thư mục bootstrap

Thư mục bootstrap chứa file app.php dùng để khởi động (bootstrap) framework. Thư mục này cũng chứa thư mục cache lưu trữ các file do framework tạo ra để tối ưu hiệu năng, như file cache routes và services.

Thư mục config

Thư mục config, đúng như tên gọi, chứa tất cả file cấu hình của ứng dụng. Bạn nên đọc qua tất cả các file này để làm quen với các tùy chọn có sẵn.

Thư mục database

Thư mục database chứa các database migrations, model factories và seeds. Nếu muốn, bạn cũng có thể sử dụng thư mục này để lưu database SQLite.

Thư mục public

Thư mục public chứa file index.php — điểm vào (entry point) cho tất cả requests đến ứng dụng và cấu hình autoloading. Thư mục này cũng lưu các tài nguyên (assets) như hình ảnh, JavaScript và CSS.

Thư mục resources

Thư mục resources chứa các views cũng như các tài nguyên thô, chưa biên dịch như CSS hoặc JavaScript.

Thư mục routes

Thư mục routes chứa tất cả định nghĩa route cho ứng dụng. Mặc định, Laravel bao gồm hai file route: web.php và console.php.

File web.php chứa các routes mà Laravel đặt trong nhóm middleware web, cung cấp session state, bảo vệ CSRF và mã hóa cookie. Nếu ứng dụng không cung cấp API stateless, RESTful thì tất cả routes rất có thể sẽ được định nghĩa trong file web.php.

File console.php là nơi bạn định nghĩa tất cả console commands dạng closure. Mỗi closure được gắn với một command instance cho phép tương tác đơn giản với các method I/O của command. Dù file này không định nghĩa HTTP routes, nó định nghĩa các entry points (routes) dạng console vào ứng dụng. Bạn cũng có thể lập lịch các tác vụ trong file console.php.

Tùy chọn, bạn có thể cài thêm file route cho API routes (api.php) và broadcasting channels (channels.php) thông qua lệnh Artisan install:api và install:broadcasting.

File api.php chứa các routes dự kiến là stateless, nên requests đến ứng dụng qua các routes này sẽ được xác thực qua tokens và không truy cập session state.

File channels.php là nơi bạn đăng ký tất cả event broadcasting channels mà ứng dụng hỗ trợ.

Thư mục storage

Thư mục storage chứa logs, Blade templates đã biên dịch, file-based sessions, file caches và các file khác do framework tạo ra. Thư mục này được chia thành các thư mục app, framework và logs. Thư mục app dùng để lưu bất kỳ file nào do ứng dụng tạo ra. Thư mục framework lưu file và caches do framework tạo. Cuối cùng, thư mục logs chứa file log của ứng dụng.

Thư mục storage/app/public có thể dùng để lưu file do người dùng tạo, chẳng hạn avatar, cần truy cập công khai. Bạn nên tạo symbolic link tại public/storage trỏ đến thư mục này. Bạn có thể tạo link bằng lệnh:

php artisan storage:link

Thư mục tests

Thư mục tests chứa các bài kiểm thử tự động (automated tests). Các ví dụ Pest hoặc PHPUnit unit tests và feature tests được cung cấp sẵn. Mỗi test class nên có hậu tố Test. Bạn có thể chạy tests bằng lệnh /vendor/bin/pest hoặc /vendor/bin/phpunit. Hoặc nếu muốn kết quả chi tiết và trực quan hơn:

php artisan test

Thư mục vendor

Thư mục vendor chứa các Composer dependencies.

Thư mục App (The App Directory)

Phần lớn ứng dụng của bạn nằm trong thư mục app. Mặc định, thư mục này được namespaced dưới App và được Composer autoload sử dụng chuẩn PSR-4 autoloading.

Mặc định, thư mục app chứa các thư mục Http, Models và Providers. Tuy nhiên, theo thời gian, nhiều thư mục khác sẽ được tạo bên trong khi bạn sử dụng lệnh Artisan make để tạo class. Ví dụ, thư mục app/Console sẽ không tồn tại cho đến khi bạn chạy lệnh make:command.

Cả thư mục Console và Http đều cung cấp API truy cập vào phần cốt lõi của ứng dụng. Giao thức HTTP và CLI đều là cơ chế tương tác với ứng dụng, nhưng thực tế không chứa logic nghiệp vụ. Nói cách khác, chúng là hai cách phát lệnh cho ứng dụng.

GỢI Ý

Nhiều class trong thư mục app có thể được tạo bằng lệnh Artisan. Để xem các lệnh có sẵn, chạy php artisan list make trong terminal.

Thư mục Broadcasting

Chứa tất cả broadcast channel classes cho ứng dụng. Được tạo bằng lệnh make:channel. Thư mục này không tồn tại mặc định, nhưng sẽ được tạo khi bạn tạo channel đầu tiên. Tìm hiểu thêm tại event broadcasting.

Thư mục Console

Chứa tất cả Artisan commands tùy chỉnh. Được tạo bằng lệnh make:command.

Thư mục Events

Không tồn tại mặc định, được tạo bằng lệnh event:generate hoặc make:event. Chứa các event classes. Events dùng để thông báo cho các phần khác của ứng dụng rằng một hành động đã xảy ra, cung cấp tính linh hoạt và giảm coupling (sự phụ thuộc lẫn nhau).

Thư mục Exceptions

Chứa tất cả exception tùy chỉnh. Được tạo bằng lệnh make:exception.

Thư mục Http

Chứa controllers, middleware và form requests. Hầu hết logic xử lý requests đến ứng dụng sẽ được đặt tại đây.

Thư mục Jobs

Không tồn tại mặc định, được tạo bằng lệnh make:job. Chứa các queueable jobs cho ứng dụng. Jobs có thể được đưa vào queue hoặc chạy đồng bộ trong vòng đời request hiện tại. Jobs chạy đồng bộ đôi khi được gọi là "commands" vì chúng là triển khai của command pattern.

Thư mục Listeners

Không tồn tại mặc định, được tạo bằng lệnh event:generate hoặc make:listener. Chứa các class xử lý events. Event listeners nhận event instance và thực hiện logic phản hồi khi event được phát. Ví dụ, event UserRegistered có thể được xử lý bởi listener SendWelcomeEmail.

Thư mục Mail

Không tồn tại mặc định, được tạo bằng lệnh make:mail. Chứa tất cả class đại diện cho email mà ứng dụng gửi đi. Mail objects cho phép bạn đóng gói toàn bộ logic xây dựng email trong một class đơn giản, có thể gửi bằng method Mail::send.

Thư mục Models

Chứa tất cả Eloquent model classes. Eloquent ORM đi kèm với Laravel cung cấp triển khai ActiveRecord đẹp và đơn giản để làm việc với database. Mỗi bảng database có một "Model" tương ứng dùng để tương tác với bảng đó. Models cho phép bạn truy vấn dữ liệu và thêm bản ghi mới.

Thư mục Notifications

Không tồn tại mặc định, được tạo bằng lệnh make:notification. Chứa tất cả notifications "transactional" mà ứng dụng gửi đi. Tính năng notification của Laravel trừu tượng hóa việc gửi thông báo qua nhiều drivers như email, Slack, SMS hoặc lưu trong database.

Thư mục Policies

Không tồn tại mặc định, được tạo bằng lệnh make:policy. Chứa các authorization policy classes. Policies dùng để xác định liệu người dùng có thể thực hiện hành động cụ thể trên tài nguyên hay không.

Thư mục Providers

Chứa tất cả service providers cho ứng dụng. Service providers khởi động ứng dụng bằng cách binding services vào service container, đăng ký events, hoặc thực hiện các tác vụ khác để chuẩn bị ứng dụng nhận requests.

Trong ứng dụng Laravel mới, thư mục này đã chứa sẵn AppServiceProvider. Bạn có thể tự do thêm providers khác khi cần.

Thư mục Rules

Không tồn tại mặc định, được tạo bằng lệnh make:rule. Chứa các custom validation rule objects. Rules dùng để đóng gói logic validation phức tạp trong một object đơn giản. Xem thêm tại tài liệu validation.