Giới thiệu

Thay vì định nghĩa tất cả các logic xử lý cho request trong file route của bạn với closures, thì bạn có thể muốn tổ chức các hành vi này bằng cách sử dụng class "controller". Các controller có thể nhóm các logic xử lý request có liên quan đến nhau thành một class duy nhất. Ví dụ: class UserController có thể xử lý tất cả các request liên quan đến người dùng, bao gồm hiển thị, tạo, cập nhật và xóa người dùng. Mặc định, controller sẽ được lưu trong thư mục app/Http/Controllers.

Viết controllers

Controller cơ bản

Để nhanh chóng tạo một controller mới, bạn có thể chạy lệnh Artisan make:controller. Mặc định, tất cả các controller cho ứng dụng của bạn sẽ được lưu trữ trong thư mục app/Http/Controllers:

php artisan make:controller UserController

Chúng ta hãy xem một ví dụ về một controller cơ bản. Controller có thể có nhiều phương thức public và nó sẽ trả về các respond cho các request HTTP đến:

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show the profile for a given user.
     */
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => User::findOrFail($id)
        ]);
    }
}

Sau khi bạn đã định nghĩa một class controller và phương thức của nó, bạn có thể định nghĩa một route tới một phương thức của controller như sau:

use App\Http\Controllers\UserController;

Route::get('/user/{id}', [UserController::class, 'show']);

Khi một request khớp với URI route đã chỉ định, phương thức show trên class App\Http\Controllers\UserController sẽ được gọi và các tham số route sẽ được truyền cho phương thức.

[!NOTE] Các controller không bắt buộc phải extend từ một class base. Tuy nhiên, đôi khi nó sẽ hiệu quả hơn khi extend class controller base có chứa các phương thức cần được chia sẻ cho tất cả các controller của bạn.

Single Action Controllers

Nếu một controller action đặc biệt phức tạp, bạn có thể thấy thuận tiện khi dành toàn bộ class controller đó cho một action. Để thực hiện điều này, bạn có thể định nghĩa một phương thức __invoke trong controller:

<?php

namespace App\Http\Controllers;

class ProvisionServer extends Controller
{
    /**
     * Provision a new web server.
     */
    public function __invoke()
    {
        // ...
    }
}

Khi đăng ký route cho một single action controller, bạn sẽ không cần phải khai báo thêm tên phương thức của controller nữa. Thay vào đó, bạn có thể chỉ cần truyền tên của controller đó cho router:

use App\Http\Controllers\ProvisionServer;

Route::post('/server', ProvisionServer::class);

Bạn có thể tạo một controller chỉ có một action duy nhất bằng cách sử dụng tùy chọn --invokable trong lệnh Artisan make:controller:

php artisan make:controller ProvisionServer --invokable

[!NOTE] Bạn có thể tùy chỉnh các stub của controller bằng cách export chúng.

Controller Middleware

Middleware có thể được gán vào route của controller trong file route của bạn:

Route::get('/profile', [UserController::class, 'show'])->middleware('auth');

Hoặc, bạn có thể thấy thuận tiện hơn khi khai báo middleware đó trong class controller của bạn. Để làm như vậy, controller của bạn phải implement interface HasMiddleware, interface này sẽ quy định controller phải có một phương thức static middleware. Từ phương thức này, bạn có thể trả về một mảng middleware cần được áp dụng cho các hành động của controller:

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

class UserController implements HasMiddleware
{
    /**
     * Get the middleware that should be assigned to the controller.
     */
    public static function middleware(): array
    {
        return [
            'auth',
            new Middleware('log', only: ['index']),
            new Middleware('subscribed', except: ['store']),
        ];
    }

    // ...
}

Bạn cũng có thể định nghĩa middleware cho controller dưới dạng closure, đây là cách thuận tiện để định nghĩa middleware ngay trong controller mà không cần viết toàn bộ class middleware:

use Closure;
use Illuminate\Http\Request;

/**
 * Get the middleware that should be assigned to the controller.
 */
public static function middleware(): array
{
    return [
        function (Request $request, Closure $next) {
            return $next($request);
        },
    ];
}

Thuộc tính middleware

Bạn cũng có thể gán middleware cho các controller bằng cách sử dụng thuộc tính PHP:

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
#[Middleware('log', only: ['index'])]
#[Middleware('subscribed', except: ['store'])]
class UserController
{
    // ...
}

Bạn cũng có thể đặt các thuộc tính middleware trên từng phương thức của controller. Những middleware đã được gán cho các phương thức sẽ được nối vào các middleware đã được gán ở class:

<?php

namespace App\Http\Controllers;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
class UserController
{
    #[Middleware('log')]
    #[Middleware('subscribed')]
    public function index()
    {
        // ...
    }

    #[Middleware(static function (Request $request, Closure $next) {
        // ...

        return $next($request);
    })]
    public function store()
    {
        // ...
    }
}

Thuộc tính authorization

Nếu bạn đang authorize các action của controller thông qua các policy, bạn có thể sử dụng thuộc tính Authorize như một lối tắt thuận tiện cho middleware can:

<?php

namespace App\Http\Controllers;

use App\Models\Comment;
use App\Models\Post;
use Illuminate\Routing\Attributes\Controllers\Authorize;

class CommentController
{
    #[Authorize('create', [Comment::class, 'post'])]
    public function store(Post $post)
    {
        // ...
    }

    #[Authorize('delete', 'comment')]
    public function destroy(Comment $comment)
    {
        // ...
    }
}

Tham số đầu tiên là hành động mà bạn muốn authorize. Tham số thứ hai có thể là class model, tham số route hoặc các tham số cần thiết khác cần được truyền cho policy.

Resource Controllers

Nếu bạn coi mỗi model Eloquent trong ứng dụng của bạn là một "resource", thì thông thường bạn sẽ thực hiện nhiều hành động giống nhau cho từng resource trong ứng dụng của bạn. Ví dụ: hãy tưởng tượng ứng dụng của bạn chứa một model Photo và một model Movie. Và người dùng có thể tạo, đọc, cập nhật hoặc xóa các resource này.

Do đây là những trường hợp rất hay sử dụng, nên route của Laravel resource sẽ chỉ định các route tạo, đọc, cập nhật và xóa ("CRUD") mặc định cho controller với một số dòng code mặc định. Để bắt đầu, chúng ta có thể sử dụng tùy chọn --resource của lệnh make:controller Artisan để nhanh chóng tạo một controller để xử lý các hành động này:

php artisan make:controller PhotoController --resource

Lệnh này sẽ tạo ra một controller tại app/Http/Controllers/PhotoController.php. Controller này sẽ chứa một phương thức cho mỗi hành động resource có sẵn. Tiếp theo, bạn có thể đăng ký một resource route trỏ đến controller:

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class);

Khai báo một single route như ở trên sẽ tạo ra một loạt route để xử lý một loạt các hành động khác nhau trên resource. Controller đã được tạo sẽ có sẵn luôn các phương thức cho từng hành động này. Hãy nhớ rằng, bạn luôn có thể xem qua các route của ứng dụng của bạn bằng cách chạy lệnh route:list Artisan.

Bạn thậm chí có thể đăng ký nhiều resource controller cùng một lúc bằng cách truyền vào một mảng cho phương thức resources:

Route::resources([
    'photos' => PhotoController::class,
    'posts' => PostController::class,
]);

Phương thức softDeletableResources sẽ đăng ký nhiều resource controller mà tất cả chúng đều sử dụng phương thức withTrashed:

Route::softDeletableResources([
    'photos' => PhotoController::class,
    'posts' => PostController::class,
]);

Các hành động được xử lý bởi Resource Controller

Customizing Missing Model Behavior

Thông thường, response HTTP 404 sẽ được tạo nếu không tìm thấy resource model mà ràng buộc ngầm. Tuy nhiên, bạn có thể tùy chỉnh hành động này bằng cách gọi phương thức missing khi định nghĩa resource route của bạn. Phương thức missing sẽ chấp nhận một closure sẽ được gọi đến nếu không thể tìm thấy một model khi ràng buộc ngầm cho bất kỳ route nào cho resource:

use App\Http\Controllers\PhotoController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redirect;

Route::resource('photos', PhotoController::class)
    ->missing(function (Request $request) {
        return Redirect::route('photos.index');
    });

Soft Deleted Models

Thông thường, liên kết model ẩn sẽ không thể lấy ra các model đã bị soft delete và thay vào đó sẽ trả về response HTTP 404. Tuy nhiên, bạn có thể hướng dẫn framework cho phép lấy ra các model bị soft delete bằng cách gọi phương thức withTrashed khi định nghĩa route resource của bạn:

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->withTrashed();

Việc gọi withTrashed không có tham số sẽ cho phép lấy ra các model bị soft delete cho các route resource show, edit và update. Bạn có thể chỉ định một tập con của các route bằng cách truyền một mảng tới phương thức withTrashed:

Route::resource('photos', PhotoController::class)->withTrashed(['show']);

Khai báo Resource Model

Nếu bạn đang sử dụng liên kết model route và muốn các phương thức của resource controller khai báo sẵn một tham số đầu vào là một model instance, bạn có thể sử dụng tùy chọn --model khi tạo controller:

php artisan make:controller PhotoController --model=Photo --resource

Generating Form Requests

Bạn có thể cung cấp tùy chọn --requests khi tạo resource controller để hướng dẫn Artisan tạo các class request validation form cho các phương thức cập nhật và lưu trữ của controller:

php artisan make:controller PhotoController --model=Photo --resource --requests

Partial Resource Routes

Khi khai báo một resource route, bạn có thể chỉ định một tập hợp các hành động mà được controller xử lý thay vì toàn bộ các hành động mặc định:

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->only([
    'index', 'show'
]);

Route::resource('photos', PhotoController::class)->except([
    'create', 'store', 'update', 'destroy'
]);

API Resource Routes

Khi khai báo một resource route mà sẽ được sử dụng bởi các API, bạn sẽ muốn loại bỏ các route mà phải nhập form HTML như create vàedit. Để thuận tiện, bạn có thể sử dụng phương thức apiResource để tự động loại bỏ hai route trên:

use App\Http\Controllers\PhotoController;

Route::apiResource('photos', PhotoController::class);

Bạn có thể đăng ký nhiều resource controller cho API cùng một lúc bằng cách truyền một mảng vào phương thức apiResources:

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\PostController;

Route::apiResources([
    'photos' => PhotoController::class,
    'posts' => PostController::class,
]);

Để tạo nhanh một API resource controller mà không chứa các phương thức create hoặc edit, hãy sử dụng switch --api khi chạy lệnh make:controller:

php artisan make:controller PhotoController --api

Nested Resources

Thỉnh thoảng bạn có thể cần định nghĩa các route đến một resource lồng nhau. Ví dụ: một resource photo có thể có nhiều nhận xét được đính kèm vào ảnh. Để lồng các resource controller, bạn có thể sử dụng ký tự "chấm" trong khai báo route của bạn:

use App\Http\Controllers\PhotoCommentController;

Route::resource('photos.comments', PhotoCommentController::class);

Route này sẽ đăng ký một resource có thể truy cập được bằng các URI như sau:

/photos/{photo}/comments/{comment}

Scoping Nested Resources

Chức năng liên kết ngầm model của Laravel có thể tự động xác định scope của các liên kết lồng nhau, sao cho các model con đã được resolve thì sẽ được xác nhận là thuộc về model cha. Bằng cách sử dụng phương thức scoped khi định nghĩa resource lồng nhau, bạn có thể bật chế độ scope tự động cũng như hướng dẫn Laravel, trường nào của resource con sẽ được lấy ra. Để biết thêm thông tin về cách thực hiện việc này, vui lòng xe thêm tài liệu về route resource theo scope.

Shallow Nesting

Thông thường, không nhất thiết phải có cả ID cha và ID con trong một URI vì ID con có thể có chứa ID của cha. Khi sử dụng ID, chẳng hạn như một khóa chính tự động tăng dần để xác định model của bạn trong các phân đoạn URI, bạn có thể chọn sử dụng "shallow nesting":

use App\Http\Controllers\CommentController;

Route::resource('photos.comments', CommentController::class)->shallow();

Định nghĩa route này sẽ định nghĩa ra các route như sau:

Naming Resource Routes

Mặc định, tất cả các hành động của resource controller đều có đi kèm với một tên route; tuy nhiên, bạn có thể ghi đè các tên này bằng cách truyền vào một mảng names cùng với tên route mà bạn mong muốn:

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->names([
    'create' => 'photos.build'
]);

Naming Resource Route Parameters

Mặc định, Route::resource sẽ tạo các tham số route cho các resource route dựa trên tên "số ít" của các resource. Bạn có thể dễ dàng ghi đè điều này trên từng resource bằng cách sử dụng phương thức parameters. Mảng được truyền cho phương thức parameters này phải là một mảng kết hợp giữa tên resource và tên tham số:

use App\Http\Controllers\AdminUserController;

Route::resource('users', AdminUserController::class)->parameters([
    'users' => 'admin_user'
]);

Ví dụ ở trên sẽ tạo ra một URI như ở dưới cho một route show của resource:

