Tiga jenis relasi inti Eloquent dijelaskan lewat satu studi kasus toko online: struktur tabel, definisi di model, cara membaca dan menulis data, sampai tabel pivot dengan data tambahan.
Overview
Relasi Eloquent membuat kode seperti $order->customer->name terasa alami. Namun banyak bug muncul dari salah paham hal-hal dasar: di tabel mana foreign key diletakkan, kapan memakai belongsTo vs hasOne, atau kenapa attach() menghasilkan baris duplikat.
Artikel ini memakai skema toko online dari artikel Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration:
| Relasi | Contoh |
|---|---|
| One-to-One | User ↔ Customer (akun login dan profil pelanggan) |
| One-to-Many | Customer → Order, Order → OrderItem |
| Many-to-Many | Product ↔ Category, dan Order ↔ Product lewat pivot berisi data |
Hasil akhir: Anda memahami aturan peletakan foreign key, bisa mendefinisikan relasi dua arah, membaca dan menulis data relasi dengan benar, serta memakai pivot model kustom. Di bagian akhir, ada test otomatis untuk memastikan relasi bekerja.
Prerequisites
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x (berlaku juga untuk 11 dan 12) |
| Database | MySQL 8.0+ / PostgreSQL 15+ / SQLite untuk latihan |
| Testing | Pest 3/4 atau PHPUnit 11+ |
Skema dan migration dasar mengikuti artikel sebelumnya. Jika Anda mulai dari nol, buat model beserta migration dan factory:
php artisan make:model Customer -mf
php artisan make:model Order -mf
php artisan make:model Product -mf
php artisan make:model Category -mf
Step-by-step Tutorial
Aturan Emas: Siapa Memegang Foreign Key?
Sebelum menulis kode, ingat satu aturan:
Model yang tabelnya menyimpan foreign key memakai
belongsTo. Pasangannya memakaihasOneatauhasMany.
| Tabel dengan FK | Sisi FK | Sisi lawan |
|---|---|---|
customers.user_id |
Customer belongsTo User |
User hasOne Customer |
orders.customer_id |
Order belongsTo Customer |
Customer hasMany Order |
pivot category_product |
Product belongsToMany Category |
Category belongsToMany Product |
Bagian 1: One-to-One (User ↔ Customer)
Akun login (users) dipisah dari profil pelanggan (customers) karena admin juga user, tetapi bukan pelanggan.
Migration:
Schema::create('customers', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->unique()->constrained()->cascadeOnDelete();
$table->string('phone', 20)->nullable();
$table->date('birth_date')->nullable();
$table->timestamps();
});
unique() pada user_id adalah yang membuat relasi ini benar-benar satu-ke-satu di level database. Tanpa itu, secara teknis satu user bisa punya dua profil.
Model:
// app/Models/User.php
use Illuminate\Database\Eloquent\Relations\HasOne;
public function customer(): HasOne
{
return $this->hasOne(Customer::class);
}
// app/Models/Customer.php
use Illuminate\Database\Eloquent\Relations\BelongsTo;
class Customer extends Model
{
protected $fillable = ['user_id', 'phone', 'birth_date'];
public function user(): BelongsTo
{
return $this->belongsTo(User::class);
}
}
Membaca dan menulis:
$user = User::find(1);
$user->customer?->phone; // akses properti -> query dijalankan sekali, hasil di-cache
// Membuat profil melalui relasi: user_id terisi otomatis
$user->customer()->create(['phone' => '081234567890']);
// Membuat atau memperbarui profil
$user->customer()->updateOrCreate([], ['phone' => '089876543210']);
// Dari sisi belongsTo
$customer = Customer::find(1);
$customer->user->email;
Perbedaan penting: $user->customer (properti) menjalankan query dan mengembalikan model, sedangkan $user->customer() (method) mengembalikan query builder relasi yang bisa dirangkai.
Nilai bawaan untuk relasi yang mungkin kosong, agar tidak perlu ?-> di view:
public function user(): BelongsTo
{
return $this->belongsTo(User::class)->withDefault([
'name' => 'Pengguna dihapus',
]);
}
Bagian 2: One-to-Many (Customer → Order → OrderItem)
Model:
// app/Models/Customer.php
use Illuminate\Database\Eloquent\Relations\HasMany;
public function orders(): HasMany
{
return $this->hasMany(Order::class);
}
// app/Models/Order.php
use Illuminate\Database\Eloquent\Relations\{BelongsTo, HasMany};
public function customer(): BelongsTo
{
return $this->belongsTo(Customer::class);
}
public function items(): HasMany
{
return $this->hasMany(OrderItem::class);
}
Membaca:
$customer = Customer::find(1);
$customer->orders; // Collection seluruh pesanan
$customer->orders()->where('status', 'paid')->count(); // query di database
$customer->orders()->latest('placed_at')->first();
Hindari $customer->orders->where(...) untuk data besar: itu memuat semua pesanan ke memori dulu, baru menyaring di PHP. Gunakan method orders() agar penyaringan terjadi di SQL.
Menulis:
$order = $customer->orders()->create([
'code' => 'INV-20261019-0001',
'address_snapshot' => ['city' => 'Depok'],
'subtotal' => 500000,
'total' => 520000,
]);
$order->items()->createMany([
['product_id' => 3, 'product_name' => 'Gamis Premium', 'unit_price' => 250000, 'quantity' => 2, 'line_total' => 500000],
]);
// Memindahkan pesanan ke pelanggan lain dari sisi belongsTo
$order->customer()->associate($otherCustomer);
$order->save();
Relasi "satu dari banyak", misalnya pesanan terakhir pelanggan. Ini jauh lebih efisien daripada mengambil semua pesanan lalu mengambil yang pertama:
// app/Models/Customer.php
use Illuminate\Database\Eloquent\Relations\HasOne;
public function latestOrder(): HasOne
{
return $this->hasOne(Order::class)->latestOfMany('placed_at');
}
$customers = Customer::with('latestOrder')->get(); // satu query tambahan, bukan N query
Relasi lewat perantara (hasManyThrough): semua item yang pernah dibeli seorang pelanggan, melalui orders:
public function orderItems(): HasManyThrough
{
return $this->hasManyThrough(OrderItem::class, Order::class);
}
Bagian 3: Many-to-Many Sederhana (Product ↔ Category)
Migration pivot (nama tabel tunggal, urut abjad):
Schema::create('category_product', function (Blueprint $table) {
$table->foreignId('category_id')->constrained()->cascadeOnDelete();
$table->foreignId('product_id')->constrained()->cascadeOnDelete();
$table->primary(['category_id', 'product_id']);
});
Model:
// app/Models/Product.php
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
public function categories(): BelongsToMany
{
return $this->belongsToMany(Category::class);
}
// app/Models/Category.php
public function products(): BelongsToMany
{
return $this->belongsToMany(Product::class);
}
Mengelola isi pivot. Pilih method sesuai niat:
| Method | Efek | Contoh kasus |
|---|---|---|
attach([1, 2]) |
Menambah baris; error bila sudah ada (karena primary key) | Menambah satu kategori baru |
detach([2]) |
Menghapus baris tertentu; detach() tanpa argumen menghapus semua |
Melepas kategori |
sync([1, 3]) |
Menyamakan isi pivot persis dengan daftar | Form edit produk dengan checkbox kategori |
syncWithoutDetaching([4]) |
Menambah yang belum ada, tidak menghapus | Impor data bertahap |
toggle([1, 5]) |
Lepas jika ada, pasang jika belum | Tombol favorit |
$product = Product::find(10);
$product->categories()->sync($request->validated('category_ids'));
$changes = $product->categories()->sync([1, 3]);
// ['attached' => [3], 'detached' => [2], 'updated' => []]
Nilai kembalian sync() berguna untuk activity log: Anda tahu persis apa yang berubah.
Query berdasarkan relasi:
// Produk yang punya kategori dengan slug "gamis"
Product::whereHas('categories', fn ($q) => $q->where('slug', 'gamis'))->get();
// Produk tanpa kategori
Product::doesntHave('categories')->get();
// Jumlah produk per kategori
Category::withCount('products')->orderByDesc('products_count')->get();
Bagian 4: Many-to-Many dengan Data Pivot (Order ↔ Product)
Item pesanan sebenarnya adalah relasi N:M antara orders dan products yang membawa data: quantity, unit_price, line_total. Ada dua cara memodelkannya.
Cara A: belongsToMany dengan withPivot (cocok untuk data pivot sederhana):
// app/Models/Order.php
public function products(): BelongsToMany
{
return $this->belongsToMany(Product::class, 'order_items')
->withPivot(['product_name', 'unit_price', 'quantity', 'line_total'])
->as('line'); // ganti nama ->pivot menjadi ->line
}
foreach ($order->products as $product) {
echo $product->name.' x '.$product->line->quantity;
}
$order->products()->attach($product->id, [
'product_name' => $product->name,
'unit_price' => $product->price,
'quantity' => 2,
'line_total' => $product->price * 2,
]);
$order->products()->updateExistingPivot($product->id, ['quantity' => 3, 'line_total' => $product->price * 3]);
Cara B: pivot model kustom (cocok bila pivot punya logika, cast, atau event):
php artisan make:model OrderItem --pivot
// app/Models/OrderItem.php
namespace App\Models;
use Illuminate\Database\Eloquent\Relations\Pivot;
class OrderItem extends Pivot
{
protected $table = 'order_items';
public $incrementing = true; // tabel order_items punya kolom id
public $timestamps = false;
protected function casts(): array
{
return [
'unit_price' => 'integer',
'quantity' => 'integer',
'line_total' => 'integer',
];
}
protected static function booted(): void
{
static::saving(function (OrderItem $item) {
$item->line_total = $item->unit_price * $item->quantity;
});
}
}
// app/Models/Order.php
public function products(): BelongsToMany
{
return $this->belongsToMany(Product::class, 'order_items')
->using(OrderItem::class)
->withPivot(['id', 'product_name', 'unit_price', 'quantity', 'line_total']);
}
Dalam praktik, banyak tim memakai kedua sisi: relasi items() (hasMany(OrderItem::class)) untuk mengelola baris item sebagai entitas, dan products() untuk query "produk apa saja di pesanan ini". Keduanya menunjuk tabel yang sama.
Catatan: event model (
saving,created) pada pivot kustom hanya terpicu untuk operasi yang melalui model pivot.attach()dansync()memicu event pivot bila relasi memakaiusing(), tetapi query massal sepertiDB::table('order_items')->update()tidak memicu event apa pun.
Bagian 5: Relasi Rekursif (Kategori Induk-Anak)
// app/Models/Category.php
public function parent(): BelongsTo
{
return $this->belongsTo(Category::class, 'parent_id');
}
public function children(): HasMany
{
return $this->hasMany(Category::class, 'parent_id');
}
$tree = Category::whereNull('parent_id')->with('children.children')->get();
Untuk hierarki yang dalam dan sering dibaca, pertimbangkan paket nested set atau recursive CTE, karena eager loading bertingkat tetap terbatas pada kedalaman yang Anda tulis.
Bagian 6: Uji Relasi dengan Test Otomatis
Factory memudahkan pembuatan data berelasi:
// database/factories/OrderFactory.php
public function definition(): array
{
return [
'customer_id' => Customer::factory(),
'code' => 'INV-'.fake()->unique()->numerify('########'),
'address_snapshot' => ['city' => fake()->city()],
'status' => 'pending',
'subtotal' => 100000,
'total' => 100000,
'placed_at' => now(),
];
}
// tests/Feature/OrderRelationshipTest.php
use App\Models\{Customer, Order, Product, Category};
it('mengaitkan pesanan dengan pelanggan', function () {
$customer = Customer::factory()->has(Order::factory()->count(3))->create();
expect($customer->orders)->toHaveCount(3)
->and($customer->orders->first()->customer->is($customer))->toBeTrue();
});
it('sync kategori hanya menyisakan kategori yang dipilih', function () {
$product = Product::factory()->hasAttached(Category::factory()->count(3))->create();
$keep = $product->categories->first();
$product->categories()->sync([$keep->id]);
expect($product->fresh()->categories)->toHaveCount(1);
});
it('menghitung line_total lewat pivot kustom', function () {
$order = Order::factory()->create();
$product = Product::factory()->create(['price' => 50000]);
$order->products()->attach($product, [
'product_name' => $product->name,
'unit_price' => 50000,
'quantity' => 3,
]);
expect($order->products->first()->pivot->line_total)->toBe(150000);
});
php artisan test --filter=OrderRelationshipTest
Troubleshooting
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
Attempt to read property "name" on null |
Relasi belongsTo kosong (FK null atau data induk hilang) |
Pakai ?->, withDefault(), atau pastikan FK wajib diisi |
Call to undefined method ...::addEagerConstraints() |
Method relasi tidak mengembalikan objek relasi (lupa return) |
Pastikan method mengembalikan $this->hasMany(...) dan beri return type |
Base table or view not found: 'product_category' |
Nama tabel pivot tidak sesuai konvensi | Ikuti urutan abjad (category_product) atau berikan nama tabel sebagai argumen kedua |
Unknown column 'orders.customers_id' |
FK tidak mengikuti konvensi {model}_id |
Sebutkan FK secara eksplisit: hasMany(Order::class, 'buyer_id') |
Duplicate entry ... for key PRIMARY saat attach() |
Relasi sudah ada | Gunakan syncWithoutDetaching() |
| Data pivot tambahan tidak muncul | Kolom tidak didaftarkan | Tambahkan ->withPivot([...]) |
| Event pada pivot model tidak berjalan | Relasi tidak memakai using(), atau penulisan lewat query builder |
Daftarkan ->using(OrderItem::class) dan tulis lewat relasi |
| Halaman daftar sangat lambat | N+1 query karena relasi diakses di dalam loop | Lihat artikel Mengatasi Masalah N+1 Query |
Best Practices
Keamanan
- Jangan memasukkan
user_idataucustomer_iddari input form secara langsung. Buat lewat relasi ($request->user()->customer->orders()->create(...)), sehingga FK diisi oleh server. - Validasi ID yang akan di-
sync():'category_ids.*' => ['integer', 'exists:categories,id']. - Gunakan Policy untuk memastikan pengguna hanya mengakses data relasinya sendiri.
Performa
- Selalu eager load relasi yang dipakai di daftar (
with()), dan aktifkanModel::preventLazyLoading()di lingkungan development. - Gunakan
withCount(),withSum(), danlatestOfMany()alih-alih memuat seluruh koleksi hanya untuk menghitung atau mengambil satu data. - Saring di database lewat method relasi (
orders()->where(...)), bukan di collection.
Maintainability
- Selalu tulis return type pada method relasi (
: HasMany). IDE, static analysis, danphp artisan model:showmenjadi lebih akurat. - Beri nama relasi sesuai makna bisnis:
latestOrder,primaryAddress,activeProducts. - Definisikan relasi di kedua arah bila keduanya dipakai.
- Gunakan pivot model kustom bila pivot punya cast, logika, atau event; jangan sebarkan perhitungan pivot di banyak controller.
Related Articles
- Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration
- Mengatasi Masalah N+1 Query di Laravel Menggunakan Eager Loading
- Laravel Query Builder vs Eloquent ORM: Kapan Menggunakan Masing-Masing?
- Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |