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

Blog / Arsitektur / Repository Pattern di Laravel:...
Arsitektur

Repository Pattern di Laravel: Kapan Dibutuhkan dan Kapan Justru Menambah Kompleksitas?

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
12 min read
13 views

Implementasi repository yang benar, kritik yang jujur terhadap repository "pembungkus Eloquent", alternatif yang lebih ringan, dan daftar periksa untuk memutuskan apakah proyek Anda benar-benar membutuhkannya.

Overview

Repository pattern sering diperkenalkan sebagai "best practice wajib". Banyak proyek Laravel kemudian memiliki struktur seperti ini:

ProductController → ProductService → ProductRepositoryInterface → EloquentProductRepository → Product (Eloquent)

Untuk setiap model, ada interface dan implementasi yang isinya hanya meneruskan panggilan ke Eloquent: find(), create(), update(), delete(). Hasilnya, menambah satu kolom filter menyentuh empat file, dan tidak ada manfaat nyata yang didapat.

Di sisi lain, ada situasi di mana repository benar-benar menyelamatkan proyek: sumber data bukan database lokal, query kompleks dipakai di banyak tempat, atau aplikasi harus berjalan dengan dua backend penyimpanan berbeda.

Hasil akhir artikel ini:

  • memahami masalah yang sebenarnya diselesaikan repository,
  • implementasi repository yang bermakna (bukan sekadar pembungkus),
  • contoh anti-pattern dan alasan ia merugikan,
  • alternatif yang lebih ringan: scope, custom Eloquent Builder, query object, dan action class,
  • daftar periksa keputusan yang bisa dipakai dalam diskusi tim.

Prerequisites

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

Diasumsikan Anda sudah membaca Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource, karena contoh di sini melanjutkan modul produk dari artikel tersebut.

Step-by-step Tutorial

Langkah 1: Pahami Masalah Asli yang Diselesaikan Repository

Repository berasal dari Domain-Driven Design dan dirancang untuk:

  1. Memisahkan logika domain dari detail penyimpanan. Domain bekerja dengan "koleksi objek", tidak tahu apakah datanya dari MySQL, API, atau file.
  2. Mengumpulkan query yang mewakili konsep bisnis di satu tempat.
  3. Memungkinkan penggantian implementasi penyimpanan.

Masalahnya, Eloquent adalah pola Active Record: model itu sendiri sudah tahu cara menyimpan dirinya. Ketika Anda mengembalikan model Eloquent dari repository, domain tetap terikat ke Eloquent ($product->save(), $product->categories() masih bisa dipanggil di mana saja). Abstraksinya bocor.

Itu sebabnya repository di Laravel hanya bernilai bila ia memberikan sesuatu yang tidak sudah diberikan Eloquent.

Langkah 2: Kenali Anti-pattern "Pembungkus Eloquent"

// Anti-pattern: tidak menambah nilai apa pun
interface ProductRepositoryInterface
{
    public function all();
    public function find(int $id);
    public function create(array $data);
    public function update(int $id, array $data);
    public function delete(int $id);
}

class EloquentProductRepository implements ProductRepositoryInterface
{
    public function all()                         { return Product::all(); }
    public function find(int $id)                 { return Product::find($id); }
    public function create(array $data)           { return Product::create($data); }
    public function update(int $id, array $data)  { return Product::find($id)->update($data); }
    public function delete(int $id)               { return Product::destroy($id); }
}

Masalah konkretnya:

Masalah Dampak
Hanya meneruskan panggilan Dua file tambahan per model, tanpa logika
Mengembalikan model Eloquent Pemanggil tetap bergantung pada Eloquent; abstraksi semu
all() tanpa batas Mendorong pemuatan seluruh tabel
Kehilangan fitur Laravel Route model binding, eager loading fleksibel, scope, paginasi harus dibungkus ulang
"Agar bisa ganti database" Eloquent sudah mendukung MySQL, PostgreSQL, SQLite, SQL Server; mengganti ORM hampir tidak pernah terjadi
"Agar mudah di-test" Laravel sudah menyediakan database test yang cepat (RefreshDatabase, SQLite in-memory)

Gejala lain: repository mulai berisi method seperti findWithCategoriesAndOrdersPaginatedByStatus(), karena setiap variasi query membutuhkan method baru.

Langkah 3: Coba Alternatif Ringan Terlebih Dahulu

Sebagian besar alasan memakai repository bisa dipenuhi dengan fitur bawaan Eloquent.

a. Local scope untuk kondisi yang dipakai berulang:

// app/Models/Product.php
public function scopeActive(Builder $query): void
{
    $query->where('is_active', true);
}