/users/{admin_user}

Scoping Resource Routes

Chức năng scope liên kết ngầm model của Laravel có thể tự động xác định scope của các liên kết lồng nhau, sao cho các model con đã được resolve thì sẽ được xác nhận là thuộc về model cha. Bằng cách sử dụng phương thức scoped khi định nghĩa resource lồng nhau, bạn có thể bật chế độ scope tự động cũng như hướng dẫn Laravel, trường nào của resource con sẽ được lấy ra bằng:

use App\Http\Controllers\PhotoCommentController;

Route::resource('photos.comments', PhotoCommentController::class)->scoped([
    'comment' => 'slug',
]);

Route này sẽ đăng ký một scoped nested resource có thể được truy cập bằng các URI như sau:

/photos/{photo}/comments/{comment:slug}

Khi sử dụng liên kết ngầm có key tùy biến làm một tham số route lồng nhau, Laravel sẽ tự động scope truy vấn để lấy ra các model lồng nhau thông qua cha của nó bằng cách sử dụng các quy ước để đặt tên quan hệ trên cha. Trong trường hợp này, sẽ giả định rằng model Photo có một quan hệ có tên là comments (số nhiều của tên tham số route) có thể được sử dụng để lấy ra model Comment.

Localizing Resource URIs

Mặc định, Route::resource sẽ tạo các URI resource bằng các động từ và quy tắc số nhiều trong tiếng Anh. Nếu bạn cần bản địa hóa các động từ này như create và edit, bạn có thể sử dụng phương thức Route::resourceVerbs. Điều này có thể được thực hiện ở đầu của phương thức boot trong App\Providers\AppServiceProvider của ứng dụng của bạn:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);
}

Bộ quy tắc số nhiều của Laravel hỗ trợ một số ngôn ngữ khác nhau mà bạn có thể cấu hình dựa trên nhu cầu của bạn. Khi các động từ và quy tắc số nhiều đã được tùy biến xong, nếu bạn đăng ký resource route là Route::resource('publicacion', PublicacionController::class) thì sẽ tạo ra các URI như sau:

/publicacion/crear

/publicacion/{publicaciones}/editar

Supplementing Resource Controllers

Nếu bạn cần thêm các route vào các resource controller ngoài các route mặc định, bạn nên định nghĩa các route đó trước khi gọi tới phương thức Route::resource; Mặt khác, các route được định nghĩa bởi phương thức resource có thể vô tình được ưu tiên hơn các route vừa được thêm của bạn:

use App\Http\Controller\PhotoController;

Route::get('/photos/popular', [PhotoController::class, 'popular']);
Route::resource('photos', PhotoController::class);

[!NOTE] Hãy nhớ giữ cho controller của bạn được tập trung. Nếu bạn cảm thấy bạn thường xuyên cần phải thêm các phương thức bên ngoài bộ resource action mặc định, hãy xem xét việc chia controller của bạn thành hai controller nhỏ hơn.

Singleton Resource Controllers

Thỉnh thoảng, ứng dụng của bạn sẽ có các resources mà chỉ có thể có một instance duy nhất. Ví dụ: "profile" của người dùng có thể được chỉnh sửa hoặc cập nhật, nhưng một người dùng chỉ thể có nhiều nhất một "profile". Tương tự như vậy, một hình ảnh có thể có một "hình thu nhỏ". Những resources này được gọi là "resources singleton", nghĩa là một và chỉ một instance của resources có thể tồn tại. Trong những trường hợp như thế này, bạn có thể đăng ký resource controller "singleton":

use App\Http\Controllers\ProfileController;
use Illuminate\Support\Facades\Route;

Route::singleton('profile', ProfileController::class);

Định nghĩa resources singleton ở trên sẽ tạo ra các đăng ký route như sau. Như bạn có thể thấy, các route "creation" không được đăng ký cho các resources singleton và các route đã đăng ký sẽ không chấp nhận id vì chỉ có một instance của resource có thể tồn tại:

Resources singleton cũng có thể được lồng trong một resource tiêu chuẩn:

Route::singleton('photos.thumbnail', ThumbnailController::class);

Trong ví dụ này, resource photos sẽ nhận được tất cả route resource tiêu chuẩn; tuy nhiên, resource thumbnail sẽ là resource singleton với các route như sau:

Creatable Singleton Resources

Đôi khi, bạn có thể muốn định nghĩa thêm các route creation và storage cho một resource singleton. Để thực hiện điều này, bạn có thể gọi phương thức creatable khi đăng ký route resource singleton:

Route::singleton('photos.thumbnail', ThumbnailController::class)->creatable();

Trong ví dụ này, các route sau sẽ được đăng ký. Như bạn có thể thấy, route DELETE cũng sẽ được đăng ký cho các resource singleton:

Nếu bạn muốn Laravel đăng ký route DELETE cho một resource singleton nhưng không đăng ký các route creation hoặc storage khác, bạn có thể sử dụng phương thức destroyable:

Route::singleton(...)->destroyable();

API Singleton Resources

Phương thức apiSingleton có thể được sử dụng để đăng ký một resource singleton sẽ được thao tác thông qua API, và do đó các route create và edit sẽ trở nên không cần thiết:

Route::apiSingleton('profile', ProfileController::class);

Tất nhiên, các resource singleton API cũng có thể là loại creatable, sẽ đăng ký các route store và destroy cho resource:

Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();

Middleware and Resource Controllers

Laravel cho phép bạn gán middleware cho tất cả, hoặc chỉ một số phương thức nhất định của các resource route bằng cách sử dụng các phương thức middleware, middlewareFor, và withoutMiddlewareFor. Các phương thức này cung cấp khả năng kiểm soát chi tiết về việc middleware nào sẽ được áp dụng cho từng action của resource.

Applying Middleware to all Methods

Bạn có thể sử dụng phương thức middleware để gán middleware cho tất cả các route được tạo bởi một resource hoặc một singleton resource route:

Route::resource('users', UserController::class)
    ->middleware(['auth', 'verified']);

Route::singleton('profile', ProfileController::class)
    ->middleware('auth');

Applying Middleware to Specific Methods

Bạn có thể sử dụng phương thức middlewareFor để gán middleware cho một hoặc nhiều phương thức cụ thể của một resource controller nhất định:

Route::resource('users', UserController::class)
    ->middlewareFor('show', 'auth');

Route::apiResource('users', UserController::class)
    ->middlewareFor(['show', 'update'], 'auth');

Route::resource('users', UserController::class)
    ->middlewareFor('show', 'auth')
    ->middlewareFor('update', 'auth');

Route::apiResource('users', UserController::class)
    ->middlewareFor(['show', 'update'], ['auth', 'verified']);

Phương thức middlewareFor cũng có thể được kết hợp với các resource controller singleton và API singleton:

Route::singleton('profile', ProfileController::class)
    ->middlewareFor('show', 'auth');

Route::apiSingleton('profile', ProfileController::class)
    ->middlewareFor(['show', 'update'], 'auth');

Excluding Middleware from Specific Methods

Bạn có thể sử dụng phương thức withoutMiddlewareFor để loại bỏ middleware ra khỏi các phương thức nhất định của một resource controller:

Route::middleware(['auth', 'verified', 'subscribed'])->group(function () {
    Route::resource('users', UserController::class)
        ->withoutMiddlewareFor('index', ['auth', 'verified'])
        ->withoutMiddlewareFor(['create', 'store'], 'verified')
        ->withoutMiddlewareFor('destroy', 'subscribed');
});

Dependency Injection và Controllers

Constructor Injection

Laravel service container sẽ được sử dụng để resolve tất cả các controller của Laravel. Kết quả là, bạn có thể khai báo cho bất kỳ phụ thuộc nào mà controller của bạn cần trong hàm khởi tạo của nó. Các phụ thuộc được khai báo sẽ tự động được resolve và được đưa vào trong controller instance:

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Create a new controller instance.
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

Method Injection

Ngoài việc khai báo vào hàm khởi tạo class, bạn cũng có thể khai báo sự phụ thuộc vào trực tiếp các phương thức của controller. Một trường hợp được sử dụng phổ biến cho việc khai báo theo kiểu này là việc khai báo instance Illuminate\Http\Request cho các phương thức controller của bạn:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Store a new user.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->name;

        // Store the user...

        return redirect('/users');
    }
}

Nếu phương thức controller của bạn cũng đang sử dụng các tham số route, bạn có thể liệt kê các tham số đó sau các phụ thuộc của bạn. Ví dụ: nếu route của bạn đang được định nghĩa như sau:

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

Thì bạn vẫn có thể khai báo Illuminate\Http\Request và truy cập tham số id của bạn bằng cách định nghĩa phương thức controller của bạn như thế này:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Update the given user.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // Update the user...

        return redirect('/users');
    }
}