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

Blog / Arsitektur / Cara Membangun CRUD Laravel ya...
Arsitektur

Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
14 min read
28 views

Controller tipis, validasi di Form Request, logika bisnis di Service, format respons di API Resource, dan otorisasi di Policy. Studi kasus: modul produk lengkap dengan upload gambar dan test.

Overview

CRUD pertama di proyek Laravel biasanya ditulis langsung di controller: validasi, upload file, simpan data, sinkron kategori, dan bentuk JSON, semua dalam satu method 80 baris. Ini berjalan, tetapi:

  • logika yang sama tidak bisa dipakai ulang dari command Artisan, job, atau importer Excel,
  • controller sulit diuji tanpa HTTP request,
  • format respons berbeda-beda antar endpoint,
  • aturan validasi store dan update di-copy-paste dan pelan-pelan tidak sinkron.

Artikel ini membagi tanggung jawab menjadi lapisan yang jelas:

Request ──► Form Request ──► Controller ──► Service ──► Model
            (validasi,        (mengatur     (logika      (data &
             otorisasi)        alur)         bisnis)      relasi)
                                  │
                                  ▼
                            API Resource ──► JSON Response
                            (format output)

Hasil akhir: endpoint index, store, show, update, dan destroy untuk produk, dengan filter dan paginasi, upload gambar, sinkron kategori, otorisasi per peran, format respons konsisten, dan feature test.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Database MySQL 8.0+ / PostgreSQL 15+
Autentikasi API Laravel Sanctum 4.x
Testing Pest 4

Siapkan route API dan Sanctum bila belum ada:

php artisan install:api

Tabel products, categories, dan category_product mengikuti artikel Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration, ditambah kolom image_path:

$table->string('image_path')->nullable()->after('description');

Step-by-step Tutorial

Langkah 1: Generate Semua File Sekaligus

php artisan make:controller Api/V1/ProductController --api --model=Product --requests
php artisan make:resource ProductResource
php artisan make:resource CategoryResource
php artisan make:policy ProductPolicy --model=Product
php artisan make:class Services/ProductService
php artisan make:test ProductApiTest --pest

Opsi --requests otomatis membuat StoreProductRequest dan UpdateProductRequest dan memakainya di signature controller.

Struktur yang dihasilkan:

app/
├── Http/
│   ├── Controllers/Api/V1/ProductController.php
│   ├── Requests/StoreProductRequest.php
│   ├── Requests/UpdateProductRequest.php
│   └── Resources/{ProductResource,CategoryResource}.php
├── Policies/ProductPolicy.php
└── Services/ProductService.php

Langkah 2: Model

// app/Models/Product.php
namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class Product extends Model
{
    use HasFactory;

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

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

    public function categories(): BelongsToMany
    {
        return $this->belongsToMany(Category::class);
    }

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

Langkah 3: Form Request untuk Validasi dan Otorisasi

// app/Http/Requests/StoreProductRequest.php
namespace App\Http\Requests;

use App\Models\Product;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Str;

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

    protected function prepareForValidation(): void
    {
        $this->merge([
            'sku'  => Str::upper(trim((string) $this->sku)),
            'slug' => $this->slug ?: Str::slug((string) $this->name),
        ]);
    }

    public function rules(): array
    {
        return [
            'sku'            => ['required', 'string', 'max:50', 'unique:products,sku'],
            'name'           => ['required', 'string', 'max:150'],
            'slug'           => ['required', 'string', 'max:170', 'alpha_dash', 'unique:products,slug'],
            'description'    => ['nullable', 'string', 'max:5000'],
            'price'          => ['required', 'integer', 'min:0', 'max:1000000000'],
            'stock'          => ['required', 'integer', 'min:0'],
            'is_active'      => ['sometimes', 'boolean'],
            'image'          => ['nullable', 'image', 'mimes:jpg,jpeg,png,webp', 'max:2048'],
            'category_ids'   => ['array'],
            'category_ids.*' => ['integer', 'distinct', 'exists:categories,id'],
        ];
    }

    public function attributes(): array
    {
        return [
            'sku'            => 'SKU',
            'name'           => 'nama produk',
            'price'          => 'harga',
            'stock'          => 'stok',
            'category_ids.*' => 'kategori',
        ];
    }
}

Untuk update, aturan unik harus mengabaikan produk yang sedang diedit, dan semua field bersifat opsional (sometimes) agar mendukung PATCH:

// app/Http/Requests/UpdateProductRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class UpdateProductRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->can('update', $this->route('product'));
    }

    public function rules(): array
    {
        $product = $this->route('product');

        return [
            'sku'            => ['sometimes', 'string', 'max:50', Rule::unique('products', 'sku')->ignore($product)],
            'name'           => ['sometimes', 'string', 'max:150'],
            'slug'           => ['sometimes', 'string', 'max:170', 'alpha_dash', Rule::unique('products', 'slug')->ignore($product)],
            'description'    => ['sometimes', 'nullable', 'string', 'max:5000'],
            'price'          => ['sometimes', 'integer', 'min:0', 'max:1000000000'],
            'stock'          => ['sometimes', 'integer', 'min:0'],
            'is_active'      => ['sometimes', 'boolean'],
            'image'          => ['sometimes', 'nullable', 'image', 'mimes:jpg,jpeg,png,webp', 'max:2048'],
            'category_ids'   => ['sometimes', 'array'],
            'category_ids.*' => ['integer', 'distinct', 'exists:categories,id'],
        ];
    }
}

Catatan: upload file lewat PUT/PATCH dengan multipart/form-data tidak diparsing oleh PHP. Klien perlu mengirim POST dengan field _method=PATCH, atau upload gambar lewat endpoint terpisah.

Langkah 4: Policy untuk Otorisasi

// app/Policies/ProductPolicy.php
namespace App\Policies;

use App\Models\{Product, User};

class ProductPolicy
{
    public function viewAny(?User $user): bool
    {
        return true;                                   // katalog publik
    }

    public function view(?User $user, Product $product): bool
    {
        return $product->is_active || $user?->hasRole('admin');
    }

    public function create(User $user): bool
    {
        return $user->hasAnyRole(['admin', 'staff']);
    }

    public function update(User $user, Product $product): bool
    {
        return $user->hasAnyRole(['admin', 'staff']);
    }

    public function delete(User $user, Product $product): bool
    {
        return $user->hasRole('admin');
    }
}

Laravel menemukan policy secara otomatis bila nama dan lokasinya mengikuti konvensi (App\Models\Product → App\Policies\ProductPolicy). Contoh hasRole() di sini memakai spatie/laravel-permission.

Langkah 5: Service untuk Logika Bisnis

Service menerima data yang sudah tervalidasi dan tidak tahu apa pun tentang HTTP. Ini yang membuatnya bisa dipakai dari controller, command, job, maupun importer.

// app/Services/ProductService.php
namespace App\Services;

use App\Models\Product;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;

class ProductService
{
    public function create(array $data, ?UploadedFile $image = null): Product
    {
        $path = $image?->store('products', 'public');

        try {
            return DB::transaction(function () use ($data, $path) {
                $product = Product::create([
                    ...Arr::except($data, ['category_ids', 'image']),
                    'image_path' => $path,
                ]);

                $product->categories()->sync($data['category_ids'] ?? []);

                return $product;
            });
        } catch (\Throwable $e) {
            if ($path) {
                Storage::disk('public')->delete($path);   // jangan tinggalkan file yatim
            }
            throw $e;
        }
    }

    public function update(Product $product, array $data, ?UploadedFile $image = null): Product
    {
        $oldPath = $product->image_path;
        $newPath = $image?->store('products', 'public');

        DB::transaction(function () use ($product, $data, $newPath) {
            $product->fill(Arr::except($data, ['category_ids', 'image']));

            if ($newPath) {
                $product->image_path = $newPath;
            }

            $product->save();

            if (array_key_exists('category_ids', $data)) {
                $product->categories()->sync($data['category_ids']);
            }
        });

        if ($newPath && $oldPath) {
            Storage::disk('public')->delete($oldPath);    // hapus setelah transaksi berhasil
        }

        return $product->refresh();
    }

    public function delete(Product $product): void
    {
        if ($product->orderItems()->exists()) {
            throw new \DomainException('Produk sudah pernah dipesan dan tidak dapat dihapus. Nonaktifkan saja.');
        }

        DB::transaction(function () use ($product) {
            $product->categories()->detach();
            $product->delete();
        });

        if ($product->image_path) {
            Storage::disk('public')->delete($product->image_path);
        }
    }
}

Hal-hal yang ditangani Service di atas, dan alasan tidak diletakkan di controller:

  • Transaksi: produk dan kategori tersimpan bersama, atau tidak sama sekali.
  • File: disimpan sebelum transaksi, dihapus bila transaksi gagal, dan file lama baru dihapus setelah transaksi sukses.
  • Aturan bisnis: produk yang sudah punya transaksi tidak boleh dihapus.
  • array_key_exists('category_ids'): membedakan "tidak mengirim kategori" (jangan diubah) dengan "mengirim array kosong" (hapus semua kategori).

Tambahkan relasi yang dipakai oleh aturan hapus:

// app/Models/Product.php
public function orderItems(): HasMany
{
    return $this->hasMany(OrderItem::class);
}

Langkah 6: API Resource untuk Format Respons

// app/Http/Resources/ProductResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\Facades\Storage;