public function scopeInStock(Builder $query): void
{
    $query->where('stock', '>', 0);
}
Product::active()->inStock()->paginate();

b. Custom Eloquent Builder bila scope sudah banyak dan membuat model gemuk:

// app/Models/Builders/ProductBuilder.php
namespace App\Models\Builders;

use Illuminate\Database\Eloquent\Builder;

/** @extends Builder<\App\Models\Product> */
class ProductBuilder extends Builder
{
    public function active(): self
    {
        return $this->where('is_active', true);
    }

    public function inCategory(string $slug): self
    {
        return $this->whereHas('categories', fn ($q) => $q->where('slug', $slug));
    }

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

    public function bestSelling(int $days = 30): self
    {
        return $this->withSum(['orderItems as sold_qty' => fn ($q) => $q
            ->whereHas('order', fn ($o) => $o->where('placed_at', '>=', now()->subDays($days)))
        ], 'quantity')->orderByDesc('sold_qty');
    }
}
// app/Models/Product.php
use App\Models\Builders\ProductBuilder;

public function newEloquentBuilder($query): ProductBuilder
{
    return new ProductBuilder($query);
}
Product::query()->active()->inCategory('gamis')->bestSelling()->take(10)->get();

Keuntungannya: query bisa dirangkai, autocompletion IDE bekerja, dan seluruh fitur Eloquent (paginasi, eager loading, route binding) tetap tersedia.

c. Query object untuk query laporan yang kompleks (lihat artikel Laravel Query Builder vs Eloquent ORM):

final class SalesReportQuery
{
    public function dailyByCategory(CarbonInterface $from, CarbonInterface $to): Collection { /* ... */ }
}

d. Action class untuk satu operasi bisnis yang terdefinisi jelas:

// app/Actions/Products/AdjustStock.php
final class AdjustStock
{
    public function handle(Product $product, int $delta, string $reason): Product
    {
        return DB::transaction(function () use ($product, $delta, $reason) {
            $product = Product::lockForUpdate()->findOrFail($product->id);

            if ($product->stock + $delta < 0) {
                throw new \DomainException('Stok tidak mencukupi.');
            }

            $product->increment('stock', $delta);
            $product->stockMovements()->create(['delta' => $delta, 'reason' => $reason]);

            return $product->refresh();
        });
    }
}

Jika salah satu dari alternatif ini sudah menjawab kebutuhan Anda, Anda tidak membutuhkan repository.

Langkah 4: Kapan Repository Benar-benar Bernilai

Kasus 1: Sumber data bukan (hanya) database lokal

Contoh: data produk sebenarnya milik ERP gudang, diakses lewat REST API, dan aplikasi Laravel hanya menyimpan cache-nya. Di sini abstraksi "koleksi produk" benar-benar menyembunyikan detail penting: HTTP, retry, mapping, dan cache.

Kasus 2: Aplikasi yang sama dijual dengan backend penyimpanan berbeda

Contoh: produk SaaS Anda menyimpan dokumen di database untuk paket standar dan di layanan penyimpanan eksternal untuk paket enterprise.

Kasus 3: Domain dimodelkan dengan objek murni (bukan model Eloquent)

Bila tim memang menerapkan arsitektur heksagonal atau DDD penuh, di mana entitas domain adalah class PHP biasa, repository adalah tempat konversi antara entitas domain dan Eloquent.

Kasus 4: Integrasi lama (legacy)

Database lama dengan nama tabel dan kolom yang tidak mengikuti konvensi, atau stored procedure yang wajib dipakai.

Langkah 5: Implementasi Repository yang Bermakna

Contoh untuk Kasus 1: katalog produk yang sumber kebenarannya adalah ERP.

Kontrak berbicara dalam bahasa domain, mengembalikan DTO, bukan model Eloquent:

// app/Domain/Catalog/ProductData.php
namespace App\Domain\Catalog;

final readonly class ProductData
{
    public function __construct(
        public string $sku,
        public string $name,
        public int $price,
        public int $stock,
    ) {}
}
// app/Domain/Catalog/ProductCatalog.php
namespace App\Domain\Catalog;

interface ProductCatalog
{
    public function findBySku(string $sku): ?ProductData;

    /** @return list<ProductData> */
    public function changedSince(\DateTimeInterface $since): array;

    public function reserveStock(string $sku, int $quantity): void;
}

Perhatikan bahwa nama method mencerminkan kebutuhan bisnis (reserveStock, changedSince), bukan operasi CRUD generik.

Implementasi ERP lewat HTTP:

// app/Infrastructure/Catalog/ErpProductCatalog.php
namespace App\Infrastructure\Catalog;

use App\Domain\Catalog\{ProductCatalog, ProductData};
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\{Cache, Http};

final class ErpProductCatalog implements ProductCatalog
{
    public function __construct(
        private readonly string $baseUrl,
        private readonly string $token,
    ) {}

    private function client(): PendingRequest
    {
        return Http::baseUrl($this->baseUrl)
            ->withToken($this->token)
            ->acceptJson()
            ->timeout(5)
            ->retry(3, 200, throw: false);
    }

    public function findBySku(string $sku): ?ProductData
    {
        return Cache::remember("erp:product:{$sku}", now()->addMinutes(5), function () use ($sku) {
            $response = $this->client()->get("/items/{$sku}");

            if ($response->notFound()) {
                return null;
            }

            return $this->map($response->throw()->json('data'));
        });
    }

    public function changedSince(\DateTimeInterface $since): array
    {
        $items = $this->client()
            ->get('/items', ['updated_after' => $since->format(DATE_ATOM)])
            ->throw()
            ->json('data');

        return array_map($this->map(...), $items);
    }

    public function reserveStock(string $sku, int $quantity): void
    {
        $this->client()->post("/items/{$sku}/reservations", ['qty' => $quantity])->throw();
        Cache::forget("erp:product:{$sku}");
    }

    private function map(array $row): ProductData
    {
        return new ProductData(
            sku: $row['item_code'],
            name: $row['item_name'],
            price: (int) round($row['sell_price']),
            stock: (int) $row['qty_available'],
        );
    }
}

Implementasi database lokal, misalnya untuk mode offline atau pelanggan tanpa ERP:

// app/Infrastructure/Catalog/DatabaseProductCatalog.php
final class DatabaseProductCatalog implements ProductCatalog
{
    public function findBySku(string $sku): ?ProductData
    {
        $p = Product::query()->active()->where('sku', $sku)->first();

        return $p ? new ProductData($p->sku, $p->name, $p->price, $p->stock) : null;
    }

    public function changedSince(\DateTimeInterface $since): array
    {
        return Product::where('updated_at', '>=', $since)->get()
            ->map(fn ($p) => new ProductData($p->sku, $p->name, $p->price, $p->stock))
            ->all();
    }

    public function reserveStock(string $sku, int $quantity): void
    {
        $affected = Product::where('sku', $sku)->where('stock', '>=', $quantity)->decrement('stock', $quantity);

        if ($affected === 0) {
            throw new \DomainException("Stok {$sku} tidak mencukupi.");
        }
    }
}

Binding berdasarkan konfigurasi:

// config/catalog.php
return [
    'driver' => env('CATALOG_DRIVER', 'database'),   // database | erp
    'erp' => [
        'url'   => env('ERP_URL'),
        'token' => env('ERP_TOKEN'),
    ],
];
// app/Providers/AppServiceProvider.php
use App\Domain\Catalog\ProductCatalog;
use App\Infrastructure\Catalog\{DatabaseProductCatalog, ErpProductCatalog};

public function register(): void
{
    $this->app->singleton(ProductCatalog::class, fn () => match (config('catalog.driver')) {
        'erp'   => new ErpProductCatalog(config('catalog.erp.url'), config('catalog.erp.token')),
        default => new DatabaseProductCatalog(),
    });
}

Pemakaian di service checkout, yang kini tidak tahu sumber data produk:

final class CheckoutService
{
    public function __construct(private readonly ProductCatalog $catalog) {}

    public function addLine(Order $order, string $sku, int $qty): void
    {
        $product = $this->catalog->findBySku($sku)
            ?? throw new \DomainException("Produk {$sku} tidak ditemukan.");

        $this->catalog->reserveStock($sku, $qty);

        $order->items()->create([
            'product_sku'  => $product->sku,
            'product_name' => $product->name,
            'unit_price'   => $product->price,
            'quantity'     => $qty,
            'line_total'   => $product->price * $qty,
        ]);
    }
}

Langkah 6: Uji dengan Implementasi Palsu

Di sinilah repository memberikan nilai pengujian yang nyata: Anda tidak perlu memanggil ERP sungguhan.

// tests/Fakes/InMemoryProductCatalog.php
final class InMemoryProductCatalog implements ProductCatalog
{
    /** @var array<string, ProductData> */
    public array $items = [];
    public array $reserved = [];

    public function findBySku(string $sku): ?ProductData { return $this->items[$sku] ?? null; }
    public function changedSince(\DateTimeInterface $since): array { return array_values($this->items); }

