Bagian 2: Routing dan Request

<?php
declare(strict_types=1);

namespace App;

/**
 * Representasi immutable dari satu HTTP request.
 *
 * Objek ini menyalin semua data mentah (method, path, query string, body
 * JSON, header) pada saat konstruksi, lalu tidak pernah berubah lagi.
 * Handler menerima objek Request ini sebagai input tunggalnya sehingga
 * mudah diuji: kita bisa membangun request tiruan tanpa web server.
 */
final class Request
{
    /**
     * @param array<string, mixed>  $query   parameter query string, mis. ?halaman=2.
     * @param array<string, mixed>  $body    body JSON yang sudah di-decode menjadi array.
     * @param array<string, string> $headers header HTTP dengan nama lowercase.
     */
    private function __construct(
        private readonly string $method,
        private readonly string $path,
        private readonly array $query,
        private readonly array $body,
        private readonly array $headers,
    ) {
    }

    /**
     * Factory untuk pengujian: bangun Request dari array biasa.
     *
     * Kunci yang dikenali: method, path, query, body, headers.
     *
     * @param array<string, mixed> $data
     */
    public static function fromArray(array $data): self
    {
        return new self(
            strtoupper((string) ($data['method'] ?? 'GET')),
            self::normalisasiPath((string) ($data['path'] ?? '/')),
            (array) ($data['query'] ?? []),
            (array) ($data['body'] ?? []),
            self::normalisasiHeader((array) ($data['headers'] ?? [])),
        );
    }

    /**
     * Factory untuk produksi: baca request dari superglobal PHP.
     */
    public static function fromGlobals(): self
    {
        $method = strtoupper((string) ($_SERVER['REQUEST_METHOD'] ?? 'GET'));
        $path = self::normalisasiPath(
            (string) (parse_url((string) ($_SERVER['REQUEST_URI'] ?? '/'), PHP_URL_PATH) ?: '/'),
        );

        $body = [];
        $mentah = file_get_contents('php://input');
        if (is_string($mentah) && $mentah !== '' && json_validate($mentah)) {
            $terjemah = json_decode($mentah, true);
            if (is_array($terjemah)) {
                $body = $terjemah;
            }
        }

        $headers = [];
        foreach ($_SERVER as $nama => $nilai) {
            if (str_starts_with((string) $nama, 'HTTP_')) {
                $headers[strtolower(str_replace('_', '-', substr((string) $nama, 5)))] = (string) $nilai;
            }
        }
        if (isset($_SERVER['CONTENT_TYPE'])) {
            $headers['content-type'] = (string) $_SERVER['CONTENT_TYPE'];
        }

        return new self($method, $path, $_GET, $body, $headers);
    }

    public function method(): string
    {
        return $this->method;
    }

    public function path(): string
    {
        return $this->path;
    }

    /**
     * Baca parameter query string. Tanpa argumen, kembalikan semua parameter.
     */
    public function query(?string $kunci = null, mixed $default = null): mixed
    {
        if ($kunci === null) {
            return $this->query;
        }

        return $this->query[$kunci] ?? $default;
    }

    /**
     * Baca field body JSON. Tanpa argumen, kembalikan seluruh body.
     */
    public function body(?string $kunci = null, mixed $default = null): mixed
    {
        if ($kunci === null) {
            return $this->body;
        }

        return $this->body[$kunci] ?? $default;
    }

    /**
     * Baca header; nama header tidak case-sensitive.
     */
    public function header(string $nama, ?string $default = null): ?string
    {
        return $this->headers[strtolower($nama)] ?? $default;
    }

    /**
     * @return array<string, string>
     */
    public function headers(): array
    {
        return $this->headers;
    }

    private static function normalisasiPath(string $path): string
    {
        // '/a/b/' dan 'a/b' keduanya dinormalisasi menjadi '/a/b',
        // sedangkan '/' dan '' menjadi '/'.
        return '/' . trim($path, '/');
    }

    /**
     * @param array<string, mixed> $headers
     *
     * @return array<string, string>
     */
    private static function normalisasiHeader(array $headers): array
    {
        $hasil = [];
        foreach ($headers as $nama => $nilai) {
            $hasil[strtolower((string) $nama)] = (string) $nilai;
        }

        return $hasil;
    }
}

<?php
declare(strict_types=1);

namespace App;

/**
 * Representasi immutable dari satu HTTP response.
 *
 * Handler tidak menyentuh fungsi header()/echo langsung; handler hanya
 * membangun objek Response (biasanya lewat static factory json()) dan
 * mengembalikannya. Front controller-lah yang memanggil send() tepat satu
 * kali di akhir. Pola ini membuat response bisa diperiksa dalam pengujian
 * tanpa benar-benar mengirim byte ke client.
 */
final class Response
{
    /**
     * @param array<string, string> $headers
     */
    private function __construct(
        private readonly int $status,
        private readonly array $headers,
        private readonly string $body,
    ) {
    }

    /**
     * Factory response JSON — tipe yang dominan pada REST API ini.
     *
     * @param mixed $data data apa pun yang bisa di-json_encode.
     */
    public static function json(mixed $data, int $status = 200): self
    {
        return new self(
            $status,
            ['Content-Type' => 'application/json; charset=utf-8'],
            (string) json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
        );
    }

    /**
     * Factory response 204 tanpa body, cocok untuk DELETE yang berhasil.
     */
    public static function noContent(): self
    {
        return new self(204, [], '');
    }

    /**
     * Factory response redirect dengan header Location.
     */
    public static function redirect(string $lokasi, int $status = 302): self
    {
        return new self($status, ['Location' => $lokasi], '');
    }

    public function status(): int
    {
        return $this->status;
    }

    public function body(): string
    {
        return $this->body;
    }

    public function header(string $nama, ?string $default = null): ?string
    {
        return $this->headers[$nama] ?? $default;
    }

    /**
     * @return array<string, string>
     */
    public function headers(): array
    {
        return $this->headers;
    }

    /**
     * Salinan response dengan satu header tambahan (immutable wither).
     */
    public function withHeader(string $nama, string $nilai): self
    {
        $headers = $this->headers;
        $headers[$nama] = $nilai;

        return new self($this->status, $headers, $this->body);
    }

    /**
     * Kirim response ke client. Hanya boleh dipanggil front controller.
     */
    public function send(): void
    {
        http_response_code($this->status);
        foreach ($this->headers as $nama => $nilai) {
            header("$nama: $nilai");
        }
        echo $this->body;
    }
}

<?php
declare(strict_types=1);

namespace App;

/**
 * Router minimalis dengan dukungan parameter {nama}.
 *
 * Cara pakai:
 *
 *     $router = new Router();
 *     $router->add('GET', '/api/tugas/{id}', $handler);
 *     $response = $router->dispatch($request);
 *
 * Handler dipanggil dengan dua argumen: objek Request dan array parameter
 * yang diekstrak dari pattern, mis. ['id' => '7']. Handler wajib
 * mengembalikan objek Response. Bila tidak ada route yang cocok, Router
 * membangun response 404; bila path cocok tapi method salah, Router
 * membangun response 405 lengkap dengan header Allow.
 */
final class Router
{
    /**
     * @var list<array{method: string, regex: string, params: list<string>, handler: callable}>
     */
    private array $routes = [];

    /**
     * Daftarkan satu route. Pattern boleh memuat parameter {nama} yang
     * mencocokan satu segmen path (karakter selain garis miring).
     */
    public function add(string $method, string $pattern, callable $handler): self
    {
        $params = [];
        $regex = (string) preg_replace_callback(
            '/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/',
            static function (array $cocok) use (&$params): string {
                $params[] = $cocok[1];

                return '([^/]+)';
            },
            $pattern,
        );

        $this->routes[] = [
            'method' => strtoupper($method),
            'regex' => '#^' . $regex . '$#',
            'params' => $params,
            'handler' => $handler,
        ];

        return $this;
    }

    /**
     * Cocokkan request dengan daftar route lalu panggil handler-nya.
     */
    public function dispatch(Request $request): Response
    {
        $methodDiizinkan = [];

        foreach ($this->routes as $route) {
            if (preg_match($route['regex'], $request->path(), $cocok) !== 1) {
                continue;
            }

            if ($route['method'] !== $request->method()) {
                $methodDiizinkan[] = $route['method'];
                continue;
            }

            $params = array_combine($route['params'], array_slice($cocok, 1));

            return ($route['handler'])($request, $params);
        }

        if ($methodDiizinkan !== []) {
            return Response::json(
                [
                    'error' => [
                        'code' => 'METHOD_NOT_ALLOWED',
                        'message' => sprintf(
                            'Method %s tidak diizinkan untuk endpoint ini.',
                            $request->method(),
                        ),
                    ],
                ],
                405,
            )->withHeader('Allow', implode(', ', array_values(array_unique($methodDiizinkan))));
        }

        return Response::json(
            [
                'error' => [
                    'code' => 'NOT_FOUND',
                    'message' => sprintf('Endpoint %s %s tidak ditemukan.', $request->method(), $request->path()),
                ],
            ],
            404,
        );
    }
}