class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'          => $this->id,
            'sku'         => $this->sku,
            'name'        => $this->name,
            'slug'        => $this->slug,
            'description' => $this->description,
            'price'       => $this->price,
            'price_label' => 'Rp '.number_format($this->price, 0, ',', '.'),
            'stock'       => $this->stock,
            'is_active'   => $this->is_active,
            'image_url'   => $this->image_path ? Storage::disk('public')->url($this->image_path) : null,
            'categories'  => CategoryResource::collection($this->whenLoaded('categories')),
            'created_at'  => $this->created_at?->toIso8601String(),
            'updated_at'  => $this->updated_at?->toIso8601String(),
        ];
    }
}
// app/Http/Resources/CategoryResource.php
public function toArray(Request $request): array
{
    return [
        'id'   => $this->id,
        'name' => $this->name,
        'slug' => $this->slug,
    ];
}

Resource memutuskan apa yang dikirim ke klien. Kolom internal (misalnya image_path mentah) tidak pernah bocor, dan perubahan nama kolom di database tidak otomatis mengubah kontrak API.

Langkah 7: Controller yang Tipis

// app/Http/Controllers/Api/V1/ProductController.php
namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\{StoreProductRequest, UpdateProductRequest};
use App\Http\Resources\ProductResource;
use App\Models\Product;
use App\Services\ProductService;
use Illuminate\Http\{JsonResponse, Request, Response};
use Illuminate\Support\Facades\Gate;

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

    public function index(Request $request)
    {
        $validated = $request->validate([
            'search'      => ['nullable', 'string', 'max:100'],
            'category_id' => ['nullable', 'integer'],
            'per_page'    => ['nullable', 'integer', 'min:1', 'max:50'],
        ]);

        $products = Product::query()
            ->with('categories:id,name,slug')
            ->search($validated['search'] ?? null)
            ->when($validated['category_id'] ?? null, fn ($q, $id) =>
                $q->whereHas('categories', fn ($q) => $q->whereKey($id)))
            ->when(! $request->user()?->hasRole('admin'), fn ($q) => $q->where('is_active', true))
            ->latest()
            ->paginate($validated['per_page'] ?? 15)
            ->withQueryString();

        return ProductResource::collection($products);
    }

    public function store(StoreProductRequest $request): JsonResponse
    {
        $product = $this->products->create(
            $request->safe()->except('image'),
            $request->file('image'),
        );

        return ProductResource::make($product->load('categories'))
            ->response()
            ->setStatusCode(Response::HTTP_CREATED);
    }

    public function show(Product $product): ProductResource
    {
        Gate::authorize('view', $product);

        return ProductResource::make($product->load('categories'));
    }

    public function update(UpdateProductRequest $request, Product $product): ProductResource
    {
        $product = $this->products->update(
            $product,
            $request->safe()->except('image'),
            $request->file('image'),
        );

        return ProductResource::make($product->load('categories'));
    }

    public function destroy(Product $product): Response
    {
        Gate::authorize('delete', $product);

        $this->products->delete($product);

        return response()->noContent();
    }
}

Setiap method controller sekarang hanya: menerima input yang sudah valid, memanggil service, dan mengembalikan resource.

Langkah 8: Route

// routes/api.php
use App\Http\Controllers\Api\V1\ProductController;

Route::prefix('v1')->group(function () {
    Route::get('products', [ProductController::class, 'index']);
    Route::get('products/{product:slug}', [ProductController::class, 'show']);

    Route::middleware('auth:sanctum')->group(function () {
        Route::apiResource('products', ProductController::class)->except(['index', 'show']);
    });
});
php artisan route:list --path=api/v1/products
  GET|HEAD   api/v1/products ............ Api\V1\ProductController@index
  POST       api/v1/products ............ Api\V1\ProductController@store
  GET|HEAD   api/v1/products/{product} .. Api\V1\ProductController@show
  PUT|PATCH  api/v1/products/{product} .. Api\V1\ProductController@update
  DELETE     api/v1/products/{product} .. Api\V1\ProductController@destroy

Langkah 9: Ubah Error Bisnis Menjadi Respons yang Rapi

DomainException dari service sebaiknya menjadi HTTP 422, bukan 500:

// bootstrap/app.php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (\DomainException $e, Request $request) {
        if ($request->expectsJson()) {
            return response()->json(['message' => $e->getMessage()], 422);
        }
    });
})

Pada proyek yang lebih besar, buat exception khusus (misalnya App\Exceptions\BusinessRuleException) agar tidak menangkap DomainException dari library lain.

Langkah 10: Feature Test

// tests/Feature/ProductApiTest.php
use App\Models\{Category, Product, User};
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;

beforeEach(function () {
    Storage::fake('public');
    $this->admin = User::factory()->create()->assignRole('admin');
});

