Mengatasi Konflik Server Lokal dan Routing Static Asset di Windows (Kasus AitiCore Flex & CMS)

Debug routing server lokal PHP built-in server dengan router.php dan static asset storage

Dalam proses pengembangan web lokal, terutama menggunakan PHP built-in server (php -S), sering muncul masalah yang terlihat sederhana tetapi ternyata berasal dari beberapa lapisan konfigurasi. Hal ini juga terjadi pada proyek AitiCore Flex dan aplikasi aitiCore CMS.

Masalah yang muncul bukan hanya satu titik error, tetapi kombinasi dari:

Konfigurasi server lokal yang bertabrakan
Handling HTTP method yang tidak lengkap
Routing static asset yang bermasalah di Windows

Jika tidak dianalisis dengan benar, hasilnya bisa berupa halaman 404 tidak konsisten, gambar tidak muncul, atau route tertentu tidak dapat diakses walaupun sebenarnya sudah dibuat.

Masalah Utama yang Terjadi

Setelah dianalisis lebih dalam, terdapat tiga lapisan kendala yang menyebabkan error tersebut.

1. Server Instance Bentrok di Port yang Sama

Masalah pertama berasal dari adanya dua proses server PHP yang berjalan bersamaan pada port yang sama.

php -S 127.0.0.1:8000
php -S 127.0.0.1:8000 router.php

Jika dua proses ini berjalan bersamaan, request yang masuk bisa diarahkan ke server yang berbeda. Akibatnya beberapa URL seperti:

/read/artikel-slug.html
/products/nama-produk.html

kadang berhasil, kadang langsung menghasilkan 404 Not Found.

Hal ini terjadi karena server pertama tidak menggunakan router.php, sehingga request tidak melalui sistem routing aplikasi.

Solusi

Pastikan hanya ada satu server yang berjalan dan selalu menggunakan router aplikasi:

php -S 0.0.0.0:8000 router.php

Dengan cara ini semua request akan diproses oleh router yang sama.

2. Request HEAD Tidak Dipetakan ke GET

Beberapa browser atau crawler seperti Googlebot sering mengirim request HEAD terlebih dahulu sebelum melakukan request GET.

Jika router hanya mengenali method literal, maka request HEAD akan menghasilkan error seperti:

ROUTE_NOT_FOUND method=HEAD

Padahal route GET sebenarnya sudah tersedia.

Solusi

Di level framework (AitiCore Flex), method HEAD dipetakan otomatis ke GET.

if ($method === 'HEAD') {
    $method = 'GET';
    $headOnly = true;
}

Kemudian response tetap diproses seperti GET, tetapi body tidak dikirim.

if ($headOnly) {
    exit; 
}

Dengan pendekatan ini, crawler dan browser modern tetap bisa membaca metadata halaman tanpa memuat seluruh konten.

3. Static Asset /storage Tidak Terbaca di Windows

Masalah berikutnya terjadi pada asset statis seperti gambar artikel dan produk.

URL gambar biasanya berada pada path seperti:

/storage/uploads/artikel/gambar.jpg

Namun di Windows, symlink public/storage sering tidak dikenali dengan benar oleh PHP built-in server. Akibatnya router menganggap request tersebut sebagai route dinamis.

Hasilnya:

Gambar tidak muncul
Request masuk router
Router mengembalikan 404

Solusi

Tambahkan pengecekan file statis langsung di router.php.

$path = parse_url($_SERVER["REQUEST_URI"], PHP_URL_PATH);
$file = __DIR__ . "/public" . $path;

if (is_file($file)) {
    return false;
}

Dengan cara ini:

File statis langsung dilayani server
Router hanya menangani route dinamis
Gambar artikel dan produk kembali tampil normal

Perbaikan di Level Framework (AitiCore Flex)

Perbaikan yang dilakukan pada framework inti meliputi:

Mapping method HEAD ke GET
Response HEAD tanpa body
Routing yang lebih konsisten

Ini memastikan kompatibilitas dengan browser modern dan crawler search engine.

Perbaikan di Level Aplikasi (AitiCore CMS)

Pada level aplikasi CMS, beberapa penyesuaian juga dilakukan:

Alias route /read/{slug}
Alias route /products/{slug}
Fallback tanpa ekstensi .html
Alias /cms untuk login panel
Server harus dijalankan menggunakan router.php

Pendekatan ini membuat URL lebih fleksibel dan SEO friendly.

Kesimpulan

Masalah routing di server lokal sering terlihat sederhana, tetapi sebenarnya dapat berasal dari kombinasi konfigurasi server, metode HTTP, dan pengolahan asset statis.

Dalam kasus AitiCore Flex dan aitiCore CMS, solusi yang diterapkan mencakup: