Overview
Masalah yang diselesaikan. Pemula sering bingung saat membuka proyek Laravel: puluhan folder, tidak jelas mana yang boleh diubah, di mana meletakkan kode baru, dan mengapa tutorial lama menyebut file (seperti Kernel.php) yang tidak ada di proyek baru.
Hasil akhir: peta mental yang jelas tentang tiap folder, alur request dari URL sampai respons, serta aturan kapan membuat file di folder tertentu. Termasuk Services, yang bukan bagian bawaan Laravel tetapi pola yang sangat umum.
Prerequisites
Komponen | Kebutuhan |
|---|---|
PHP | 8.3+ (Laravel 13) atau 8.2+ (Laravel 12) |
Laravel | 12.x atau 13.x (struktur ramping sejak Laravel 11) |
Proyek | Satu proyek Laravel baru untuk dijelajahi |
Jika Anda membaca tutorial lama (Laravel 10 ke bawah), struktur yang dijelaskan di sini berbeda: tidak ada app/Http/Kernel.php, app/Console/Kernel.php, maupun app/Exceptions/Handler.php.
Step-by-Step Tutorial
1. Peta Besar Struktur Proyek
nama-proyek/
├── app/ ← kode aplikasi Anda
├── bootstrap/ ← inisialisasi framework (app.php, providers.php, cache/)
├── config/ ← berkas konfigurasi
├── database/ ← migrations, factories, seeders
├── public/ ← satu-satunya folder yang boleh diakses web
├── resources/ ← views, CSS/JS mentah, bahasa
├── routes/ ← definisi URL
├── storage/ ← log, cache, upload, session file
├── tests/ ← pengujian otomatis
├── vendor/ ← paket Composer (jangan diubah, jangan di-commit)
├── .env ← konfigurasi lingkungan (rahasia, jangan di-commit)
├── artisan ← CLI Laravel
├── composer.json ← dependensi PHP
└── package.json ← dependensi frontend
2. Alur Request: dari URL ke Respons
Browser ──► public/index.php ──► bootstrap/app.php
│
Middleware (global & grup)
│
routes/web.php
│
Controller
┌───────────┼───────────┐
Form Request Service Model
└───────────┼───────────┘
│
View / JSON
│
Middleware (jalur keluar) ──► Browser
Semua request masuk lewat public/index.php. Karena itu document root web server harus public/, bukan root proyek. Jika salah, .env bisa diunduh orang lain.
3. Folder routes/
routes/
├── web.php ← halaman web (session, CSRF)
├── console.php ← perintah Artisan dan jadwal (scheduler)
├── api.php ← API (dibuat lewat: php artisan install:api)
└── channels.php ← broadcasting (php artisan install:broadcasting)
Fungsi: memetakan URL dan method HTTP ke tindakan. Route tidak berisi logika.
// routes/web.php
use App\Http\Controllers\ProductController;
use Illuminate\Support\Facades\Route;
Route::get('/', fn () => view('welcome'));
Route::middleware('auth')->group(function () {
Route::resource('products', ProductController::class);
});
php artisan route:list
php artisan route:list --path=products
4. Folder app/Http/Controllers/
Fungsi: menerima request, memanggil logika, dan mengembalikan respons.
php artisan make:controller ProductController --resource
Controller yang sehat berisi beberapa baris per method:
public function show(Product $product)
{
return view('products.show', compact('product'));
}
Tanda controller sudah terlalu gemuk: ada DB::transaction, perhitungan bisnis, atau pengiriman email langsung di dalamnya. Pindahkan ke Service (lihat poin 8).
5. Folder app/Models/
Fungsi: merepresentasikan tabel dan relasinya (Eloquent ORM).
php artisan make:model Product -mf # model + migration + factory
class Product extends Model
{
protected $fillable = ['name', 'price'];
public function category(): BelongsTo
{
return $this->belongsTo(Category::class);
}
}
Model memuat relasi, cast, scope, dan accessor. Aturan bisnis yang panjang sebaiknya tidak ditaruh di sini.
6. Middleware
Fungsi: lapisan penyaring yang dijalankan sebelum atau sesudah request mencapai controller, misalnya autentikasi, pembatasan role, logging, atau pengaturan bahasa.
Di Laravel 11 ke atas, middleware bawaan berada di dalam framework. Folder app/Http/Middleware/ baru muncul saat Anda membuat sendiri:
php artisan make:middleware EnsureUserIsAdmin
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class EnsureUserIsAdmin
{
public function handle(Request $request, Closure $next): Response
{
abort_unless($request->user()?->is_admin, 403);
return $next($request);
}
}
Pendaftaran dilakukan di bootstrap/app.php, bukan di Kernel.php:
->withMiddleware(function (Middleware $middleware) {
$middleware->alias(['admin' => \App\Http\Middleware\EnsureUserIsAdmin::class]);
$middleware->web(append: [\App\Http\Middleware\SetLocale::class]);
})
Route::middleware(['auth', 'admin'])->prefix('admin')->group(function () { /* ... */ });
7. Folder bootstrap/, config/, dan app/Providers/
Lokasi | Fungsi |
|---|---|
| Titik konfigurasi: routing, middleware, exception handling |
| Daftar service provider yang dimuat |
| Cache hasil optimasi framework (perlu bisa ditulis) |
| Pengaturan (database, cache, mail, dll.), membaca nilai dari |
| Tempat mendaftarkan binding dan pengaturan global ( |
8. Folder app/Services/ (Pola, Bukan Bawaan)
Laravel tidak membuat folder ini otomatis. Folder Services adalah konvensi buatan tim untuk menampung logika bisnis agar controller tetap tipis.
php artisan make:class Services/OrderService
<?php
namespace App\Services;
use App\Models\Order;
use Illuminate\Support\Facades\DB;
class OrderService
{
public function place(array $data): Order
{
return DB::transaction(function () use ($data) {
$order = Order::create($data);
// kurangi stok, hitung total, kirim event, dll.
return $order;
});
}
}
Laravel akan menyuntikkan service otomatis lewat dependency injection:
public function __construct(private readonly OrderService $orders) {}
public function store(StoreOrderRequest $request)
{
$order = $this->orders->place($request->validated());
return redirect()->route('orders.show', $order);
}
Beberapa tim memakai nama Actions (satu kelas satu tugas) atau Domain/. Yang penting konsisten.
9. Folder Lain di dalam app/
Folder berikut baru muncul ketika Anda membuatnya lewat Artisan:
Folder | Perintah pembuat | Fungsi |
|---|---|---|
|
| Validasi dan otorisasi input |
|
| Bentuk keluaran JSON |
|
| Aturan "boleh atau tidak" per model |
|
| Tugas latar belakang (queue) |
|
| Kelas email |
|
| Notifikasi multi-kanal |
|
| Pola event-driven |
|
| Nilai tetap bertipe |
|
| Perintah Artisan kustom |
|
| Reaksi terhadap siklus hidup model |
|
| Aturan validasi kustom |
10. Folder database/
database/
├── migrations/ ← riwayat perubahan skema
├── factories/ ← pembuat data uji
├── seeders/ ← data awal
└── database.sqlite ← (jika memakai SQLite)
php artisan make:migration add_status_to_orders_table
php artisan migrate
php artisan migrate:rollback
php artisan db:seed
Migrasi yang sudah dijalankan di production jangan diedit. Buat migrasi baru untuk perubahan berikutnya.
11. Folder resources/
resources/
├── views/ ← template Blade
├── css/ ← CSS mentah (diproses Vite)
├── js/ ← JavaScript mentah (diproses Vite)
└── lang/ ← berkas terjemahan (muncul setelah lang:publish)
Aset di resources/ belum bisa diakses publik. Vite membangunnya menjadi berkas di public/build/.
12. Folder public/ dan storage/
Lokasi | Isi | Catatan |
|---|---|---|
| Pintu masuk aplikasi | Jangan diubah |
| Hasil build Vite | Dihasilkan |
| Symlink ke | Dibuat dengan |
| File unggahan yang boleh diakses publik | Lewat symlink |
| File unggahan privat | Tidak bisa diakses langsung |
| Log aplikasi ( | Perlu bisa ditulis |
| Cache, session, dan view terkompilasi | Perlu bisa ditulis |
php artisan storage:link
13. Tes dan Pengaman
tests/
├── Feature/ ← menguji alur lengkap (HTTP, database)
├── Unit/ ← menguji kelas terisolasi
└── TestCase.php
php artisan make:test OrderTest
php artisan make:test OrderServiceTest --unit
php artisan test
14. Ringkasan: Kode Ini Taruh di Mana?
Kebutuhan | Letakkan di |
|---|---|
Menentukan URL |
|
Menerima request, memanggil logika | Controller |
Memvalidasi input | Form Request |
Aturan bisnis, transaksi | Service / Action |
Relasi dan scope tabel | Model |
Membatasi akses berdasarkan peran | Middleware atau Policy |
Bentuk JSON | API Resource |
Pekerjaan lambat | Job (queue) |
Nilai tetap (status, tipe) | Enum |
Pengaturan aplikasi |
|
Tampilan |
|
Troubleshooting
Gejala | Penyebab | Solusi |
|---|---|---|
Tutorial menyebut | Tutorial untuk Laravel 10 atau lebih lama | Gunakan |
| Nama route salah atau belum diberi |
|
Route baru tidak terbaca di server | Route di-cache |
|
| Namespace atau | Periksa namespace dan nama file (huruf besar-kecil penting di Linux) |
Route API tidak ada |
|
|
Gambar unggahan tidak tampil | Symlink belum ada |
|
| Izin | Pastikan |
Perubahan view tidak terlihat | View terkompilasi di-cache |
|
Class baru tidak ditemukan | Autoload belum diperbarui |
|
Perubahan | Konfigurasi di-cache |
|
Best Practices
Keamanan
Document root server hanya
public/. Jangan pernah mengarah ke root proyek..env,storage/, danvendor/tidak boleh dapat diakses lewat URL.Taruh file sensitif di
storage/app/private, dan sajikan lewat controller dengan otorisasi.Folder
vendor/dan.envjangan di-commit.
Performa
Di production, jalankan
php artisan optimize(cache konfigurasi, route, event, dan view).Jangan menaruh logika berat di
routes/web.phpatau closure route, karena route dengan closure tidak bisa di-cache.Gunakan controller untuk route yang akan di-cache.
Maintainability
Satu kelas, satu tanggung jawab. Controller tidak membawa aturan bisnis.
Gunakan nama yang mengikuti konvensi Laravel (
ProductController,ProductPolicy) agar auto-discovery bekerja.Hanya buat folder baru (Services, Actions, DTO) bila ada kebutuhan nyata, dan dokumentasikan di README.
Jangan mengedit isi
vendor/. Perubahan akan hilang saatcomposer install.Gunakan
php artisan aboutuntuk melihat ringkasan lingkungan dan konfigurasi.
Related Articles
Last Tested
Catatan jujur: isi disusun dari dokumentasi resmi dan struktur skeleton Laravel 11+; belum dijalankan ulang di proyek baru oleh penulis. Cek
php artisan aboutdan struktur folder pada proyek Anda.
Komponen | Versi acuan penulisan | Versi saat Anda menguji |
|---|---|---|
PHP | 8.3.x | |
Laravel | 13.x (struktur sama dengan 12.x dan 11.x) | |
Tanggal uji |