Trait HasUserstamps dan Relasi User

Trait HasUserstamps adalah satu-satunya titik masuk paket di sisi model. Trait ini melakukan dua hal: mendaftarkan UserstampsObserver pada event booted, dan menyediakan tiga relasi baca ke baris user yang tercatat di kolom userstamp. Pada model uji Product, trait itu dipasang bersama SoftDeletes, sehingga createdBy, updatedBy, dan deletedBy semuanya punya sumber data — tests/Models/Product.php:9-19¹.

use TwintyLabs\Userstamps\Concerns\HasUserstamps;

class Product extends Model
{
    use HasUserstamps;
    use SoftDeletes;
}

Isi trait itu sendiri hanya 57 baris: satu hook boot, tiga method relasi, dan satu helper statis — src/Concerns/HasUserstamps.php:10-17².

Registrasi observer lewat event booted

Eloquent memanggil bootHasUserstamps() sekali saat model di-boot. Method itu tidak langsung mengobservasi model, melainkan mendaftarkan closure pada event booted, dan di dalam closure itulah static::observe(UserstampsObserver::class) baru dijalankan — src/Concerns/HasUserstamps.php:12-17³.

sequenceDiagram
    participant Model as Model Product
    participant Trait as HasUserstamps
    participant Obs as UserstampsObserver
    Model->>Trait: bootHasUserstamps
    Trait->>Model: registerModelEvent booted
    Model-->>Trait: event booted dipicu
    Trait->>Obs: static::observe
    Obs-->>Model: creating / updating / deleting / restoring
%% fig: Urutan registrasi observer dari hook boot trait
%% desc: Trait menunda pemanggilan observe sampai event booted, sehingga observer terpasang setelah model selesai di-boot.

Penundaan ini menghindari boot bersarang: observe() ikut memicu boot model, sehingga memanggilnya langsung di dalam bootHasUserstamps() berisiko rekursi. Berkas test menutup kasus tersebut dengan memastikan new Product tidak melempar LogicException — tests/Feature/TraitHasUserstampsTest.php:5-7⁴. Perilaku observer setelah terpasang dijelaskan di Observer dan Siklus Event Model.

Tiga relasi userstamp

createdBy(), updatedBy(), dan deletedBy() bertipe kembalian MorphTo|BelongsTo. Tipe konkretnya ditentukan saat pemanggilan, bukan saat kompilasi, karena bergantung pada nilai config userstamps.is_using_morph — src/Concerns/HasUserstamps.php:19-32⁵, src/Concerns/HasUserstamps.php:34-47⁶, src/Concerns/HasUserstamps.php:49-62⁷.

Nama relasi pada cabang morphTo diambil dari __FUNCTION__, sedangkan kolom _type dan _id diberikan eksplisit sebagai argumen kedua dan ketiga, jadi Eloquent tidak perlu menebak sufiks kolom — src/Concerns/HasUserstamps.php:22⁸, src/Concerns/HasUserstamps.php:37⁹, src/Concerns/HasUserstamps.php:52¹⁰.

Config yang dibaca ketiga method tersebut:

graph TD
    A["createdBy / updatedBy / deletedBy"] --> B{"is_using_morph"}
    B -->|true| C["morphTo: nama method + kolom _type + kolom _id"]
    B -->|false| D["belongsTo: users_model + kolom _id + users_table_id_column_name"]
    C --> E{"with_trashed"}
    D --> E
    E -->|true| F["relation->withTrashed()"]
    E -->|false| G["relation"]
    style A fill:#f59e0b,color:#000
    style B fill:#f59e0b,color:#000
    style E fill:#f59e0b,color:#000
    style C fill:#8b5cf6,color:#fff
    style D fill:#336791,color:#fff
    style F fill:#2d7d46,color:#fff
    style G fill:#2d7d46,color:#fff
%% fig: Percabangan di dalam setiap method relasi
%% desc: Setiap method memilih morphTo atau belongsTo berdasarkan config, lalu membungkus hasilnya dengan withTrashed bila diminta.

Kardinalitas relasi ke tabel users

Kolom userstamp dibuat nullable dan, pada mode non-morph, memakai foreign key nullOnDelete ke tabel users — src/Database/Schema/Macros/UserstampsMacro.php:42-47¹⁶. Karena itu relasinya bersifat opsional: satu baris model menunjuk ke nol atau satu baris users, dan satu baris users bisa dirujuk banyak baris model. Model uji membangun tabelnya lewat $table->userstamps() dan $table->softUserstamps() — tests/Feature/UserstampsBehaviorTest.php:153-160¹⁷.

erDiagram
    PRODUCT }o--o| USERS : "created_by_id"
    PRODUCT }o--o| USERS : "updated_by_id"
    PRODUCT }o--o| USERS : "deleted_by_id"
    PRODUCT {
        bigint id PK
        varchar name
        bigint created_by_id FK
        bigint updated_by_id FK
        bigint deleted_by_id FK
        timestamp deleted_at
    }
    USERS {
        bigint id PK
        varchar name
        varchar email
        timestamp deleted_at
    }
%% fig: Kardinalitas userstamp dari model ke tabel users
%% desc: Tiga foreign key nullable pada products menunjuk ke satu baris users; kolomnya nullOnDelete sehingga relasi selalu opsional.

Nama tabel users ditentukan userstamps.users_table dan kolom primary key-nya users_table_id_column_name — config/userstamps.php:33¹⁸, config/userstamps.php:71¹⁹. Pada sisi model user, kolom itu harus benar-benar ada. UserWithId adalah model uji untuk skenario ini: Authenticatable dengan SoftDeletes dan $fillable = ['name', 'email'] — tests/Models/UserWithId.php:8-13²⁰. Test mengarahkan users_model ke class tersebut sebelum skenario non-morph berjalan — tests/Feature/UserstampsBehaviorTest.php:141-143²¹.

Jebakan yang mudah terlewat

⚠️ is_using_morph wajib ditetapkan sebelum migration dijalankan, karena nilai itu menentukan apakah kolom _type ikut dibuat — config/userstamps.php:13-18²². Mengubahnya setelah tabel terbentuk membuat relasi morphTo menunjuk kolom yang tidak ada.

Pada mode morph, trait memakai created_by_type, updated_by_type, dan deleted_by_type berisi string nullable yang ditambahkan macro — src/Database/Schema/Macros/UserstampsMacro.php:58-60²³, src/Database/Schema/Macros/UserstampsMacro.php:79-81²⁴. Detail kolom dan tipe ID dibahas di Mode Morph dan Tipe Kolom ID, sedangkan pembentukan kolomnya di Lapisan Schema dan Macro Blueprint.

⚠️ deletedBy() membaca deleted_by_id, kolom yang hanya dibuat oleh softUserstamps() — src/Database/Schema/Macros/UserstampsMacro.php:72-85²⁵. Model tanpa macro itu akan gagal saat relasi deletedBy dipakai; daftar kolom lengkap ada di Migrasi dan Kolom Userstamps.

with_trashed pada query relasi

Setiap method menutup dengan pemeriksaan yang sama: bila userstamps.with_trashed bernilai true, relasi yang sudah terbentuk dibungkus withTrashed(), selain itu dikembalikan apa adanya — src/Concerns/HasUserstamps.php:31²⁶, src/Concerns/HasUserstamps.php:46²⁷, src/Concerns/HasUserstamps.php:61²⁸. Flag ini hanya berpengaruh kalau model user memakai SoftDeletes.

Efeknya terlihat di test: setelah Config::set('userstamps.with_trashed', true), user yang sudah dihapus tetap terbaca lewat $product->updatedBy — tests/Feature/UserstampsBehaviorTest.php:42-47²⁹. Nilai kolom userstamp sendiri tidak diubah oleh flag ini; yang berubah hanya cakupan query relasi.

usingSoftDeletes sebagai pemeriksa trait

Trait juga menyediakan helper statis usingSoftDeletes() yang mengembalikan true bila SoftDeletes::class ada di class_uses_recursive(static::class) — src/Concerns/HasUserstamps.php:64-67³⁰. Helper ini yang dipanggil observer pada event deleting untuk memutuskan apakah cap deleted_by_id perlu diisi — src/Observers/UserstampsObserver.php:44³¹.

Konsekuensinya, memasang HasUserstamps tanpa SoftDeletes membuat deletedBy selalu null, meskipun createdBy dan updatedBy tetap terisi — bandingkan tests/Feature/UserstampsBehaviorTest.php:18-22³² dengan tests/Feature/UserstampsBehaviorTest.php:29-31³³. Pakai HasUserstamps bersama SoftDeletes bila cap hapus dibutuhkan; siklusnya dirinci di Siklus Soft Delete dan Restore.