Model Eloquent

Konvensi pemetaan tabel, primary key, dan konfigurasi dasar model.

Daftar isi

Model Eloquent adalah kelas PHP yang memetakan satu tabel database menjadi objek yang dapat dibaca dan ditulis melalui metode bawaan Laravel. Topik ini membahas konvensi pemetaan yang digunakan Eloquent, properti $fillable dan $table, cara membuat model dengan Artisan, serta pemeriksaan hasil pemetaan melalui Tinker. Seluruh pembahasan diterapkan pada dua model aplikasi catatan, yaitu Note untuk tabel notes dan Category untuk tabel categories, yang menjadi fondasi operasi CRUD dan relasi.

Konvensi pemetaan model dan tabel#

Eloquent menghubungkan kelas model dengan tabel database melalui konvensi penamaan, sehingga aplikasi jarang perlu menyebut nama tabel secara eksplisit. Nama kelas ditulis dalam bentuk tunggal dengan gaya StudlyCase, sedangkan nama tabel hasil konvensinya berbentuk jamak dengan gaya snake_case. Dengan konvensi itu, kelas Note dipetakan ke tabel notes, dan kelas Category dipetakan ke tabel categories. Tabel berikut merangkum beberapa contoh pemetaan.

Kelas model	Tabel hasil konvensi
`Note`	`notes`
`Category`	`categories`
`DataKategori`	`data_kategori`

Selain nama tabel, Eloquent menetapkan dua asumsi lain pada setiap model. Pertama, primary key berada pada kolom id yang bertipe bilangan bulat dan bertambah sendiri. Kedua, tabel memiliki kolom created_at dan updated_at yang diisi otomatis ketika baris dibuat dan diperbarui. Ketiga asumsi tersebut, yaitu nama tabel, primary key, dan kolom waktu, selaras dengan skema aplikasi catatan yang dibangun pada topik Migration, sehingga model Note dan Category dapat ditulis tanpa konfigurasi tambahan.

Apabila konvensi tidak sesuai dengan database yang sudah ada, asumsi tersebut dapat ditimpa pada kelas model. Properti protected $table = 'nama_tabel'; mengganti nama tabel, sedangkan protected $primaryKey = 'kunci'; mengganti nama primary key. Kolom waktu juga dapat dimatikan dengan public $timestamps = false; apabila tabel tidak memiliki kolom created_at dan updated_at.

Membuat model dengan Artisan#

Kelas model dibuat dengan perintah make:model yang menghasilkan kerangka kelas pada direktori app/Models. Menambahkan opsi -m pada perintah yang sama membuat berkas migration untuk tabel tersebut sekaligus, sehingga model dan skemanya dibuat dalam satu langkah.

bash

# tidak-dijalankan
# membuat kelas model untuk tabel categories dan notes
cd ~/aplikasi-catatan
php artisan make:model Category
php artisan make:model Note

Perintah tersebut sudah dieksekusi sebelumnya ketika skema aplikasi contoh disiapkan, sehingga contoh ini tidak mengulanginya. Keluaran asli kedua perintah itu adalah sebagai berikut.

text Hasil perintah make:model


   INFO  Model [app/Models/Category.php] created successfully.  

   INFO  Model [app/Models/Note.php] created successfully.

Kerangka hasil perintah ini masih kosong dan belum berfungsi apa pun. Kelasnya baru menjadi fungsional setelah trait HasFactory dipasang dan properti penting, khususnya $fillable, diisi sesuai kebutuhan aplikasi.

Properti fillable sebagai daftar atribut yang boleh diisi#

Properti $fillable berupa array berisi nama atribut yang boleh diisi secara massal (mass assignment), yaitu pengisian beberapa atribut sekaligus dalam satu pemanggilan seperti create() atau update(). Mekanisme ini berperan sebagai pengaman: tanpa daftar tersebut, pihak yang tidak berwenang dapat mengirimkan atribut tambahan melalui formulir dan mengubah data yang tidak seharusnya diubah. Model Note mengizinkan judul, isi, dan category_id, sedangkan model Category hanya mengizinkan nama.

Atribut yang tidak terdaftar pada $fillable secara bawaan dibuang tanpa pemberitahuan saat pengisian massal, sehingga nilainya tidak pernah masuk ke tabel. Aturan lengkap beserta error MassAssignmentException dibahas pada topik CRUD dengan Eloquent. Untuk aplikasi contoh, ketiga kolom milik Note dan satu kolom milik Category memang seluruhnya berasal dari masukan pengguna, sehingga daftar $fillable pada kedua model sama dengan kolom nonkunci tabel masing-masing.

Model Note dan Category#

