Repository Pattern di Laravel: Kapan Dibutuhkan dan Kapan Justru Menambah Kompleksitas?
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
| 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.
Repository berasal dari Domain-Driven Design dan dirancang untuk:
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.
// 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.
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.
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.
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,
]);
}
}
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);
});
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.
| 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() |
Keamanan
.env dan baca lewat config(), jangan di implementasi repository.Performa
all(); sediakan method yang spesifik dan terbatas.Maintainability
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource
Berikutnya
Soft Delete, Audit Trail, dan Activity Log: Cara Melacak Perubahan Data Aplikasi
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk