Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Arsitektur / Cara Membuat Project Laravel d...
Arsitektur

Cara Membuat Project Laravel dengan Struktur Kode yang Rapi dan Mudah Dikembangkan

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
9 min read
12 views

Overview

Masalah yang diselesaikan. Proyek Laravel biasanya dimulai rapi, lalu berubah menjadi "controller gemuk": validasi, query, perhitungan bisnis, kirim email, dan format respons menumpuk di satu method sepanjang 200 baris. Akibatnya sulit diuji, sulit dibaca anggota tim baru, dan setiap perubahan kecil berisiko merusak bagian lain.

Hasil akhir tutorial ini: kerangka proyek dengan pemisahan tanggung jawab yang jelas, dibangun pada contoh modul Produk:

Request ──► Route ──► Controller (tipis)
                         │
        Form Request ◄───┤  validasi + otorisasi
                         │
                         ▼
                      Service / Action   ← logika bisnis
                         │
                         ▼
                Model / Query Scope      ← akses data
                         │
                         ▼
           API Resource / Blade View     ← bentuk keluaran

Prinsipnya sederhana: setiap kelas punya satu alasan untuk berubah. Tidak perlu arsitektur berlebihan. Struktur ini cukup untuk aplikasi kecil sampai menengah dan bisa tumbuh.

Prerequisites

Komponen

Kebutuhan

PHP

8.3+ (Laravel 13) atau 8.2+ (Laravel 12)

Laravel

12.x atau 13.x

Composer

2.x

Database

MySQL 8.x / MariaDB / SQLite

Pengetahuan

Route, controller, Eloquent dasar

Proyek kosong sudah terpasang (lihat artikel instalasi). Perintah make:class dan make:enum tersedia di Laravel 11 ke atas.

Step-by-Step Tutorial

1. Tetapkan Aturan Struktur Sejak Awal

Sepakati dan tulis di README.md:

Lapisan

Folder

Tanggung jawab

Tidak boleh berisi

Route

routes/

Memetakan URL ke controller

Logika

Controller

app/Http/Controllers

Menerima request, memanggil service, mengembalikan respons

Query kompleks, aturan bisnis

Form Request

app/Http/Requests

Validasi dan otorisasi input

Akses database berat

Service/Action

app/Services atau app/Actions

Aturan bisnis, transaksi

Objek Request, HTML

Model

app/Models

Relasi, scope, cast

Aturan bisnis panjang

Resource

app/Http/Resources

Bentuk keluaran JSON

Query

Policy

app/Policies

Otorisasi per model

Validasi input

Enum

app/Enums

Nilai tetap bertipe

-

2. Siapkan Kualitas Kode Otomatis

Pasang alat gaya kode dan analisis statis sejak awal, karena membenahi belakangan jauh lebih mahal.

composer require laravel/pint --dev
composer require larastan/larastan --dev

Jalankan Pint:

vendor\bin\pint
  ................................................

  ──────────────────────────── Laravel
    FIXED   ................................ 6 files, 2 style issues fixed

Konfigurasi Larastan (phpstan.neon):

includes:
    - vendor/larastan/larastan/extension.neon

parameters:
    paths:
        - app
    level: 5
vendor\bin\phpstan analyse --memory-limit=1G

Naikkan level bertahap seiring kode matang. Tambahkan skrip pintasan di composer.json:

"scripts": {
    "lint": "pint --test",
    "analyse": "phpstan analyse --memory-limit=1G",
    "check": ["@lint", "@analyse", "@php artisan test"]
}
composer check

3. Aktifkan Pengaman Eloquent saat Pengembangan

// app/Providers/AppServiceProvider.php
use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    Model::shouldBeStrict(! app()->isProduction());
}

shouldBeStrict mengaktifkan pencegahan lazy loading (N+1), pencegahan pengisian atribut yang tidak ada, dan pencegahan akses atribut yang tidak dimuat. Bug jadi muncul saat pengembangan, bukan di production.

4. Buat Modul Produk

php artisan make:model Product -mf
php artisan make:enum Enums/ProductStatus
php artisan make:controller ProductController
php artisan make:request StoreProductRequest
php artisan make:request UpdateProductRequest
php artisan make:resource ProductResource
php artisan make:policy ProductPolicy --model=Product
php artisan make:class Services/ProductService

Enum status (app/Enums/ProductStatus.php):

<?php

namespace App\Enums;

enum ProductStatus: string
{
    case Draft    = 'draft';
    case Active   = 'active';
    case Archived = 'archived';

    public function label(): string
    {
        return match ($this) {
            self::Draft    => 'Draf',
            self::Active   => 'Aktif',
            self::Archived => 'Diarsipkan',
        };
    }
}

Migrasi:

Schema::create('products', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->string('sku')->unique();
    $table->unsignedBigInteger('price');           // rupiah, integer
    $table->unsignedInteger('stock')->default(0);
    $table->string('status')->default('draft')->index();
    $table->text('description')->nullable();
    $table->timestamps();
    $table->softDeletes();
});

Model:

<?php

namespace App\Models;

use App\Enums\ProductStatus;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Product extends Model
{
    use HasFactory, SoftDeletes;

    protected $fillable = ['name', 'slug', 'sku', 'price', 'stock', 'status', 'description'];

    protected function casts(): array
    {
        return [
            'price'  => 'integer',
            'stock'  => 'integer',
            'status' => ProductStatus::class,
        ];
    }

    public function scopeActive(Builder $query): Builder
    {
        return $query->where('status', ProductStatus::Active);
    }

    public function scopeSearch(Builder $query, ?string $term): Builder
    {
        return $query->when($term, fn (Builder $q) => $q->where(
            fn (Builder $w) => $w->where('name', 'like', "%{$term}%")->orWhere('sku', 'like', "%{$term}%")
        ));
    }
}

Form Request (app/Http/Requests/StoreProductRequest.php):

<?php

namespace App\Http\Requests;

use App\Enums\ProductStatus;
use App\Models\Product;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class StoreProductRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()?->can('create', Product::class) ?? false;
    }

    public function rules(): array
    {
        return [
            'name'        => ['required', 'string', 'max:150'],
            'sku'         => ['required', 'string', 'max:50', 'unique:products,sku'],
            'price'       => ['required', 'integer', 'min:0'],
            'stock'       => ['required', 'integer', 'min:0'],
            'status'      => ['required', Rule::enum(ProductStatus::class)],
            'description' => ['nullable', 'string', 'max:5000'],
        ];
    }
}

Service (app/Services/ProductService.php):

<?php

namespace App\Services;

use App\Models\Product;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class ProductService
{
    public function paginate(?string $search, int $perPage = 15): LengthAwarePaginator
    {
        return Product::query()->search($search)->latest()->paginate($perPage)->withQueryString();
    }

    /** @param  array<string, mixed>  $data */
    public function create(array $data): Product
    {
        return DB::transaction(function () use ($data) {
            $data['slug'] = $this->uniqueSlug($data['name']);

            return Product::create($data);
        });
    }

    /** @param  array<string, mixed>  $data */
    public function update(Product $product, array $data): Product
    {
        $product->update($data);

        return $product->refresh();
    }

    private function uniqueSlug(string $name): string
    {
        $base = Str::slug($name) ?: 'produk';
        $slug = $base;

        for ($i = 2; Product::withTrashed()->where('slug', $slug)->exists(); $i++) {
            $slug = "{$base}-{$i}";
        }

        return $slug;
    }
}

Controller tipis:

<?php

namespace App\Http\Controllers;

use App\Http\Requests\StoreProductRequest;
use App\Http\Requests\UpdateProductRequest;
use App\Http\Resources\ProductResource;
use App\Models\Product;
use App\Services\ProductService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

class ProductController extends Controller
{
    public function __construct(private readonly ProductService $products) {}

    public function index(Request $request): AnonymousResourceCollection
    {
        return ProductResource::collection(
            $this->products->paginate($request->string('q')->toString() ?: null)
        );
    }

    public function store(StoreProductRequest $request): JsonResponse
    {
        $product = $this->products->create($request->validated());

        return (new ProductResource($product))->response()->setStatusCode(201);
    }

    public function update(UpdateProductRequest $request, Product $product): ProductResource
    {
        $this->authorize('update', $product);

        return new ProductResource($this->products->update($product, $request->validated()));
    }

    public function destroy(Product $product): JsonResponse
    {
        $this->authorize('delete', $product);
        $product->delete();

        return response()->json(status: 204);
    }
}

Resource:

public function toArray(Request $request): array
{
    return [
        'id'     => $this->id,
        'name'   => $this->name,
        'slug'   => $this->slug,
        'sku'    => $this->sku,
        'price'  => $this->price,
        'stock'  => $this->stock,
        'status' => ['value' => $this->status->value, 'label' => $this->status->label()],
    ];
}

Route (gunakan routes/api.php; buat dengan php artisan install:api bila belum ada):

use App\Http\Controllers\ProductController;

Route::middleware('auth:sanctum')->apiResource('products', ProductController::class)->except(['show']);

5. Letakkan Konfigurasi dan Konstanta di Tempat yang Benar

Jangan memanggil env() di luar folder config/. Buat berkas konfigurasi sendiri untuk pengaturan aplikasi:

// config/shop.php
return [
    'currency'          => 'IDR',
    'low_stock_limit'   => env('SHOP_LOW_STOCK_LIMIT', 5),
    'items_per_page'    => 15,
];
config('shop.low_stock_limit');

6. Struktur Folder yang Dihasilkan

app/
├── Enums/ProductStatus.php
├── Http/
│   ├── Controllers/ProductController.php
│   ├── Requests/{StoreProductRequest,UpdateProductRequest}.php
│   └── Resources/ProductResource.php
├── Models/Product.php
├── Policies/ProductPolicy.php
└── Services/ProductService.php
config/shop.php
tests/
├── Feature/ProductApiTest.php
└── Unit/ProductServiceTest.php

Saat modul bertambah, kelompokkan per domain bila perlu:

app/Services/Catalog/ProductService.php
app/Services/Order/CheckoutService.php

7. Tulis Test untuk Alur Utama

php artisan make:test ProductApiTest
public function test_user_dapat_membuat_produk(): void
{
    $user = User::factory()->create();

    $this->actingAs($user, 'sanctum')
        ->postJson('/api/products', [
            'name' => 'Produk Uji', 'sku' => 'SKU-001', 'price' => 150000,
            'stock' => 10, 'status' => 'active',
        ])
        ->assertCreated()
        ->assertJsonPath('data.slug', 'produk-uji');

    $this->assertDatabaseHas('products', ['sku' => 'SKU-001']);
}

public function test_validasi_sku_unik(): void
{
    Product::factory()->create(['sku' => 'SKU-001']);

    $this->actingAs(User::factory()->create(), 'sanctum')
        ->postJson('/api/products', ['sku' => 'SKU-001'])
        ->assertUnprocessable()
        ->assertJsonValidationErrors(['sku']);
}
php artisan test
   PASS  Tests\Feature\ProductApiTest
  ✓ user dapat membuat produk
  ✓ validasi sku unik

  Tests:    2 passed (7 assertions)

Troubleshooting

Gejala

Penyebab

Solusi

Target class [ProductService] does not exist

Namespace atau use salah

Cek namespace dan use App\Services\ProductService;

Class "App\Services\ProductService" not found setelah membuat dengan make:class

Folder atau namespace tidak cocok

Pastikan path app/Services/ProductService.php dan namespace App\Services

Form Request mengembalikan 403

authorize() mengembalikan false

Periksa policy dan status login, atau kembalikan true bila tidak butuh otorisasi

MassAssignmentException

Kolom belum masuk $fillable (mode strict)

Tambahkan ke $fillable

LazyLoadingViolationException

Relasi diakses tanpa eager loading

Gunakan with(), lihat artikel N+1

Policy tidak terpanggil

Nama model dan policy tidak sesuai konvensi

Beri nama ProductPolicy, atau daftarkan lewat Gate::policy()

Pint mengubah banyak berkas sekaligus

Gaya belum pernah diterapkan

Jalankan sekali dalam satu commit khusus agar diff mudah ditinjau

Larastan melaporkan ratusan error

Level terlalu tinggi untuk kode awal

Mulai dari level rendah, atau gunakan baseline

Best Practices

Keamanan

  • Validasi semua input lewat Form Request, dan gunakan $request->validated(), bukan $request->all().

  • Pasang $fillable eksplisit (hindari $guarded = []).

  • Otorisasi di Form Request atau Policy, jangan hanya menyembunyikan tombol di tampilan.

  • Simpan harga dalam bilangan bulat, dan hitung total di server.

Performa

  • Gunakan eager loading dan Model::shouldBeStrict() untuk menangkap N+1.

  • Tambahkan index pada kolom yang sering difilter (status, sku).

  • Paginasi semua daftar, dan jangan memakai ->get() untuk data tak terbatas.

Maintainability

  • Controller tipis: validasi, panggil service, kembalikan respons.

  • Service tidak mengenal Request atau Response, sehingga mudah diuji dan dipakai ulang dari command, job, atau API.

  • Jangan membuat repository, interface, dan lapisan lain sebelum ada kebutuhan nyata. Abstraksi dini menambah kerumitan tanpa manfaat.

  • Gunakan enum untuk nilai tetap, bukan string tersebar.

  • Jalankan composer check di CI sehingga gaya dan kualitas konsisten.

  • Dokumentasikan keputusan struktur di README.md atau docs/architecture.md.

Related Articles

Last Tested

Catatan jujur: kode disusun mengikuti konvensi Laravel 12/13 dan dokumentasi resmi, tetapi belum dijalankan ulang pada proyek nyata oleh penulis. Jalankan composer check pada proyek Anda, lalu isi tabel.

Komponen

Versi acuan penulisan

Versi saat Anda menguji

PHP

8.3.x

Laravel

13.x (kompatibel dengan 12.x)

Pint / Larastan

Rilis stabil terbaru

Database

MySQL 8.x atau SQLite

Tanggal uji

Bagikan artikel:

Artikel lainnya