Skip to main content

​
Installation

composer require getimmutable/laravel
Requirements: PHP 8.2+, Laravel 10+

​
Configuration

Add your credentials to .env: 
GETIMMUTABLE_API_KEY=imk_your_api_key_here
GETIMMUTABLE_BASE_URL=https://getimmutable.dev
GETIMMUTABLE_ASYNC=false
VariableRequiredDescription
GETIMMUTABLE_API_KEYYesYour imk_ prefixed API key
GETIMMUTABLE_BASE_URLYesBase domain URL
GETIMMUTABLE_ASYNCNoSet true to dispatch tracking via Laravel queues

​
Service Provider

The package auto-discovers GetImmutable\GetImmutableServiceProvider. No manual registration needed.

​
Facade

use GetImmutable\AuditLog;

​
Tracking Events

​
Basic Usage

use GetImmutable\AuditLog;

AuditLog::track('document.created', 'document', [
    'actor_id' => 'user_2hG9kLm',
    'actor_name' => 'Sarah Chen',
    'actor_type' => 'user',
    'resource_id' => 'doc_8nXpQr3',
    'resource_name' => 'Q4 Financial Report',
    'metadata' => ['folder' => 'reports', 'template' => 'quarterly'],
]);

​
Fluent Builder

use GetImmutable\AuditLog;

AuditLog::actor($user)
    ->idempotencyKey('unique_key_123')
    ->version(1)
    ->session('sess_4kN8pLm')
    ->actionCategory('documents')
    ->target('folder', 'folder_3mK9pLq', 'Shared Reports')
    ->target('team', 'team_5bR7cNx', 'Engineering')
    ->track('document.created', 'document', [
        'folder' => 'reports',
        'template' => 'quarterly',
    ]);

// Or use the currently authenticated user
AuditLog::fromAuth()
    ->track('document.created', $document, [
        'folder' => 'reports',
    ]);

​
PendingEvent Methods

MethodParametersDescription
idempotencyKey($key)stringSet deduplication key
version($v)intSet event schema version
session($id)stringSet session identifier
actionCategory($cat)stringSet action category
target($type, $id?, $name?)string, string?, string?Add a single target
targets($arr)arraySet all targets at once
track($action, $resource?, $metadata?)string, string?, array?Send the event

​
Batch Ingestion

use GetImmutable\AuditLog;

AuditLog::trackBatch([
    [
        'actor_id' => 'user_2hG9kLm',
        'actor_name' => 'Sarah Chen',
        'action' => 'document.created',
        'resource_id' => 'doc_8nXpQr3',
        'resource_name' => 'Q4 Financial Report',
    ],
    [
        'actor_id' => 'user_2hG9kLm',
        'actor_name' => 'Sarah Chen',
        'action' => 'document.shared',
        'resource_id' => 'doc_8nXpQr3',
        'targets' => [
            ['type' => 'team', 'id' => 'team_5bR7cNx', 'name' => 'Engineering'],
        ],
    ],
]);

​
Querying Events

$response = AuditLog::getEvents([
    'actor_id' => 'user_2hG9kLm',
    'action' => 'document.*',
    'from' => '2026-03-01T00:00:00Z',
    'limit' => 25,
]);

// $response['data'] -- array of events
// $response['pagination']['has_more'] -- boolean
// $response['pagination']['next_cursor'] -- string|null

​
Retrieving a Single Event

$event = AuditLog::getEvent('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d');

$event['integrity']['event_hash'];
$event['integrity']['previous_event_hash'];

​
Verification

$result = AuditLog::verify();

if (!$result['data']['valid']) {
    Log::critical('Audit log integrity violation', [
        'breaks' => $result['data']['breaks'],
    ]);
}

// With date range
$result = AuditLog::verify('2026-03-01T00:00:00Z', '2026-03-31T23:59:59Z');

​
Viewer Tokens

$token = AuditLog::createViewerToken([
    'tenantId' => 'org_7rT2xBc',
    'actorId' => 'user_2hG9kLm',
    'ttl' => 7200,
]);

$token['token'];      // JWT string
$token['expires_at']; // ISO timestamp

​
Alerts

$alerts = AuditLog::getAlerts([
    'rule_type' => 'new_country',
    'limit' => 25,
]);

​
Exports

$export = AuditLog::createExport([
    'actor_id' => 'user_2hG9kLm',
    'from' => '2026-03-01T00:00:00Z',
]);

$status = AuditLog::getExport($export['id']);

​
Auto-Session Tracking

The Laravel SDK can automatically attach the current Laravel session ID to every tracked event. Enable this in your configuration: 
// Auto-session reads from Laravel's session store
// No explicit ->session() calls needed

​
Eloquent Observer Example

Track model events automatically using an Eloquent observer: 
namespace App\Observers;

use App\Models\Document;
use GetImmutable\AuditLog;

class DocumentObserver
{
    public function created(Document $document): void
    {
        AuditLog::fromAuth()
            ->track('document.created', $document, [
                'size' => $document->size,
                'mime_type' => $document->mime_type,
            ]);
    }

    public function updated(Document $document): void
    {
        AuditLog::fromAuth()
            ->track('document.updated', $document, [
                'changed_fields' => array_keys($document->getDirty()),
            ]);
    }

    public function deleted(Document $document): void
    {
        AuditLog::fromAuth()
            ->track('document.deleted', $document);
    }
}
Register the observer in your AppServiceProvider: 
use App\Models\Document;
use App\Observers\DocumentObserver;

public function boot(): void
{
    Document::observe(DocumentObserver::class);
}

​
Queue Integration

Set GETIMMUTABLE_ASYNC=true in your .env to dispatch tracking calls via Laravel’s queue system instead of making synchronous HTTP requests. This prevents audit logging from blocking your application’s response time. 
GETIMMUTABLE_ASYNC=true
Ensure your queue worker is running to process the dispatched jobs.