Berkas model aplikasi catatan ditampilkan berikut ini. Kedua kelas menggunakan trait HasFactory agar dapat memanggil factory yang dibuat pada topik Seeder dan factory, serta mendaftarkan relasinya sebagai metode biasa.

php Note.php

// tidak-dijalankan
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Note extends Model
{
    use HasFactory;

    protected $fillable = ['judul', 'isi', 'category_id'];

    public function category(): BelongsTo
    {
        return $this->belongsTo(Category::class);
    }
}

Metode category() menyatakan bahwa setiap catatan dimiliki oleh satu kategori. Kebalikannya berada pada model Category berupa metode notes() yang menyatakan satu kategori memiliki banyak catatan.

php Category.php

// tidak-dijalankan
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Category extends Model
{
    use HasFactory;

    protected $fillable = ['nama'];

    public function notes(): HasMany
    {
        return $this->hasMany(Note::class);
    }
}

Tipe kembalian BelongsTo dan HasMany pada kedua metode merupakan tipe relasi milik Eloquent. Cara kedua metode ini bekerja dan cara menggunakannya dibahas lebih rinci pada topik Relasi.

Memeriksa pemetaan melalui Tinker#

Konvensi pemetaan tidak perlu ditebak karena Eloquent menyediakan metode pembaca untuk memeriksa pemetaan pada setiap model. Perintah berikut menjalankan Tinker untuk menampilkan nama tabel, nama primary key, daftar $fillable, serta kolom waktu dari kedua model.

bash

# memeriksa pemetaan kedua model melalui Tinker
cd ~/aplikasi-catatan
php artisan tinker --execute='
use App\Models\Category;
use App\Models\Note;
echo Note::make()->getTable() . PHP_EOL;
echo Note::make()->getKeyName() . PHP_EOL;
echo implode(", ", Note::make()->getFillable()) . PHP_EOL;
echo Category::make()->getTable() . PHP_EOL;
echo implode(", ", Category::make()->getDates()) . PHP_EOL;
'

text Keluaran

notes
id
judul, isi, category_id
categories
created_at, updated_at

Keluaran tersebut menunjukkan bahwa konvensi bekerja sebagaimana dirangkum di awal topik. Metode getTable() mengembalikan notes dan categories tanpa konfigurasi apa pun, getKeyName() mengembalikan id, sedangkan getDates() mengembalikan dua kolom waktu yang diisi otomatis. Metode make() digunakan di sini karena hanya membuat objek model di memori tanpa menyentuh database, sehingga pemeriksaan aman dijalankan berulang kali.

Kesalahan umum#

Kesalahan pertama adalah menamai model dengan kata Indonesia seperti Kategori padahal tabelnya categories. Eloquent mencari tabel kategoris hasil konvensinya, sehingga query gagal dengan error bahwa tabel kategoris tidak ada. Perbaikannya adalah menamai kelas mengikuti bahasa tabel, misalnya Category, atau menetapkan protected $table = 'categories'; secara eksplisit pada kelas model.

Kesalahan kedua adalah lupa mendaftarkan atribut pada $fillable, sehingga kolomnya selalu NULL di tabel meskipun nilai sudah diberikan saat create(). Pembuangan atribut terjadi tanpa pesan apa pun pada perilaku bawaan. Periksa daftar $fillable setiap kali sebuah kolom tidak terisi, dan tambahkan nama kolom itu ke daftar jika memang boleh diisi dari luar.

Kesalahan ketiga adalah menggunakan model yang sama pada tabel lama yang tidak memiliki kolom created_at dan updated_at. Eloquent menuliskan kedua kolom itu pada setiap penyimpanan sehingga penyimpanan gagal dengan error kolom tidak ditemukan. Matikan perilakunya dengan public $timestamps = false; pada kelas model tersebut.

Ringkasan#

Eloquent memetakan kelas model ke tabel melalui konvensi: nama kelas tunggal StudlyCase menjadi tabel jamak snake_case, primary key bernama id, serta kolom created_at dan updated_at yang diisi otomatis.
Properti $table, $primaryKey, dan $timestamps menimpa konvensi apabila database yang ada tidak sesuai.
Properti $fillable membatasi atribut yang boleh diisi secara massal, sedangkan metode seperti getTable() dan getFillable() memungkinkan pemeriksaan pemetaan melalui Tinker.
Trait HasFactory wajib ada pada model yang akan dibuat oleh factory.

Referensi#

Eloquent: Getting Started — Laravel — Dokumentasi resmi konvensi model, properti $table, dan penggunaan Eloquent.
Artisan Console — Laravel — Dokumentasi perintah make:model beserta opsinya.