Tiga alat untuk tiga pertanyaan berbeda: "data ini masih bisa dikembalikan?", "siapa mengubah apa, kapan, dari nilai berapa?", dan "apa saja yang dilakukan pengguna?" Lengkap dengan retensi data dan tampilan riwayat.
Overview
Suatu pagi admin melapor: "Harga produk X berubah sendiri jadi Rp 1.000, dan kategori Y hilang." Tanpa jejak perubahan, tim hanya bisa menebak. Kebutuhan pelacakan data biasanya muncul setelah insiden, padahal paling mudah dipasang di awal.
Ketiga konsep yang sering dicampuradukkan:
| Konsep | Pertanyaan yang dijawab | Contoh |
|---|---|---|
| Soft delete | Bisakah data yang terhapus dikembalikan? | Produk terhapus dipulihkan dari "Tempat Sampah" |
| Audit trail | Siapa mengubah field apa, dari nilai lama ke nilai baru, kapan? | Harga diubah oleh budi@toko.com dari 250.000 ke 1.000 pukul 08.12 |
| Activity log | Apa saja tindakan yang terjadi di aplikasi? | Login, ekspor laporan, mengirim ulang invoice |
Hasil akhir artikel ini:
- soft delete yang benar, termasuk masalah indeks unik dan pembersihan otomatis,
- audit trail buatan sendiri yang ringan (tabel
audits+ trait), - activity log dengan
spatie/laravel-activitylogv5 untuk pelacakan yang lebih lengkap, - endpoint riwayat perubahan, retensi data, dan pertimbangan privasi.
Prerequisites
| Komponen | Versi |
|---|---|
| PHP | 8.4 (diwajibkan oleh spatie/laravel-activitylog v5; bagian lain berjalan di 8.3) |
| Laravel | 13.x (activitylog v5 membutuhkan Laravel 12+) |
| Database | MySQL 8.0+ / PostgreSQL 15+ |
| Paket | spatie/laravel-activitylog ^5.0 (opsional, Bagian C) |
Jika proyek Anda masih di PHP 8.3, gunakan spatie/laravel-activitylog v4. API-nya berbeda di beberapa tempat; lihat catatan di Bagian C.
Step-by-step Tutorial
Bagian A: Soft Delete
Langkah 1: Tambahkan Kolom dan Trait
php artisan make:migration add_soft_deletes_to_products_table
public function up(): void
{
Schema::table('products', function (Blueprint $table) {
$table->softDeletes(); // kolom deleted_at nullable
});
}
public function down(): void
{
Schema::table('products', function (Blueprint $table) {
$table->dropSoftDeletes();
});
}
// app/Models/Product.php
use Illuminate\Database\Eloquent\SoftDeletes;
class Product extends Model
{
use HasFactory, SoftDeletes;
}
Langkah 2: Perilaku Query Setelah Soft Delete
$product->delete(); // set deleted_at = now(), baris tetap ada
Product::all(); // otomatis WHERE deleted_at IS NULL
Product::withTrashed()->find($id); // termasuk yang terhapus
Product::onlyTrashed()->paginate(); // hanya yang terhapus ("Tempat Sampah")
$product->trashed(); // true
$product->restore(); // deleted_at = null
$product->forceDelete(); // hapus permanen
Route model binding mengabaikan data terhapus. Untuk halaman pemulihan, izinkan secara eksplisit:
Route::patch('products/{product}/restore', [ProductController::class, 'restore'])
->withTrashed();
public function restore(Product $product)
{
Gate::authorize('restore', $product);
$product->restore();
return ProductResource::make($product);
}
Relasi juga mengabaikan data terhapus. Jika item pesanan lama harus tetap menampilkan produk yang sudah dihapus:
// app/Models/OrderItem.php
public function product(): BelongsTo
{
return $this->belongsTo(Product::class)->withTrashed();
}
Langkah 3: Atasi Masalah Indeks Unik
Masalah yang paling sering muncul: produk dengan SKU PRD-001 di-soft-delete, lalu admin membuat produk baru dengan SKU yang sama, dan database menolak karena indeks unik sku masih melihat baris lama.
Pilih salah satu solusi:
Solusi 1 (PostgreSQL): partial unique index
DB::statement('CREATE UNIQUE INDEX products_sku_active_unique ON products (sku) WHERE deleted_at IS NULL');
Solusi 2 (MySQL 8): generated column
MySQL tidak mendukung partial index, tetapi NULL tidak dianggap duplikat di indeks unik. Buat kolom yang bernilai SKU saat aktif dan NULL saat terhapus:
public function up(): void
{
Schema::table('products', function (Blueprint $table) {
$table->dropUnique(['sku']);
$table->string('sku_active', 50)
->virtualAs('IF(deleted_at IS NULL, sku, NULL)')
->nullable();
$table->unique('sku_active');
});
}
Solusi 3: ubah nilai saat menghapus
protected static function booted(): void
{
static::softDeleted(function (Product $product) {
$product->sku = $product->sku.'__deleted_'.$product->id;
$product->saveQuietly();
});
}
Solusi 3 paling portabel tetapi mengubah data asli dan harus dibalik saat restore(). Untuk MySQL, solusi 2 lebih bersih.
Jangan lupa aturan validasi juga harus mengabaikan data terhapus:
Rule::unique('products', 'sku')->withoutTrashed()->ignore($product)
Langkah 4: Bersihkan Otomatis dengan Pruning
Data yang di-soft-delete selamanya akan menumpuk. Gunakan Prunable untuk menghapus permanen setelah periode tertentu:
// app/Models/Product.php
use Illuminate\Database\Eloquent\Prunable;
class Product extends Model
{
use SoftDeletes, Prunable;
public function prunable(): Builder
{
return static::onlyTrashed()
->where('deleted_at', '<=', now()->subDays(90))
->whereDoesntHave('orderItems'); // jangan hapus produk yang punya transaksi
}
protected function pruning(): void
{
if ($this->image_path) {
Storage::disk('public')->delete($this->image_path);
}
}
}
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('model:prune')->daily();
Uji tanpa benar-benar menghapus:
php artisan model:prune --pretend
INFO 12 [App\Models\Product] records will be pruned.
Langkah 5: Kapan Tidak Memakai Soft Delete
Soft delete bukan solusi untuk semua tabel:
- Tabel pivot dan log: hapus permanen saja.
- Data pribadi yang diminta dihapus pemiliknya: soft delete tidak memenuhi permintaan penghapusan. Lakukan anonimisasi atau hapus permanen.
- Tabel transaksi (pesanan, pembayaran): biasanya tidak dihapus sama sekali, melainkan diberi status
cancelled.
Bagian B: Audit Trail Buatan Sendiri
Untuk kebutuhan sederhana ("siapa mengubah field apa"), tabel audit sendiri sering cukup dan mudah dikendalikan.
Langkah 6: Tabel audits
php artisan make:migration create_audits_table
php artisan make:model Audit
public function up(): void
{
Schema::create('audits', function (Blueprint $table) {
$table->id();
$table->morphs('auditable'); // auditable_type, auditable_id
$table->foreignId('user_id')->nullable()->constrained()->nullOnDelete();
$table->string('event', 20); // created, updated, deleted, restored
$table->json('old_values')->nullable();
$table->json('new_values')->nullable();
$table->string('ip_address', 45)->nullable();
$table->string('user_agent', 255)->nullable();
$table->string('url', 2048)->nullable();
$table->timestamp('created_at')->useCurrent();
$table->index(['auditable_type', 'auditable_id', 'created_at']);
});
}
// app/Models/Audit.php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\{BelongsTo, MorphTo};
class Audit extends Model
{
public const UPDATED_AT = null;
protected $guarded = [];
protected function casts(): array
{
return ['old_values' => 'array', 'new_values' => 'array'];
}
public function auditable(): MorphTo
{
return $this->morphTo()->withTrashed();
}
public function user(): BelongsTo
{
return $this->belongsTo(User::class);
}
}
Catatan:
morphTo()->withTrashed()hanya berlaku bila model target memakaiSoftDeletes. Jika ada model ter-audit yang tidak memakai soft delete, hapuswithTrashed().
Langkah 7: Trait Auditable
// app/Models/Concerns/Auditable.php
namespace App\Models\Concerns;
use App\Models\Audit;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphMany;
trait Auditable
{
public static function bootAuditable(): void
{
static::created(fn (Model $m) => $m->writeAudit('created', [], $m->auditableValues($m->getAttributes())));
static::updated(function (Model $m) {
$changes = $m->auditableValues($m->getChanges());
unset($changes['updated_at']);
if ($changes === []) {
return; // tidak ada perubahan bermakna
}
$old = array_intersect_key($m->auditableValues($m->getOriginal()), $changes);
$m->writeAudit('updated', $old, $changes);
});
static::deleted(fn (Model $m) => $m->writeAudit('deleted', $m->auditableValues($m->getAttributes()), []));
if (method_exists(static::class, 'restored')) {
static::restored(fn (Model $m) => $m->writeAudit('restored', [], []));
}
}
public function audits(): MorphMany
{
return $this->morphMany(Audit::class, 'auditable')->latest('created_at');
}
/** Kolom yang tidak boleh masuk audit. Override di model bila perlu. */
protected function auditExclude(): array
{
return ['password', 'remember_token', 'two_factor_secret', 'created_at'];
}
protected function auditableValues(array $values): array
{
return array_diff_key($values, array_flip($this->auditExclude()));
}
protected function writeAudit(string $event, array $old, array $new): void
{
$request = app()->runningInConsole() ? null : request();
Audit::create([
'auditable_type' => $this->getMorphClass(),
'auditable_id' => $this->getKey(),
'user_id' => auth()->id(),
'event' => $event,
'old_values' => $old ?: null,
'new_values' => $new ?: null,
'ip_address' => $request?->ip(),
'user_agent' => $request ? substr((string) $request->userAgent(), 0, 255) : null,
'url' => $request?->fullUrl(),
]);
}
}
Pasang di model yang perlu diaudit:
class Product extends Model
{
use HasFactory, SoftDeletes, Auditable;
}
Hasilnya untuk perubahan harga:
{
"event": "updated",
"user_id": 4,
"old_values": { "price": 250000 },
"new_values": { "price": 1000 },
"ip_address": "103.10.66.21",
"created_at": "2026-10-19T01:12:44Z"
}
Gunakan morph map agar auditable_type tidak menyimpan nama class lengkap (yang akan rusak bila class dipindah namespace):
// app/Providers/AppServiceProvider.php
use Illuminate\Database\Eloquent\Relations\Relation;
Relation::enforceMorphMap([
'product' => \App\Models\Product::class,
'order' => \App\Models\Order::class,
'user' => \App\Models\User::class,
]);
Langkah 8: Keterbatasan yang Harus Diketahui
Audit berbasis event model tidak menangkap:
- update massal:
Product::where(...)->update([...])danDB::table()->update(), saveQuietly(),updateQuietly(), dan kode di dalamModel::withoutEvents(),- perubahan langsung di database (lewat phpMyAdmin, migration, atau sistem lain).
Untuk kebutuhan kepatuhan yang ketat, lengkapi dengan trigger database atau audit log di level database (misalnya plugin audit MySQL/MariaDB atau pgaudit di PostgreSQL).
Bagian C: Activity Log dengan spatie/laravel-activitylog v5
Paket ini cocok bila Anda membutuhkan log tindakan non-CRUD (login, ekspor, kirim email) sekaligus perubahan model, dengan API yang sudah matang.
Langkah 9: Instalasi
composer require spatie/laravel-activitylog:"^5.0"
php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-config"
php artisan migrate
Tabel activity_log menyimpan perubahan atribut model di kolom attribute_changes dan data kustom di kolom properties.
Langkah 10: Log Perubahan Model
// app/Models/Order.php
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;
class Order extends Model
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logOnly(['status', 'shipping_cost', 'total'])
->logOnlyDirty()
->dontLogEmptyChanges()
->useLogName('order')
->setDescriptionForEvent(fn (string $event) => "Pesanan {$event}");
}
}
Di v5, getActivitylogOptions() bersifat opsional. Tanpa method ini, event created/updated/deleted tetap dicatat tetapi perubahan atribut tidak dilacak, jadi definisikan method ini bila Anda ingin melihat nilai lama dan baru.
Langkah 11: Log Tindakan Manual
activity('order')
->performedOn($order)
->causedBy($request->user())
->withProperties(['channel' => 'email', 'to' => $order->customer->email])
->log('Invoice dikirim ulang');
// Login berhasil, misalnya di listener event Illuminate\Auth\Events\Login
activity('auth')
->causedBy($event->user)
->withProperties(['ip' => request()->ip()])
->log('Login');
Batch (LogBatch) dihapus di v5. Untuk mengelompokkan beberapa aktivitas dalam satu proses, gunakan properti sendiri:
$group = (string) Str::uuid();
activity()->withProperty('group', $group)->performedOn($order)->log('Pembayaran diverifikasi');
activity()->withProperty('group', $group)->performedOn($order)->log('Stok dikurangi');
Langkah 12: Membaca Riwayat
use Spatie\Activitylog\Models\Activity;
$history = Activity::query()
->forSubject($order)
->with('causer:id,name')
->latest()
->get();
foreach ($history as $activity) {
$activity->description; // "Pesanan updated"
$activity->causer?->name; // "Budi"
$activity->attribute_changes; // ['attributes' => ['status' => 'shipped'], 'old' => ['status' => 'paid']]
$activity->getProperty('channel'); // data kustom
}
Relasi pada model di v5 bernama activitiesAsSubject (untuk model yang dicatat) dan activitiesAsCauser (untuk pelaku). Jika Anda migrasi dari v4, ganti ->activities, ->actions, changes(), dan getExtraProperty() sesuai panduan upgrade resmi paket.
Langkah 13: Endpoint Riwayat Perubahan
// routes/api.php
Route::get('orders/{order}/history', OrderHistoryController::class)->middleware('auth:sanctum');
// app/Http/Controllers/Api/V1/OrderHistoryController.php
public function __invoke(Order $order)
{
Gate::authorize('viewHistory', $order);
$items = Activity::forSubject($order)->with('causer:id,name')->latest()->paginate(20);
return $items->through(fn (Activity $a) => [
'waktu' => $a->created_at->timezone('Asia/Jakarta')->format('d M Y H:i'),
'oleh' => $a->causer?->name ?? 'Sistem',
'aktivitas' => $a->description,
'perubahan' => collect($a->attribute_changes['attributes'] ?? [])
->map(fn ($baru, $field) => [
'field' => $field,
'dari' => $a->attribute_changes['old'][$field] ?? null,
'ke' => $baru,
])->values(),
]);
}
Langkah 14: Retensi dan Pembersihan
Atur umur log di config/activitylog.php (clean_after_days), lalu jadwalkan:
// routes/console.php
Schedule::command('activitylog:clean')->daily();
Untuk tabel audits buatan sendiri, pakai MassPrunable agar cepat:
// app/Models/Audit.php
use Illuminate\Database\Eloquent\MassPrunable;
class Audit extends Model
{
use MassPrunable;
public function prunable(): Builder
{
return static::where('created_at', '<', now()->subYear());
}
}
Tentukan periode retensi bersama klien. Data keuangan biasanya wajib disimpan bertahun-tahun, sementara log aktivitas umum cukup beberapa bulan.
Memilih Pendekatan
| Kebutuhan | Pilihan |
|---|---|
| Bisa memulihkan data terhapus | Soft delete + pruning |
| Riwayat perubahan field untuk beberapa model | Audit trail sendiri (Bagian B) |
| Riwayat perubahan + log tindakan + UI riwayat | spatie/laravel-activitylog |
| Kepatuhan ketat, termasuk perubahan di luar aplikasi | Audit di level database + salah satu di atas |
Troubleshooting
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
Duplicate entry 'PRD-001' for key 'products_sku_unique' setelah soft delete |
Indeks unik masih menghitung baris terhapus | Partial index (PostgreSQL), generated column (MySQL), atau ubah nilai saat dihapus |
Validasi unique menolak padahal data lama sudah dihapus |
Aturan validasi tidak mengabaikan data terhapus | Rule::unique(...)->withoutTrashed() |
| 404 di endpoint restore | Route model binding mengabaikan data terhapus | Tambahkan ->withTrashed() pada route |
| Audit tidak tercatat | Update massal, saveQuietly(), atau withoutEvents() |
Update per model, atau catat audit secara eksplisit |
auditable_type rusak setelah refactor namespace |
Menyimpan nama class lengkap | Gunakan Relation::enforceMorphMap() dan migrasikan data lama |
Class "Spatie\Activitylog\Traits\LogsActivity" not found |
Namespace v4 dipakai pada v5 | Gunakan Spatie\Activitylog\Models\Concerns\LogsActivity dan Spatie\Activitylog\Support\LogOptions |
Column not found: attribute_changes |
Upgrade dari v4 tanpa migration baru | Buat migration upgrade sesuai panduan resmi paket |
| Tabel log membengkak dan query lambat | Tidak ada retensi dan indeks | Jadwalkan pembersihan, tambahkan indeks pada subject dan created_at |
| Password atau token muncul di log | Kolom sensitif tidak dikecualikan | Gunakan logOnly() atau daftar pengecualian; sterilkan log lama |
Best Practices
Keamanan
- Jangan pernah mencatat password, token, kunci API, atau data kartu. Gunakan daftar putih (
logOnly) daripada daftar hitam bila memungkinkan. - Batasi akses riwayat dengan Policy; riwayat sering berisi informasi yang lebih sensitif daripada data saat ini.
- Tabel audit sebaiknya append-only: aplikasi tidak menyediakan fitur ubah atau hapus audit. Pertimbangkan pengguna database terpisah dengan izin
INSERTdanSELECTsaja. - Perhatikan regulasi pelindungan data pribadi: IP dan user agent termasuk data pribadi. Tetapkan masa retensi dan dasar pemrosesannya.
Performa
- Untuk aplikasi dengan trafik tulis tinggi, tulis audit lewat queue (misalnya dispatch job dari trait) agar request tidak melambat.
- Pasang indeks komposit pada
(subject_type, subject_id, created_at)atau padanannya. - Jalankan pruning terjadwal; jangan biarkan tabel log tumbuh tanpa batas.
- Pertimbangkan menyimpan log di koneksi database terpisah bila volumenya sangat besar.
Maintainability
- Gunakan morph map sejak awal.
- Uji audit dengan test: ubah model, lalu pastikan baris audit berisi nilai lama dan baru yang tepat.
- Dokumentasikan operasi mana yang sengaja melewati event (update massal) beserta cara pelacakannya.
- Tampilkan riwayat dalam bahasa manusia di UI admin; log yang tidak pernah dibaca tidak membantu saat insiden.
Related Articles
- Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration
- Laravel Query Builder vs Eloquent ORM: Kapan Menggunakan Masing-Masing?
- Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource
- Membangun Laravel Starter Kit yang Reusable untuk Berbagai Jenis Aplikasi Bisnis
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| spatie/laravel-activitylog | 5.x |
| Tanggal | 19 Oktober 2026 |