    public function reserveStock(string $sku, int $quantity): void
    {
        $this->reserved[$sku] = ($this->reserved[$sku] ?? 0) + $quantity;
    }
}
it('memakai harga dari katalog saat menambah item', function () {
    $catalog = new InMemoryProductCatalog();
    $catalog->items['PRD-1'] = new ProductData('PRD-1', 'Gamis', 250000, 5);
    $this->app->instance(ProductCatalog::class, $catalog);

    $order = Order::factory()->create();
    app(CheckoutService::class)->addLine($order, 'PRD-1', 2);

    expect($order->items()->first()->line_total)->toBe(500000)
        ->and($catalog->reserved['PRD-1'])->toBe(2);
});

Untuk implementasi ERP itu sendiri, uji dengan Http::fake():

it('memetakan respons ERP ke ProductData', function () {
    Http::fake(['erp.test/items/PRD-1' => Http::response(['data' => [
        'item_code' => 'PRD-1', 'item_name' => 'Gamis', 'sell_price' => 250000.0, 'qty_available' => 7,
    ]])]);

    $catalog = new ErpProductCatalog('https://erp.test', 'token');

    expect($catalog->findBySku('PRD-1'))->stock->toBe(7);
});

Langkah 7: Daftar Periksa Keputusan

Jawab pertanyaan berikut sebelum menambahkan repository:

Pertanyaan Jika "Ya"
Apakah sumber data bukan database aplikasi (API, ERP, file, layanan lain)? Repository layak dipertimbangkan
Apakah ada lebih dari satu implementasi penyimpanan yang benar-benar akan dipakai? Repository layak
Apakah domain dimodelkan dengan objek murni, bukan model Eloquent? Repository diperlukan
Apakah hanya ingin "rapi" atau "sesuai best practice"? Gunakan scope / custom builder
Apakah query kompleks dipakai di banyak tempat? Custom builder atau query object dulu
Apakah hanya ingin mudah di-test? Gunakan database test Laravel
Apakah tim kecil dan tenggat ketat? Hindari lapisan tambahan

Aturan praktis: tambahkan repository untuk batas sistem (boundary), bukan untuk setiap model. Dalam satu aplikasi, sangat wajar bila hanya satu atau dua konsep yang memakai repository, sementara sisanya memakai Eloquent langsung melalui service atau action.

Troubleshooting

Error / Gejala Penyebab Solusi
Target [App\Domain\Catalog\ProductCatalog] is not instantiable Interface belum di-bind ke implementasi Daftarkan binding di register() service provider
Implementasi yang dipakai tidak berubah setelah ganti .env Konfigurasi masih di-cache php artisan config:clear lalu config:cache
Repository punya puluhan method findBy... Repository dipakai sebagai pengganti query builder Pindahkan ke custom Eloquent Builder atau query object
N+1 query di balik repository Repository mengembalikan model tanpa eager loading yang dibutuhkan pemanggil Kembalikan DTO lengkap, atau jangan bungkus Eloquent dengan repository
Paginasi dan route model binding jadi rumit Repository menyembunyikan fitur Eloquent Evaluasi ulang: apakah repository memang dibutuhkan untuk model ini?
Test lambat karena memanggil API sungguhan Implementasi asli dipakai di test Ganti dengan $this->app->instance(...) atau Http::fake()
Singleton menyimpan state antar request (Octane) Implementasi menyimpan data di properti Buat implementasi stateless, atau gunakan scoped() alih-alih singleton()

Best Practices

Keamanan

  • Simpan kredensial integrasi (token ERP) di .env dan baca lewat config(), jangan di implementasi repository.
  • Validasi dan petakan data dari sistem eksternal ke DTO; jangan percaya bentuk respons begitu saja.
  • Beri timeout dan retry terbatas pada implementasi berbasis HTTP agar kegagalan sistem lain tidak membuat aplikasi menggantung.

Performa

  • Cache hasil dari sumber eksternal yang lambat di dalam implementasi repository, dan invalidasi saat data berubah.
  • Hindari method generik seperti all(); sediakan method yang spesifik dan terbatas.
  • Jangan mengembalikan model Eloquent dari repository yang dimaksudkan sebagai abstraksi, karena pemanggil bisa memicu lazy loading tanpa sadar.

Maintainability

  • Mulai dari yang paling sederhana: Eloquent langsung → scope → custom builder → query object / action → repository.
  • Nama method repository mencerminkan bahasa bisnis, bukan operasi database.
  • Satu repository per konsep di batas sistem, bukan satu per tabel.
  • Dokumentasikan alasan setiap repository ada (misalnya di docblock interface), agar tidak ditiru secara membabi buta untuk model lain.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya