Middleware Laravel: Memahami Alur Request dan `$next($request)`

Ketika setiap request perlu melewati aturan yang sama—misalnya memeriksa header tertentu atau menambahkan keputusan awal sebelum aplikasi memprosesnya—menaruh aturan itu berulang kali di banyak controller cepat membuat alurnya sulit dirawat. Middleware Laravel memberi satu batas khusus untuk memeriksa request sebelum request diteruskan atau dihentikan.

Model mental yang perlu diingat hanya satu: middleware menerima request, mengambil keputusan, lalu memilih antara meneruskan $next($request) atau mengembalikan response sendiri. Artikel ini menunjukkan satu middleware kustom dan satu cara mendaftarkannya secara global pada Laravel 13.x. Contoh bersifat dokumentasi-guided dan belum dijalankan pada proyek lokal.

Apa yang dilakukan middleware di dalam alur HTTP?

Middleware berada di antara request HTTP yang masuk dan bagian aplikasi yang akan menanganinya. Ia dapat memeriksa atau mengubah request sebelum request berjalan lebih jauh. Ia juga dapat memeriksa response setelah lapisan berikutnya selesai, jika kebutuhan aplikasi memang memerlukannya.

Ada dua keputusan utama:

• return $next($request); meneruskan request ke middleware berikutnya atau ke handler aplikasi yang lebih dalam.
• return dengan response lain menghentikan alur pada titik tersebut. Response itu dapat berupa penolakan atau pengalihan sesuai aturan aplikasi.

Jadi, middleware bukan sekadar fungsi yang “selalu berjalan lalu lanjut”. Ia adalah titik keputusan. Jika syarat terpenuhi, alur bergerak ke dalam. Jika tidak, middleware dapat mengembalikan response yang terbatas tanpa meneruskan request.

Contoh satu aturan di batas request

Bayangkan sebuah aplikasi internal yang hanya ingin meneruskan request jika header X-Workspace memiliki nilai. Contoh ini hanya untuk menjelaskan alur middleware; nama header, nilai yang sah, dan response yang tepat tetap merupakan keputusan aplikasi.

Buat middleware dengan Artisan:

php artisan make:middleware EnsureWorkspaceIsPresent

Perintah di atas mengikuti dokumentasi Laravel, tetapi tidak dijalankan untuk artikel ini. Isi minimal middleware dapat ditulis seperti berikut:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureWorkspaceIsPresent
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->hasHeader('X-Workspace')) {
            return response('Workspace header is required.', 400);
        }

        return $next($request);
    }
}

Cara membacanya:

1. handle menerima request dan closure $next.
2. Middleware memeriksa apakah header yang dibutuhkan tersedia.
3. Jika header tidak ada, middleware langsung mengembalikan response dengan status 400.
4. Jika header ada, $next($request) meneruskan request ke bagian alur berikutnya.

Response 400 di sini adalah contoh keputusan yang dibatasi. Ia bukan rekomendasi universal untuk semua aturan header, dan contoh ini tidak membuktikan bahwa request benar-benar berhasil pada aplikasi tertentu.

Mendaftarkan middleware sebagai global

Satu middleware dapat dipasang pada route tertentu, group, atau seluruh request. Agar fokus tetap pada satu registration path, contoh ini memakai global middleware. Laravel 13.x mendokumentasikan konfigurasi middleware global melalui bootstrap/app.php dan withMiddleware.

<?php

use App\Http\Middleware\EnsureWorkspaceIsPresent;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(EnsureWorkspaceIsPresent::class);
    })
    // konfigurasi aplikasi lain tetap di sini
    ->create();

Dengan append, middleware ditambahkan ke global middleware stack sesuai konfigurasi aplikasi. Dampaknya lebih luas daripada menempelkan middleware pada satu route: request yang masuk ke aplikasi dapat melewati aturan ini. Karena itu, global registration hanya masuk akal bila aturan tersebut memang lintas-request dan tidak seharusnya diterapkan pada sebagian route saja.

Contoh ini tidak membahas urutan lengkap stack aplikasi. Posisi relatif middleware dapat dipengaruhi konfigurasi dan kebutuhan aplikasi, sehingga jangan menyimpulkan urutan universal hanya dari contoh global registration.

Kapan memakai global, group, atau route?

Pemilihan tempat registrasi sebaiknya mengikuti cakupan aturan:

• Global: aturan memang perlu dipertimbangkan pada setiap HTTP request.
• Group: aturan berlaku untuk kelompok route yang memiliki konteks sama.
• Route: aturan hanya relevan pada endpoint atau sekumpulan endpoint tertentu.

Artikel ini hanya mengimplementasikan global registration. Route dan group disebut sebagai alternatif cakupan, bukan tutorial API lengkap. Jika aturan hanya diperlukan pada area tertentu, mendaftarkannya secara lebih sempit dapat membuat batas perilakunya lebih mudah dibaca.

Bedakan middleware dari aturan aplikasi lain

Middleware cocok untuk keputusan di batas request, tetapi bukan tempat otomatis untuk semua logika aplikasi. Pemeriksaan header pada contoh hanya menunjukkan kapan request diteruskan atau dihentikan.

Middleware bukan tutorial autentikasi, desain policy atau gate authorization, validasi seluruh payload, controller, ataupun API. Authentication dan authorization dapat menjadi contoh konteks yang berbeda, tetapi artikel ini tidak mengajarkan cara merancang keduanya. Begitu pula, middleware tidak dengan sendirinya menjadi jaminan keamanan, performa, atau urutan eksekusi tertentu. Jaminan tersebut membutuhkan peninjauan aplikasi dan verifikasi yang tidak dilakukan di sini.

Cara memilih titik keputusan yang tepat

Sebelum membuat middleware, tulis aturan dalam bentuk keputusan sederhana:

1. Request apa yang perlu diperiksa?
2. Kondisi apa yang membuat request boleh diteruskan?
3. Response apa yang dikembalikan jika kondisi tidak terpenuhi?
4. Apakah aturan berlaku global, untuk group, atau hanya route tertentu?
5. Bagian mana yang perlu diverifikasi pada aplikasi dan konfigurasi Laravel yang dipakai?

Jika jawabannya hanya berlaku pada satu operasi bisnis, middleware global mungkin terlalu luas. Jika jawabannya merupakan pemeriksaan lintas batas request, middleware dapat menjadi tempat yang lebih konsisten daripada menyalin kondisi ke banyak handler.

Ringkasnya

Middleware Laravel membantu menempatkan satu aturan di antara request masuk dan alur aplikasi. Inti implementasinya bukan jumlah method yang dihafal, melainkan keputusan pada handle: kembalikan response untuk menghentikan alur, atau panggil $next($request) untuk meneruskannya. Pada Laravel 13.x, contoh ini mendaftarkan middleware secara global melalui bootstrap/app.php.

Gunakan global registration hanya untuk aturan yang memang lintas-request. Untuk cakupan yang lebih sempit, evaluasi group atau route. Setelah itu, cocokkan syntax dengan dokumentasi versi proyek dan uji pada aplikasi Anda; contoh artikel ini belum dijalankan dan bukan bukti kesiapan produksi.