Request Object

Selama ini handler route kita bekerja dengan parameter URI dan data yang di-seed ke database. Padahal setiap request HTTP membawa informasi yang jauh lebih kaya: method apa yang dipakai, path apa yang diminta, input apa yang dikirim pengguna, sampai identitas pengguna yang sedang login. Laravel membungkus semuanya dalam satu class Illuminate\Http\Request, dan object tersebut tinggal kita minta lewat type declaration di signature handler. Chapter ini membahas cara injeksi object Request, membaca metadatanya, mengambil input dengan berbagai method, sampai membaca data pengguna terotentikasi.

Injeksi Request ke Handler #

Service container Laravel mengenali class Request dan otomatis menyediakan instance-nya setiap kali kita menuliskannya sebagai argumen handler — teknik yang sama dengan chapter Route Parameters :

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/profil-request', function (Request $request) {
    return [
        'method' => $request->method(),
        'path' => $request->path(),
        'url' => $request->url(),
        'ip' => $request->ip(),
    ];
});

Handler di atas mengembalikan array yang otomatis dikonversi menjadi response JSON. Pola injeksi ini juga berlaku di method controller — tinggal tambahkan argumen bertipe Request pada method yang menangani route. Karena satu request hanya punya satu object Request, kita bisa memakainya di berbagai tempat sepanjang request berlangsung.

Membaca Metadata Request #

Kita uji route di atas dengan pola runner dari chapter sebelumnya, kali ini hanya satu request GET:

<?php

// uji-profil.php — jalankan dari root proyek Laravel
use Illuminate\Contracts\Http\Kernel;
use Illuminate\Http\Request;

require __DIR__.'/vendor/autoload.php';
$app = require __DIR__.'/bootstrap/app.php';
$app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();

$kernel = $app->make(Kernel::class);
$response = $kernel->handle(
    Request::create('http://localhost:8000/profil-request', 'GET')
);

echo $response->getContent().PHP_EOL;

Output yang Dihasilkan:

{"method":"GET","path":"profil-request","url":"http:\/\/localhost:8000\/profil-request","ip":"127.0.0.1"}

Empat method tersebut memberi kita gambaran lengkap tentang request yang sedang ditangani:

Informasi semacam ini berguna untuk logging, pembatasan akses per IP, atau penulisan response yang menyesuaikan konteks request.

Membaca Input: input() dan all() #

Untuk membaca data yang dikirim klien, kita pakai method input(). Daftarkan route POST berikut:

Route::post('/tugas-baru', function (Request $request) {
    return [
        'nama' => $request->input('nama'),
        'prioritas' => $request->input('prioritas', 'sedang'),
        'selesai' => $request->boolean('selesai'),
        'semua' => $request->all(),
    ];
});

Method input('nama') mengambil satu kunci dari gabungan seluruh sumber input — query string, body POST, maupun JSON. Argumen kedua yang opsional menjadi nilai default ketika kunci tidak ada, seperti prioritas di atas. Method boolean() menerjemahkan nilai form menjadi true/false, dan all() mengembalikan seluruh input sekaligus.

Karena request POST di route web melewati pemeriksaan CSRF, kita beralih ke feature test untuk mengujinya — Laravel otomatis menonaktifkan pemeriksaan CSRF saat testing, jadi kita tidak perlu mengirim _token:

<?php

// tests/Feature/RequestObjectTest.php
namespace Tests\Feature;

use Tests\TestCase;

class RequestObjectTest extends TestCase
{
    public function test_membaca_input_dan_boolean(): void
    {
        $response = $this->post('/tugas-baru', [
            'nama' => 'Belajar Laravel',
            'selesai' => '1',
        ]);

        dump($response->json());
        $this->assertSame(200, $response->status());
    }
}

Output yang Dihasilkan:

array:4 [
  "nama" => "Belajar Laravel"
  "prioritas" => "sedang"
  "selesai" => true
  "semua" => array:2 [
    "nama" => "Belajar Laravel"
    "selesai" => "1"
  ]
]

Perhatikan dua hal dari output tersebut. Field prioritas yang tidak kita kirim terisi default 'sedang', dan string '1' dari checkbox dikonversi boolean() menjadi true. Bandingkan pula "selesai" => true dengan "selesai" => "1" pada semua — all() selalu mengembalikan nilai mentah tanpa konversi.

Menyaring dan Memeriksa Input #

Method only() dan except() memfilter input menjadi array berisi kunci tertentu, sedangkan has() dan filled() memeriksa keberadaan kunci. Route berikut merangkum keempatnya:

Route::post('/ringkasan', function (Request $request) {
    return [
        'only' => $request->only(['nama', 'selesai']),
        'except' => $request->except(['selesai']),
        'ada_nama' => $request->has('nama'),
        'nama_terisi' => $request->filled('nama'),
    ];
});

Kita uji dengan input nama sengaja dikirim sebagai string kosong, ditambah dua field lain:

$response = $this->post('/ringkasan', [
    'nama' => '',
    'selesai' => '1',
    'prioritas' => 'tinggi',
]);

dump($response->json());

Output yang Dihasilkan:

array:4 [
  "only" => array:2 [
    "nama" => null
    "selesai" => "1"
  ]
  "except" => array:2 [
    "nama" => null
    "prioritas" => "tinggi"
  ]
  "ada_nama" => true
  "nama_terisi" => false
]

Di sinilah perbedaan has() dan filled() terlihat: has('nama') bernilai true karena kunci nama memang ada di request, tetapi filled('nama') bernilai false karena isinya tidak berupa nilai berarti.

Membaca Pengguna dengan user() #

Saat aplikasi punya sistem login, method user() mengembalikan instance model pengguna yang sedang terotentikasi — atau null jika pengunjung belum login:

Route::get('/tugas-saya', function (Request $request) {
    return [
        'user' => $request->user()?->email,
    ];
});

Operator nullsafe ?-> menjaga route tetap aman dari error saat user() bernilai null. Kita uji dua skenario dalam satu feature test — sebelum dan sesudah login:

public function test_user_tanpa_login_dan_sesudah_login(): void
{
    $response = $this->get('/tugas-saya');
    dump($response->json());

    $user = \App\Models\User::factory()->create(['email' => '[email protected]']);
    $response = $this->actingAs($user)->get('/tugas-saya');
    dump($response->json());

    $this->assertSame(200, $response->status());
}

Output yang Dihasilkan:

array:1 [
  "user" => null
]
array:1 [
  "user" => "[email protected]"
]

Method actingAs() pada feature test membuat Laravel menganggap request berikutnya datang dari user tersebut. Dalam kode aplikasi nyata, helper auth()->user() mengembalikan object yang sama dengan $request->user(), dan route yang wajib diakses pengguna login sebaiknya dilindungi middleware auth.

Object Request adalah gerbang tunggal untuk membaca segala kiriman klien, dan daftar methodnya jauh lebih panjang dari yang kita coba di sini — dokumentasi requests memuat semuanya. Salah satu bagian yang paling sering dipakai adalah membaca query string seperti ?halaman=2&urutkan=nama, yang akan kita bedah khusus di chapter berikutnya.