Your IP : 216.73.216.79
# Activity Log Module — Dokumentasi Penuh
## 1. Pengenalan
Activity Log module merekod dan memaparkan setiap aktiviti penting dalam sistem — bila user create, update, delete data, dan siapa yang buat. Module ni guna package **Spatie Activitylog** (`spatie/laravel-activitylog`).
---
## 2. Struktur Database
**Table:** `activity_log`
| Column | Type | Description |
|--------|------|-------------|
| `id` | bigint (PK) | Primary key |
| `log_name` | string (nullable) | Nama kumpulan log (contoh: `Backend User`, `Frontend User`) |
| `description` | text | Penerangan aktiviti |
| `subject_type` | string (nullable) | Model class yang kena action (polymorphic) |
| `subject_id` | bigint (nullable) | ID record yang kena action |
| `event` | string (nullable) | Jenis event: `created`, `updated`, `deleted`, `login`, dll |
| `causer_type` | string (nullable) | Model class yang buat action (polymorphic) |
| `causer_id` | bigint (nullable) | ID user yang buat action |
| `attribute_changes` | json (nullable) | Senarai field yang berubah (old vs new) |
| `properties` | json (nullable) | Data tambahan (nullable) |
| `url` | string (nullable) | URL tempat action berlaku |
| `ip_address` | string(45) (nullable) | IP pengguna (support IPv6) |
| `user_agent` | text (nullable) | Browser/device info |
| `created_at` | timestamp | Bila log direkod |
| `updated_at` | timestamp | Bila log dikemaskini |
**Indexes:**
- `log_name` (index)
- `subject_type + subject_id` (morph index)
- `causer_type + causer_id` (morph index)
- `ip_address` (index)
- `created_at` (index)
---
## 3. Aliran Data (Data Flow)
```
┌────────────────────────────────────────────────────────────────────────┐
│ AUTO LOGGING (Spatie) │
│ │
│ BackendUser model ──LogsActivity trait──> Spatie Activitylog │
│ FrontendUser model ──LogsActivity trait──> Spatie Activitylog │
│ │
│ Setiap kali model di-create/update/delete, Spatie auto-rekod: │
│ - subject_type, subject_id (model & record ID) │
│ - event (created/updated/deleted) │
│ - description (default: "This model has been {event}") │
│ - attribute_changes (field yang berubah) │
└────────────────────────────────┬──────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ ACTIVITY OBSERVER │
│ │
│ ActivityObserver@creating() dipanggil SEBELUM activity disimpan: │
│ - Set url (current request URL) │
│ - Set ip_address (client IP) │
│ - Set user_agent (browser) │
│ - Determine causer berdasarkan auth guard (admin/user) │
│ - Set log_name berdasarkan causer_type │
└────────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ activity_log table │
└─────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ DISPLAY DI BROWSER │
│ │
│ BackendHomeController -> index.blade.php │
│ - Search by: log_name, description, event │
│ - Paginate 10 records per page │
│ - Columns: No, Log Name, Performed By, Model Name, │
│ Action, IP Address, User Agent, Timestamp │
│ - Action badges: created=green, updated=orange, deleted=red │
└────────────────────────────────────────────────────────────────────────┘
```
---
## 4. Penjelasan Setiap File
### 4.1 Package: `spatie/laravel-activitylog` (composer.json)
```
"spatie/laravel-activitylog": "^5.0"
```
Package ni yang handle:
- Auto record activity bila model diubah
- Polymorphic relationship (`subject`, `causer`)
- Batch cleanup log lama
### 4.2 Config: `config/activitylog.php`
```php
return [
'enabled' => env('ACTIVITYLOG_ENABLED', true),
'clean_after_days' => 365, // Auto delete log lebih 1 tahun
'default_log_name' => 'default',
'activity_model' => Activity::class,
'buffer' => [
'enabled' => env('ACTIVITYLOG_BUFFER_ENABLED', false),
],
];
```
- Boleh disable total guna `ACTIVITYLOG_ENABLED=false` dalam `.env`
- Log lebih 365 hari akan di-clean (via artisan command)
- Buffer mode disabled (log terus ke DB)
### 4.3 Migration: `2026_04_22_220206_create_activity_log_table.php`
Migration standard Spatie dengan custom columns tambahan:
```php
$table->string('url')->nullable();
$table->string('ip_address', 45)->nullable();
$table->text('user_agent')->nullable();
$table->json('attribute_changes')->nullable();
$table->index('ip_address');
$table->index('created_at');
```
**Custom columns** (`url`, `ip_address`, `user_agent`) tak ada dalam Spatie default — ditambah khas untuk tracking detail request.
### 4.4 Observer: `app/Observers/ActivityObserver.php`
**Registered in** `AppServiceProvider@boot`:
```php
Activity::observe(ActivityObserver::class);
```
**Function `creating(Activity $activity)`:**
Observer ni auto-populate data sebelum activity disimpan:
```
Step 1: Skip jika runningInConsole() — log dari cron/queue tak perlu URL/IP
Step 2: Set url, ip_address, user_agent dari current request
Step 3: Set causer jika belum ada:
├─ check auth:admin guard → set BackendUser
├─ check auth:user guard → set FrontendUser
└─ fallback → guna subject sebagai causer
Step 4: Set log_name berdasarkan causer_type:
├─ BackendUser → "Backend User"
└─ FrontendUser → "Frontend User"
```
**Kenapa observer penting?**
- Spatie default TIDAK rekod URL, IP, User-Agent
- Observer ni tambah detail tu secara automatik
- Juga ensure log_name konsisten (Backend User / Frontend User)
### 4.5 Model: Tidak Ada Model Khas
Module ni **tidak** guna model custom. Terus guna `Spatie\Activitylog\Models\Activity`.
```php
use Spatie\Activitylog\Models\Activity;
```
**Eloquent relationships available:**
- `$activity->subject` — polymorphic: model yang kena action
- `$activity->causer` — polymorphic: user yang buat action
- `$activity->causer()->withoutGlobalScopes()->first()` — kalau subject dah soft-deleted
### 4.6 Model dengan LogsActivity Trait
Dua model guna `LogsActivity` trait:
#### `BackendUser`
```php
use Spatie\Activitylog\Models\Concerns\LogsActivity;
class BackendUser extends Authenticatable
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logOnly(['username', 'email', 'first_name', 'last_name', 'profile_picture', 'is_active'])
->useLogName('Backend User')
->setDescriptionForEvent(fn(string $eventName) => "This model has been {$eventName}")
->dontLogEmptyChanges();
}
}
```
#### `FrontendUser`
```php
use Spatie\Activitylog\Models\Concerns\LogsActivity;
class FrontendUser extends Authenticatable
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logOnly(['username', 'email', 'first_name', 'last_name', 'profile_picture', 'is_active'])
->useLogName('Backend User') // Note: guna 'Backend User' juga!
->setDescriptionForEvent(fn(string $eventName) => "This model has been {$eventName}")
->dontLogEmptyChanges();
}
}
```
**Apa yang di-log:**
- Hanya field yang listed dalam `logOnly()` — bukan semua field
- Empty changes tak di-log (`dontLogEmptyChanges`)
- Description generic: "This model has been created/updated/deleted"
### 4.7 Controller: `app/Http/Controllers/Backend/ActivityLogController.php`
```php
class ActivityLogController extends Controller
{
public function index(Request $request)
{
$search = $request->get('search');
$activities = Activity::with('causer')
->when($search, function ($q) use ($search) {
$q->where(function ($sub) use ($search) {
$sub->where('log_name', 'like', "%{$search}%")
->orWhere('description', 'like', "%{$search}%")
->orWhere('event', 'like', "%{$search}%");
});
})
->latest()
->paginate(10)->onEachSide(1)->withQueryString();
return view('backend.module.activityLog.index', [
'activities' => $activities,
'search' => $search,
]);
}
}
```
**Fungsi:**
- `index()` — Paginated list (10/page) dengan search on `log_name`, `description`, `event`
- Eager load `causer` relationship untuk display nama user
- Order by latest (descending)
- Ada commented-out `indexApi()` untuk JSON endpoint
**Route:**
```php
Route::get('/activity-log', [ActivityLogController::class, 'index'])
->middleware('permission:activity-log.view,admin')
->name('activity-log.index');
```
### 4.8 View: `resources/views/backend/module/activityLog/index.blade.php`
**Table columns:**
| Column | Source | Format |
|--------|--------|--------|
| No | `$loop->iteration` | Number |
| Log Name | `$activity->log_name` | String |
| Performed By | `$activity->causer` | Username + email / "User #ID (Deleted)" / "System/Automated" |
| Model Name | `$activity->causer_type` | Class name (short) |
| Action | `$activity->event` | Badge: green=created, orange=updated, red=deleted, blue=other |
| IP Address | `$activity->ip_address` | Monospace font |
| User Agent | `$activity->user_agent` | Truncated 50 chars with tooltip |
| Timestamp | `$activity->created_at` | `h:i A` + `d-m-Y` |
**Features:**
- **Search** — debounce 400ms, auto-submit, search across log_name/description/event
- **Pagination** — `vendor.pagination.custom` dengan `onEachSide(1)`
- **Empty state** — icon + "No activity logs found" message
- **Causer fallback** — handle deleted user atau system action
### 4.9 Seeders
#### `BackendMenuSeeder.php`
- Create permission: `activity-log.view`
- Add route `activity-log.index` to Backend menu
- Create menu item "Activity Log" dengan icon `fa-clock-rotate-left`
#### `AdminRolePermissionSeeder.php`
- Assign `activity-log.view` to `editor` dan `viewer` roles
#### `BackendUserSeeder.php` & `FrontendUserSeeder.php`
- Disable auto-logging semasa seeder: `activity()->disableLogging()`
- Manual create satu log entry dengan event `'seeded'`
### 4.10 Permissions
| Permission | Guard | Routes Protected |
|------------|-------|-----------------|
| `activity-log.view` | admin | `activity-log.index` |
- Permission ni **protected** — tak boleh delete dari UI (dalam `PermissionController`)
- Auto-generated dari route prefix `activity-log` → module `ActivityLog` (dalam `AutoPermissionController`)
---
## 5. Cara Guna
### 5.1 Auto Logging (Models)
Untuk enable auto logging kat mana-mana model baru:
```php
use Spatie\Activitylog\Models\Concerns\LogsActivity;
use Spatie\Activitylog\Support\LogOptions;
class YourModel extends Model
{
use LogsActivity;
public function getActivitylogOptions(): LogOptions
{
return LogOptions::defaults()
->logOnly(['field1', 'field2'])
->useLogName('Your Module')
->setDescriptionForEvent(fn(string $eventName) => "This model has been {$eventName}")
->dontLogEmptyChanges();
}
}
```
### 5.2 Manual Logging
Guna dalam controller/command:
```php
use Spatie\Activitylog\Models\Activity;
// Disable auto-logging
activity()->disableLogging();
// Manual log
activity()
->performedOn($model)
->causedBy($user)
->withProperties(['key' => 'value'])
->event('custom_event')
->log('Manual description');
```
### 5.3 Query Activities
```php
use Spatie\Activitylog\Models\Activity;
// Get recent 50 logs
$logs = Activity::with('causer')->latest()->take(50)->get();
// Filter by event
$creates = Activity::where('event', 'created')->get();
// By user
$userLogs = Activity::where('causer_type', BackendUser::class)
->where('causer_id', $userId)
->get();
// By subject model
$modelLogs = Activity::where('subject_type', YourModel::class)
->where('subject_id', $recordId)
->get();
```
### 5.4 Clean Old Logs
```bash
# Manual clean log lebih 365 hari (ikut config)
php artisan activitylog:clean
```
---
## 6. Hubungan Antara Komponen
```
┌──────────────┐ ┌──────────────────┐ ┌─────────────────────────┐
│ Routes │────>│ Controllers │────>│ Views │
│ web.php │ │ │ │ │
│ │ │ ActivityLogCtrl │ │ activityLog/index.blade │
│ /activity-log│────>│ → index() │────>│ ├─ Search │
│ │ │ → with('causer')│ │ ├─ Table + Badges │
│ │ │ → paginate(10) │ │ └─ Pagination │
└──────────────┘ └──────────────────┘ └─────────────────────────┘
│
▼
┌──────────────────┐
│ Spatie\Model │
│ Activity (no custom model) │
└──────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Database: activity_log │
│ ├─ Auto populated by LogsActivity trait │
│ │ (BackendUser, FrontendUser) │
│ ├─ Observer enrich with URL/IP/UserAgent │
│ └─ Causer determined by auth guard │
└──────────────────────────────────────────────┘
```
---
## 7. Tips & Troubleshooting
### Log tak direkod
- Check `.env`: `ACTIVITYLOG_ENABLED=true`
- Confirm model guna `LogsActivity` trait
- Confirm `getActivitylogOptions()` defined
- Check observer tak skip (runningInConsole?)
### Causer sentiasa null
- Observer check middleware: `auth:admin` atau `auth:user`
- Route mesti ada middleware auth yang sesuai
- Kalau console/queue, causer tak auto-set
### IP/URL/User-Agent kosong
- Observer mungkin tak register — check `AppServiceProvider@boot`
- Observer skip jika `runningInConsole()` — log dari artisan takde request context
### Log terlalu banyak
- Adjust `clean_after_days` dalam `config/activitylog.php`
- Jalankan `php artisan activitylog:clean` secara berkala (cron)
- Limit `logOnly()` dalam `getActivitylogOptions()` — jangan log semua field
### User deleted — nama tak muncul
- View ada fallback: "User #ID (Deleted)" jika causer record dah dipadam
- Guna `$activity->causer()->withoutGlobalScopes()->first()` untuk access deleted user
### Custom log_name tak set
- Observer set `log_name` berdasarkan `causer_type`
- Kalau nak guna `log_name` berbeza, set manually dalam observer atau override