Penggunaan pada Model Eloquent

Model Eloquent memakai trait HasUserstamps untuk membuka tiga relasi: createdBy, updatedBy, dan deletedBy. Pemasangannya cukup satu baris use di dalam kelas model, dan trait itu sendiri yang mendaftarkan observer serta menyusun relasi berdasarkan nilai config userstamps. README menuliskan pemasangan itu sebagai tambahan trait pada model (README.md:151-159¹), dan model uji Product melakukannya persis dengan menambahkan SoftDeletes di kelas yang sama (tests/Models/Product.php:9-13²).

Memasang trait pada model

Tambahkan trait di badan kelas model, lalu biarkan trait mendaftarkan observer-nya sendiri:

use TwintyLabs\Userstamps\Concerns\HasUserstamps;

class Example extends Model
{
    use HasUserstamps;
}

Saat model di-boot, bootHasUserstamps memasang callback pada event booted yang memanggil static::observe(UserstampsObserver::class) (src/Concerns/HasUserstamps.php:10-17³). Artinya kolom created_by_id, updated_by_id, dan deleted_by_id terisi tanpa kode tambahan di model; urutan event yang mengisinya dibahas di Observer dan Siklus Event Model.

Trait juga menyediakan usingSoftDeletes(), yang memakai class_uses_recursive untuk memeriksa apakah model benar-benar memakai SoftDeletes (src/Concerns/HasUserstamps.php:64-67⁴). Model yang tidak memakai SoftDeletes tidak akan punya isi pada deleted_by_id, sehingga relasi deletedBy selalu kosong untuk model tersebut.

graph TD
    Model["Product (Model Eloquent)"] --> Trait["HasUserstamps"]
    Trait --> Created["createdBy()"]
    Trait --> Updated["updatedBy()"]
    Trait --> Deleted["deletedBy()"]
    Created --> Branch{"is_using_morph"}
    Branch -->|false| Belongs["belongsTo(users_model, ..._id, users_table_id_column_name)"]
    Branch -->|true| Morph["morphTo(__FUNCTION__, ..._type, ..._id)"]
    Belongs --> Trashed{"with_trashed"}
    Morph --> Trashed
    Trashed -->|false| Plain["query tanpa user terhapus"]
    Trashed -->|true| WithTr["withTrashed()"]
    style Model fill:#336791,color:#fff
    style Trait fill:#f59e0b,color:#000
    style Created fill:#8b5cf6,color:#fff
    style Updated fill:#8b5cf6,color:#fff
    style Deleted fill:#8b5cf6,color:#fff
    style Branch fill:#f59e0b,color:#000
    style Belongs fill:#336791,color:#fff
    style Morph fill:#336791,color:#fff
    style Trashed fill:#f59e0b,color:#000
    style Plain fill:#dc2626,color:#fff
    style WithTr fill:#2d7d46,color:#fff
%% fig: Resolusi relasi userstamps pada satu model
%% desc: Trait HasUserstamps membuka tiga relasi yang bercabang menurut is_using_morph, lalu setiap cabang disaring lagi oleh opsi with_trashed.

Membaca relasi pembuat, pengubah, dan penghapus

Ketiga relasi dibaca sebagai properti biasa, sesuai contoh README (README.md:161-167⁵). Nilainya berupa instance model user, jadi atribut user bisa langsung diakses. Uji perilaku memastikan createdBy dan updatedBy terisi tepat setelah Product::create, sementara deletedBy masih null, dan email user bisa dibaca dari relasi tersebut (tests/Feature/UserstampsBehaviorTest.php:18-22⁶).

createdBy() memilih jalur morphTo ketika config('userstamps.is_using_morph') bernilai benar, dan jalur belongsTo ke config('userstamps.users_model') ketika bernilai salah; kolom yang dipakai adalah nama kolom config ditambah akhiran _id (src/Concerns/HasUserstamps.php:19-32⁷). Pola yang sama berlaku untuk updatedBy() (src/Concerns/HasUserstamps.php:34-47⁸) dan deletedBy() (src/Concerns/HasUserstamps.php:49-62⁹). Karena config dibaca di dalam method relasi, setiap pemanggilan relasi selalu mengikuti nilai config yang sedang aktif. Perbedaan kedua jalur tersebut, termasuk pengaruh tipe kolom ID, dibahas di Trait HasUserstamps dan Relasi User dan Mode Morph dan Tipe Kolom ID.

Opsi with_trashed

Opsi with_trashed menentukan apakah user yang sudah di-soft-delete tetap muncul saat relasi dibaca, dan nilai bawaannya false (config/userstamps.php:120¹⁰). Ketiga method relasi mengembalikan $relation->withTrashed() bila opsi itu true, dan mengembalikan relasi apa adanya bila false (src/Concerns/HasUserstamps.php:19-32⁷).

Uji perilaku memperlihatkan efeknya: setelah Config::set('userstamps.with_trashed', true), user yang sudah dihapus masih bisa dibaca lewat updatedBy->email (tests/Feature/UserstampsBehaviorTest.php:41-48¹¹).

⚠️ Dengan with_trashed = false, relasi ke user yang sudah di-soft-delete menghasilkan null meskipun kolom updated_by_id tetap berisi ID user tersebut. Jangan simpulkan stamp-nya hilang hanya karena relasinya kosong.

Nama kolom kustom

Nama kolom tidak ditulis di model, melainkan diambil dari config. Opsi created_by_column (config/userstamps.php:73-84¹²), updated_by_column (config/userstamps.php:86-97¹³), dan deleted_by_column (config/userstamps.php:99-110¹⁴) masing-masing menjadi awalan kolom; trait menambahkan akhiran _id, dan akhiran _type hanya pada mode morph. Sisi user dari relasi belongsTo memakai config('userstamps.users_table_id_column_name') sebagai kolom kunci (config/userstamps.php:62-71¹⁵).

⚠️ Mengubah nama kolom config setelah migrasi berjalan membuat relasi menunjuk kolom yang tidak ada. Samakan nilainya sebelum migrasi dijalankan, seperti dijelaskan pada Migrasi dan Kolom Userstamps dan Referensi Opsi Konfigurasi.

Siklus pengisian deletedBy saat model dihapus dan dipulihkan, termasuk pengaruh SoftDeletes pada model, dibahas di Siklus Soft Delete dan Restore.