it('membuat produk beserta kategori dan gambar', function () {
    $categories = Category::factory()->count(2)->create();

    $response = $this->actingAs($this->admin)->postJson('/api/v1/products', [
        'sku'          => 'prd-001',
        'name'         => 'Gamis Premium',
        'price'        => 250000,
        'stock'        => 10,
        'image'        => UploadedFile::fake()->image('gamis.jpg'),
        'category_ids' => $categories->pluck('id')->all(),
    ]);

    $response->assertCreated()
        ->assertJsonPath('data.sku', 'PRD-001')
        ->assertJsonPath('data.slug', 'gamis-premium')
        ->assertJsonCount(2, 'data.categories');

    Storage::disk('public')->assertExists(Product::first()->image_path);
});

it('menolak SKU yang sudah dipakai', function () {
    Product::factory()->create(['sku' => 'PRD-001']);

    $this->actingAs($this->admin)
        ->postJson('/api/v1/products', ['sku' => 'PRD-001', 'name' => 'X', 'price' => 1, 'stock' => 1])
        ->assertUnprocessable()
        ->assertJsonValidationErrors('sku');
});

it('melarang staf menghapus produk', function () {
    $staff = User::factory()->create()->assignRole('staff');
    $product = Product::factory()->create();

    $this->actingAs($staff)->deleteJson("/api/v1/products/{$product->id}")->assertForbidden();
});

it('tidak menghapus produk yang sudah pernah dipesan', function () {
    $product = Product::factory()->hasOrderItems(1)->create();

    $this->actingAs($this->admin)
        ->deleteJson("/api/v1/products/{$product->id}")
        ->assertUnprocessable();

    expect(Product::find($product->id))->not->toBeNull();
});
php artisan test --filter=ProductApiTest

Karena logika ada di service, Anda juga bisa menguji service secara langsung tanpa HTTP:

it('service menghapus kategori bila category_ids dikirim kosong', function () {
    $product = Product::factory()->hasCategories(2)->create();

    app(\App\Services\ProductService::class)->update($product, ['category_ids' => []]);

    expect($product->categories()->count())->toBe(0);
});

Troubleshooting

Error / Gejala Penyebab Solusi
403 This action is unauthorized authorize() di Form Request atau Policy mengembalikan false Periksa peran pengguna dan method policy yang dipanggil
422 dengan sku has already been taken saat update Aturan unique tidak mengabaikan data yang sedang diedit Gunakan Rule::unique(...)->ignore($product)
File gambar tidak terkirim saat PUT PHP tidak memparsing multipart/form-data untuk PUT/PATCH Kirim POST dengan _method=PATCH
Gambar 404 di browser Tautan storage belum dibuat atau APP_URL salah php artisan storage:link, periksa APP_URL
Add [sku] to fillable property Kolom tidak ada di $fillable Tambahkan ke $fillable
Kategori terhapus padahal tidak dikirim Service memanggil sync($data['category_ids'] ?? []) saat update Sync hanya bila key ada (array_key_exists)
Respons 500 saat menghapus produk bertransaksi DomainException tidak dipetakan Render menjadi 422 di bootstrap/app.php
Route model binding memakai id, bukan slug Parameter route tidak menyebut kolom Gunakan {product:slug}
Relasi categories tidak muncul di JSON Resource memakai whenLoaded tetapi relasi tidak dimuat Panggil load('categories') atau with() di controller

Best Practices

Keamanan

  • Selalu kirim $request->validated() atau $request->safe() ke service, jangan $request->all().
  • Batasi tipe dan ukuran file upload (image, mimes, max), dan simpan dengan nama acak (perilaku bawaan store()).
  • Letakkan otorisasi di Policy dan panggil dari Form Request atau Gate::authorize(), bukan if peran yang tersebar di controller.
  • Batasi per_page agar klien tidak bisa meminta jutaan baris sekaligus.

Performa

  • Eager load relasi di index dan pakai whenLoaded di Resource untuk mencegah N+1.
  • Tambahkan indeks untuk kolom yang dipakai filter (is_active, slug, sku).
  • Untuk gambar, buat thumbnail di queue job agar request tetap cepat.

Maintainability

  • Controller hanya mengatur alur; logika bisnis di service; format output di resource.
  • Service menerima array atau DTO yang sudah valid, tidak menerima objek Request.
  • Pisahkan Store dan Update Form Request walaupun mirip; perbedaannya (unik, opsional) penting.
  • Versikan API (/api/v1) sejak awal.
  • Jangan memecah lebih jauh (repository, action, DTO) sebelum ada kebutuhan nyata. Lihat artikel Repository Pattern di Laravel untuk pertimbangannya.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
Laravel Sanctum 4.x
spatie/laravel-permission rilis terbaru yang mendukung Laravel 13
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya