Lompat ke konten
dokumentasi.id
Masuk
dokumentasi.idTwintyLabslaravel-userstamps
Commit 159d6ac
v1
Star1
Navigasi sumber

1

Ringkasan Proyek

TwintyLabs/laravel-userstamps adalah paket Laravel yang mencatat user pembuat, pengubah, dan penghapus pada model Eloquent. Deskripsi resminya menyebut dukungan untuk relasi userstamp standar sekaligus polymorphic (morph) composer.json:2-3. Seluruh kode paket berada di namespace TwintyLabs\Userstamps dan dipetakan PSR-4 ke direktori src/ composer.json:43-47.

Paket menyentuh tiga lapisan sekaligus: macro Blueprint yang menambah kolom saat migration, trait HasUserstamps yang membuka relasi ke model user, dan UserstampsObserver yang mengisi kolom pada siklus event model. Perakitan ketiganya terjadi di UserstampsServiceProvider: config didaftarkan lewat hasConfigFile('userstamps'), sedangkan macro didaftarkan pada bootingPackage src/UserstampsServiceProvider.php:11-24.

Kemampuan utama

Tabel berikut merangkum apa saja yang disediakan paket dan di mana implementasinya berada.

KemampuanTitik masukHasil
Menambah kolom userstamp saat Schema::createmacro userstampscreated_by_id dan updated_by_id, ditambah created_by_type serta updated_by_type bila is_using_morph aktif src/Database/Schema/Macros/UserstampsMacro.php:50-70
Menambah kolom penghapusmacro softUserstampsdeleted_by_id, ditambah deleted_by_type bila morph aktif src/Database/Schema/Macros/UserstampsMacro.php:72-85
Memilih tipe kolom IDaddUserIdColumnforeignId, foreignUuid, foreignUlid untuk non-morph; unsignedBigInteger, uuid, ulid untuk morph src/Database/Schema/Macros/UserstampsMacro.php:24-40
Relasi ke usercreatedBy, updatedBy, deletedByBelongsTo atau MorphTo, dibungkus withTrashed() bila with_trashed bernilai true src/Concerns/HasUserstamps.php:19-32 src/Concerns/HasUserstamps.php:49-62
Pengisian kolom otomatisUserstampsObserverhook creating, updating, deleting, restoring src/Observers/UserstampsObserver.php:9-28

Peta komponen dan alur pemakaian

Diagram berikut memetakan komponen paket serta jalur data dari berkas config sampai relasi yang dibaca aplikasi.

graph TD
    CFG["config/userstamps.php"] --> PROV["UserstampsServiceProvider"]
    PROV --> MACRO["UserstampsMacro"]
    MACRO --> COLS["created_by_id / updated_by_id / deleted_by_id"]
    COLS --> TABLE[("Tabel model")]
    PROV --> TRAIT["HasUserstamps"]
    TRAIT --> OBS["UserstampsObserver"]
    OBS -- "mengisi kolom saat save" --> TABLE
    OBS -- "auth()->user()" --> USER[("Tabel users")]
    TABLE -- "withTrashed() opsional" --> REL["createdBy() / updatedBy() / deletedBy()"]
    TRAIT --> REL
    style CFG fill:#f59e0b,color:#000
    style PROV fill:#f59e0b,color:#000
    style TABLE fill:#336791,color:#fff
    style USER fill:#336791,color:#fff
    style REL fill:#8b5cf6,color:#fff
    style OBS fill:#2d7d46,color:#fff
%% fig: Komponen paket dan jalur data userstamp
%% desc: Config dipakai service provider untuk mendaftarkan macro schema dan trait model, lalu observer mengisi kolom dan relasi membacanya kembali.
Fig. 1: Komponen paket dan jalur data userstampConfig dipakai service provider untuk mendaftarkan macro schema dan trait model, lalu observer mengisi kolom dan relasi membacanya kembali.

Trait HasUserstamps mendaftarkan UserstampsObserver sendiri lewat hook booted, sehingga model pemakai tidak perlu memasang observer secara manual src/Concerns/HasUserstamps.php:12-17.

Alur pemakaian singkat

Urutan pemakaian mengikuti README resmi:

  1. Tambahkan $table->userstamps() dan $table->softUserstamps() di dalam closure Schema::create README.md:117-127.
  2. Untuk tabel yang sudah ada, pakai macro yang sama di Schema::table, lalu lepas kembali dengan dropUserstamps() dan dropSoftUserstamps() di method down README.md:142-148.
  3. Pasang trait pada model dengan use HasUserstamps; README.md:153-159.
  4. Baca hasilnya lewat $model->createdBy, $model->updatedBy, dan $model->deletedBy README.md:163-167.

Nilai yang disimpan bergantung pada user yang sedang login. getUserPrimaryValueAndClass mengembalikan id dan type bernilai null bila auth()->check() bernilai false, dan memakai kolom lain ketika users_table_id_column_name bukan id src/Observers/UserstampsObserver.php:91-107.

Perilaku pada siklus event model

Observer mengisi kolom hanya jika kolom tersebut masih bersih. Pada creating, created_by_id dan updated_by_id diisi bila keduanya lolos isClean src/Observers/UserstampsObserver.php:9-28. Pada updating hanya updated_by_id yang diperbarui src/Observers/UserstampsObserver.php:30-40.

Penghapusan dan pemulihan hanya berlaku untuk model yang memakai SoftDeletes, dan usingSoftDeletes() menjawabnya lewat class_uses_recursive src/Concerns/HasUserstamps.php:64-67. Saat deleting, deleted_by_id diisi bersama updated_by_id, lalu model disimpan tanpa memicu event lagi src/Observers/UserstampsObserver.php:42-59. Saat restoring, deleted_by_id dikosongkan dan updated_by_id diisi dengan user yang memulihkan src/Observers/UserstampsObserver.php:61-78. Penulisan di luar siklus event itu memakai saveWithoutEventDispatching, yang melepas lalu memasang kembali event dispatcher src/Observers/UserstampsObserver.php:80-89.

⚠️ is_using_morph harus ditetapkan sebelum migration dijalankan, karena nilai ini menentukan apakah kolom _type ikut dibuat config/userstamps.php:13-18. Nama kolom created_by, updated_by, dan deleted_by menjadi dasar penamaan kolom yang dihasilkan config/userstamps.php:84-110.

Langkah berikutnya