Struktur proyek

Topik ini menelusuri direktori-direktori utama pada proyek Laravel modern dengan menjadikan proyek contoh aplikasi catatan sebagai acuan. Pada akhir topik, setiap direktori memiliki arti yang jelas, yaitu tempat controller, model, rute, view, dan konfigurasi disimpan, sehingga setiap berkas baru memiliki tempat yang pasti.

Peta direktori utama#

Proyek Laravel yang baru dibuat sudah memiliki struktur direktori yang seragam untuk semua aplikasi. Keseragaman ini disengaja, karena struktur yang sama pada setiap proyek membuat pengembang baru dapat menemukan bagian tertentu tanpa menjelajahi kode terlebih dahulu. Dokumentasi resmi menyebut bahwa struktur bawaan ini hanya titik awal dan Laravel hampir tidak membatasi lokasi kelas selama Composer dapat memuatnya. Meskipun demikian, untuk aplikasi berukuran kecil hingga besar, struktur bawaan sudah menempatkan setiap jenis kode pada tempat yang wajar.

Pohon berikut merangkum direktori utama pada proyek contoh aplikasi catatan.

aplikasi-catatan/
├── app/           kode inti aplikasi (controller, model, provider)
├── bootstrap/     titik bootstrap framework dan berkas cache internal
├── config/        berkas konfigurasi aplikasi
├── database/      migration, factory, seeder, dan berkas SQLite
├── public/        document root web server beserta index.php
├── resources/     view Blade dan aset mentah CSS serta JS
├── routes/        definisi rute HTTP dan konsol
├── storage/       log, view terkompilasi, cache, dan sesi
├── tests/         pengujian otomatis
└── vendor/        dependensi Composer

Selain direktori di atas, akar proyek memuat beberapa berkas penting. Berkas artisan adalah alat command line bawaan Laravel yang menjadi pintu masuk seluruh perintah Artisan. Berkas composer.json dan composer.lock mengelola dependensi PHP, sedangkan package.json dan vite.config.js mengelola aset frontend. Berkas phpunit.xml menyiapkan konfigurasi pengujian, dan pasangan berkas .env serta .env.example menyimpan nilai lingkungan aplikasi.

Direktori app#

Direktori app menampung hampir seluruh kelas yang ditulis khusus untuk aplikasi. Secara baku, proyek baru memuat tiga subdirektori, dan daftar isinya dapat diperiksa langsung pada proyek contoh.

cd ~/aplikasi-catatan
# tampilkan isi direktori app
ls app

Http
Jobs
Mail
Models
Notifications
Policies
Providers
Rules
Support

Direktori app/Http menampung kode yang berinteraksi dengan lapisan HTTP, yaitu controller, middleware, dan form request. Direktori app/Models menampung kelas model Eloquent yang mewakili tabel database, sedangkan app/Providers menampung service provider aplikasi. Ketiganya adalah tiga subdirektori bawaan proyek baru. Subdirektori lain pada daftar di atas, yaitu Jobs, Mail, Notifications, Policies, Rules, dan Support, berasal dari kelas pendukung aplikasi catatan yang dibuat sepanjang contoh pada jalur ini. Pada proyek baru, subdirektori semacam itu belum ada dan baru muncul ketika perintah make terkait dijalankan, misalnya php artisan make:job menciptakan app/Jobs.

Proyek contoh sudah memiliki dua model tambahan selain User karena aplikasi catatan bekerja dengan tabel notes dan categories.

# tampilkan isi direktori app/Models
ls app/Models

Category.php
Note.php
User.php

Direktori routes dan resources#

Direktori routes memuat definisi rute aplikasi. Pada struktur modern Laravel, proyek baru hanya menyertakan dua berkas, yaitu web.php untuk rute antarmuka web dan console.php untuk perintah konsol berbasis closure. Berkas api.php ikut terlihat pada proyek contoh karena php artisan install:api sudah dijalankan untuk kebutuhan contoh API pada jalur ini.

# tampilkan isi direktori routes
ls routes

api.php
console.php
web.php

Rute pada web.php diberi grup middleware web yang menyediakan session, proteksi CSRF, dan enkripsi cookie. Berkas routes/api.php tidak disertakan secara bawaan dan baru dibuat ketika perintah php artisan install:api dijalankan, sehingga proyek yang tidak menawarkan API dapat menempatkan semua rute di web.php. Adapun direktori resources memuat view Blade pada resources/views beserta aset mentah pada resources/css dan resources/js yang diproses oleh Vite pada tahap build. Berbeda dengan direktori app, isi resources adalah berkas templat dan aset, bukan kelas PHP.

Direktori database, public, dan storage#

Direktori database menampung migration pada database/migrations, factory pada database/factories, dan seeder pada database/seeders. Ketiganya mengelola skema dan data uji database. Proyek dengan driver SQLite default juga menyimpan berkas database/database.sqlite pada direktori ini.

Direktori public adalah document root yang dilayani web server. Hanya berkas pada direktori inilah yang dapat diakses langsung dari internet, termasuk index.php yang menjadi titik masuk seluruh permintaan HTTP. Adapun direktori storage memuat berkas yang ditulis framework selama aplikasi berjalan, yaitu log pada storage/logs, view terkompilasi dan cache pada storage/framework, serta berkas buatan aplikasi pada storage/app. Berkas unggahan yang perlu diakses publik ditempatkan pada storage/app/public dan dibuka melalui tautan simbolik yang dibuat perintah php artisan storage:link.

Konvensi namespace dan autoload#

Kelas-kelas pada app dimuat otomatis oleh Composer mengikuti standar autoloading PSR-4. Pemetaannya dideklarasikan pada berkas composer.json, dan bagiannya yang relevan adalah sebagai berikut.

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Database\\Factories\\": "database/factories/",
        "Database\\Seeders\\": "database/seeders/"
    }
}

Pemetaan tersebut menetapkan aturan sederhana, yaitu namespace App\ berpadanan dengan direktori app/. Kelas App\Models\Note berada pada app/Models/Note.php, dan kelas App\Http\Controllers\HalamanController berada pada app/Http/Controllers/HalamanController.php. Aturan ini berlaku dua arah, sehingga saat kelas baru dibuat pada direktori yang benar dengan namespace yang benar, Composer dapat memuatnya tanpa konfigurasi tambahan. Konvensi inilah yang digunakan saat controller dan model dibuat pada topik lain dalam jalur ini.

Kesalahan umum#

Kesalahan pertama adalah menyunting berkas di dalam vendor. Direktori tersebut berisi dependensi yang ditulis ulang setiap kali composer install atau composer update dijalankan, sehingga perubahan apa pun di dalamnya hilang. Penyesuaian perilaku paket dilakukan melalui konfigurasi aplikasi, bukan dengan menyunting paketnya.

Kesalahan kedua adalah menempatkan kelas baru pada direktori sembarang atau menuliskan namespace yang tidak cocok dengan lokasinya. Akibatnya PHP melaporkan error Class "..." not found ketika kelas itu dipanggil. Perbaikannya adalah menempatkan kelas sesuai pemetaan PSR-4 di atas, atau apabila memang diperlukan lokasi lain, menambahkan pemetaannya pada composer.json lalu menjalankan composer dump-autoload.

Kesalahan ketiga adalah mengarahkan web server ke akar proyek alih-alih ke public. Berkas seperti .env yang berada di akar proyek dapat diunduh oleh siapa pun apabila web server melayani direktori yang salah. Web server harus diarahkan ke public, dan perintah php artisan serve sudah melakukannya secara otomatis.

Ringkasan#

• Struktur proyek Laravel menempatkan kode aplikasi pada app, definisi rute pada routes, templat pada resources/views, pengelolaan skema dan data uji pada database, serta berkas berjalan pada storage.
• Proyek modern hanya menyertakan routes/web.php dan routes/console.php, sedangkan routes/api.php baru muncul setelah php artisan install:api.
• public adalah satu-satunya direktori yang dilayani web server, dan index.php di dalamnya menjadi titik masuk seluruh permintaan.
• Namespace App\ dipetakan PSR-4 ke direktori app/, sehingga lokasi berkas dan nama kelas harus saling cocok agar kelas dapat dimuat otomatis.

Referensi#

• Directory Structure — Laravel — Dokumentasi resmi yang menjelaskan peran setiap direktori akar dan direktori pada app serta menjadi dasar tur pada topik ini.