Contracts

Giới thiệu (Introduction)

"Contracts" trong Laravel là tập hợp các interfaces định nghĩa core services của framework. Ví dụ:

• Illuminate\Contracts\Queue\Queue — định nghĩa methods để queue jobs
• Illuminate\Contracts\Mail\Mailer — định nghĩa methods để gửi email

Mỗi contract có implementation tương ứng do framework cung cấp. Tất cả contracts nằm trong GitHub repository riêng.

Contracts vs. Facades

Facades cung cấp cú pháp ngắn gọn để dùng services mà không cần type-hint trong constructor. Contracts cho phép bạn định nghĩa explicit dependencies cho classes.

Khi nào dùng cái nào?

Tiêu chí	Contracts	Facades
Coupling	Loose coupling — dễ swap implementations	Convenience — ít boilerplate
Testing	Dễ mock qua dependency injection	Dễ mock qua Facade::shouldReceive()
Use case	Packages, libraries tái sử dụng	Application code thông thường

Trong hầu hết ứng dụng, cả hai đều hoạt động tốt. Lựa chọn tùy thuộc vào preferences của team.

Khi nào dùng Contracts (When to Use Contracts)

Sử dụng Contracts khi bạn muốn:

1. Loose coupling — dễ dàng thay đổi implementation
2. Simplicity — khi classes có ít dependencies

Cách sử dụng Contracts (How to Use Contracts)

Type-hint interface trong constructor:

<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * Tạo instance mới.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // Dùng $this->redis...
    }
}

Service container tự động resolve implementation tương ứng.

Contract Reference

Bảng tham chiếu contracts phổ biến:

Contract	Facade tương ứng
Illuminate\Contracts\Auth\Factory	Auth
Illuminate\Contracts\Auth\Guard	Auth::guard()
Illuminate\Contracts\Bus\Dispatcher	Bus
Illuminate\Contracts\Cache\Factory	Cache
Illuminate\Contracts\Cache\Repository	Cache::driver()
Illuminate\Contracts\Config\Repository	Config
Illuminate\Contracts\Cookie\Factory	Cookie
Illuminate\Contracts\Database\Events\MigrationEvent	—
Illuminate\Contracts\Encryption\Encrypter	Crypt
Illuminate\Contracts\Events\Dispatcher	Event
Illuminate\Contracts\Filesystem\Cloud	Storage::cloud()
Illuminate\Contracts\Filesystem\Factory	Storage
Illuminate\Contracts\Filesystem\Filesystem	Storage::disk()
Illuminate\Contracts\Hashing\Hasher	Hash
Illuminate\Contracts\Http\Kernel	App
Illuminate\Contracts\Mail\Mailer	Mail
Illuminate\Contracts\Notifications\Factory	Notification
Illuminate\Contracts\Queue\Factory	Queue
Illuminate\Contracts\Queue\Queue	Queue::connection()
Illuminate\Contracts\Redis\Factory	Redis
Illuminate\Contracts\Routing\Registrar	Route
Illuminate\Contracts\Routing\ResponseFactory	Response
Illuminate\Contracts\Routing\UrlGenerator	URL
Illuminate\Contracts\Session\Session	Session::driver()
Illuminate\Contracts\Translation\Translator	Lang
Illuminate\Contracts\Validation\Factory	Validator
Illuminate\Contracts\View\Factory	View