README

The Audit Log package is an open source Composer package for use in Laravel applications that is used by other Boldly Grow packages and ventures including Provisionr to provide a consistent log syntax and optional database persistence for audit events. Although this is purpose built for our packages, you are welcome to adopt this for your own standardized logging.

Please use at your own risk and create pull requests for any bugs that you encounter.

Problem Statement

When using Laravel Logging with the Log::info('Message', ['key1' => 'value', 'key2' => 'value']) syntax, it is easy to have inconsistency with log formatting that results in a variety of log messages and varying context keys.

The BoldlyGrow\AuditLog\AuditLog::create() method provides a pre-defined set of context keys that allow us to improve indexing and searchability in external logging platforms, and ensures that all events provide as much context data as possible in a consistent format.

Sometimes you need to get a formatted array that can be added to a changelog or actioned upon programmatically instead of trying to tail a log file. An array is returned for each log entry that is created.

Feature Comparison

How this package compares to Laravel's built-in logging and Spatie Activity Log. Each capability links to the section that documents it.

Legend: ✅ built-in · ◐ partial or manual · ❌ not provided

Capability	Laravel Logs	Spatie Activity Log	BoldlyGrow Audit Log
Records & storage
Durable database table	❌	✅	✅
System log-channel output	✅	❌	✅
Configurable table & model	❌	✅	✅
UUIDv7 primary keys	❌	❌	✅
Soft deletes (recoverable)	❌	❌	✅
Indexed for query performance	❌	◐	✅
Attribution
Actor identity / causer	❌	✅	✅
Session, IP & request source	❌	❌	✅
Configurable actor attribute mapping	❌	◐	✅
Proxy / CDN IP resolution	❌	❌	✅
Event content
Standardized structured schema	❌	◐	✅
Event classification (type / level / outcome)	◐	◐	✅
State change (old / new values)	❌	✅	✅
Affected-resource linkage	❌	◐	✅
Model → snake_case type + FQCN	❌	◐	✅
Background job / batch / pipeline metadata	❌	◐	✅
Automatic capture
Automatic model-change logging (trait)	❌	✅	❌
Runs without a database (log-only)	✅	❌	◐
Security & compliance
Encryption at rest	❌	❌	✅
Search encrypted fields	❌	❌	✅
Immutable records (block update / destroy)	❌	❌	✅
Tamper-evident mutation recording	❌	❌	✅
Compliance control mapping	❌	❌	✅
Querying & output
Date-range scopes	❌	◐	✅
Relationship querying	❌	◐	✅
SIEM-friendly string-type search	❌	◐	✅
Custom indexable columns	❌	◐	✅
Formatted response array / DTO	❌	❌	✅
Configurable response schemas	❌	❌	✅
Copyable API endpoint examples	❌	❌	✅

The two competitor-win rows are deliberate: Spatie Activity Log logs model changes automatically via a trait (this package favors explicit, intentional AuditLog::create() events), and Laravel's channel logging runs with no database (persistence here is optional — see Skipping Log Creation).

Audit Record Completeness & Scope

A single event can capture every element that audit-record standards — NIST 800-53 AU-3, CIS 8.5, ISO 27001 A.8.15 — expect a record to contain:

Required element	Package field(s)
What happened	`event_type`, `level`, `message`, `method`
When	`occurred_at`, `datetime` (ISO 8601 Zulu), `created_at`
Where / source	`actor_source`, `actor_ip_addr`, `actor_session_id`, `method`
Outcome	`event_type` result segment (e.g. `…success`, `…error.validation`), `level`
Who	`actor_id`, `actor_email`, `actor_name`, `actor_username`, `actor_provider_id`, `actor_type`
Affected resources + before/after	`record_`, `parent_`, `related_`, `subject_`, `tenant_*`, `attribute_value_old`, `attribute_value_new`

Scope — what this package does not do. It generates and stores records; it is not a full audit-management platform. You remain responsible for retention scheduling, access control to the logs, review / alerting (SIEM), time synchronization, and cryptographic tamper-evidence (hashing / signing). For how the package's capabilities map to compliance frameworks (SOC 1/2, ISO 27001, NIST 800-53/63/171, CISA, CIS) and the full shared-responsibility boundaries, see COMPLIANCE.md.

Issue Tracking and Bug Reports

We do not maintain a roadmap of feature requests, however we invite you to contribute and we will gladly review your merge requests.

Please create an issue for bug reports.

Contributing

Please see CONTRIBUTING.md to learn more about how to contribute.

Maintainers

Name	GitLab Handle	Email
Jeff Martin	@jeffersonmartin	`jeff [at] boldlygrow [dot] us`

Contributor Credit

Jeff Martin

Installation

Requirements

Requirement	Version
PHP	`^8.2`
Laravel	`^11.0`, `^12.0`, `^13.0`

Upgrade Guide

See the changelog for release notes. If you are upgrading from provisionesta/audit (1.x), read the 2.0 release notes for the package rename, class rename, and configuration changes.

Add Composer Package

composer require boldlygrow/audit-log:^2.0

The old provisionesta/audit package name is retained as a replace alias, so existing dependency graphs continue to resolve during the transition.

If you are contributing to this package, see CONTRIBUTING.md for instructions on configuring a local composer package with symlinks.

Publish the config and migration

Publish both the config file and the migration together:

php artisan vendor:publish --tag=audit-log

Or publish them separately:

php artisan vendor:publish --tag=audit-log-config
php artisan vendor:publish --tag=audit-log-migrations

Publishing the config file (config/audit-log.php) is optional — the package works with sensible defaults and it is only needed to customize settings such as response schemas (dump_config). The migration is required for database persistence, which is enabled by default.

Before running the migration, review the identifier column formats. The published migration defaults the primary key to UUIDv7 (timestamp-ordered — the de facto standard for logging systems) and the polymorphic reference ids (actor_id, record_id, parent_id, related_id, subject_id, tenant_id) to CHAR(36), sized for a UUID or ULID. An inline comment block at the top of the migration shows how to switch any of them to BIGINT, ULID, or a custom/VARCHAR format to match your own models — decide this now, since changing it later means an additional migration. If you change the primary key type, also update the base model's boot() id generation (override it on a model that extends the base).

To make sure this review is not skipped, the migration ships with a SAFETY CHECK block at the top of its up() method that throws until you delete it — php artisan migrate will fail with an explanatory message until you have reviewed the formats and removed that block. (The guard is skipped automatically under the test runner, so it does not affect your test suite.) Once you have removed it, run:

php artisan migrate

Bundled Examples

The package ships copyable reference implementations in the examples/ directory — including two variants of a read-only audit log API (list + describe), one dependency-free and one using Spatie Query Builder + Laravel Data. They are reference stubs (not autoloaded) to copy into your app and adapt. See Example API Endpoints for details.

Usage Examples

Basic Usage

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    event_ms: $event_ms,
    event_type: 'okta.api.post.success.ok',
    level: 'info',
    message: 'Success',
    metadata: [
        'okta_request_id' => 'REDACTED',
        'rate_limit_remaining' => $request->headers['x-rate-limit-remaining'],
        'uri' => 'users',
        'url' => 'https://dev-12345678.okta.com/api/v1/users?activate=true'
    ],
    method: __METHOD__
);

Comprehensive Usage

You can copy and paste this example anywhere in your code that you would create a log entry. Any arguments that are not relevant can be removed and will be considered null.

The actor_* fields are intentionally omitted below — they are automatically populated from the authenticated user based on your configuration. See Actor Metadata to customize, map, or override them.

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    attribute_key: 'xxx',
    attribute_value_old: 'xxx',
    attribute_value_new: 'xxx',
    count_records: count($array),
    database: false,
    dump_config: null,
    dump_date: 'c',
    dump_keys: [],
    dump_strings: [],
    duration_ms: $duration_ms,
    duration_ms_per_record: (int) ($duration_ms / count($records)),
    errors: [],
    event_ms: $event_ms,
    event_ms_per_record: (int) ($event_ms / count($records)),
    event_type: '{provider}.{entity}.{action}.xxx',
    level: 'info',
    log: true,
    message: '{What happened}',
    metadata: [],
    method: __METHOD__,
    occurred_at: $entity->created_at,
    parent_id: $parent->id,
    parent_model: ProviderApplication::class, // parent_type => "provider_application"
    parent_provider_id: $parent->provider_id,
    parent_reference_key: 'name',
    parent_reference_value: $entity->organization->name,
    record_id: $entity->id,
    record_model: ProviderEntity::class,      // record_type => "provider_entity"
    record_provider_id: $entity->provider_id,
    record_reference_key: 'name',
    record_reference_value: $entity->name,
    related_id: $manager->id,
    related_model: ProviderUser::class,
    subject_id: $service->id,
    subject_model: ProviderService::class,
    tenant_id: $entity->provider_organization_id,
    tenant_model: ProviderOrganization::class,
);

Example Output

[YYYY-MM-DD HH:II:SS] local.DEBUG: ApiClient Success {"event_type":"okta.api.post.success.ok","method":"BoldlyGrow\\Okta\\ApiClient::post","event_ms":627,"metadata":{"okta_request_id":"REDACTED","rate_limit_remaining":"16","uri":"users","url":"https://dev-12345678.okta.com/api/v1/users?activate=true"}"}

The log message is prefixed with the class name only (ApiClient). The fully-qualified method remains in the log context.

{
    "event_type": "okta.api.post.success.ok",
    "method": "BoldlyGrow\\Okta\\ApiClient::post",
    "event_ms": 627,
    "metadata": {
        "okta_request_id": "REDACTED",
        "rate_limit_remaining": "16",
        "uri": "users",
        "url": "https://dev-12345678.okta.com/api/v1/users?activate=true"
    }
}

Log Parameter Definitions

The actor_* fields are auto-populated from the authenticated user using the attribute map in config('audit-log.actor.attributes'), so you normally do not pass them. Provide an actor_* argument only to override the automatic value. For those rows, the Example Usage column shows the default source of the value. See Actor Metadata for mapping and overriding.

Parameter Name	Example Usage	Description
event_type (Required) `string`	`provider.entity.action.result.reason`	The octet notation event type that follows our codestyle conventions.
level (Required) `string`	`debug` `info` `notice` `warning` `error` `critical` `alert` `emergency`	The log level for the log entry
message (Required) `string`	Validation Failed	A short message to include in the logs. This will be auto-prefixed with the fully-qualified method name (the "noun") so you can keep the message focused on the "verb" language.
method (Required) `string`	`__METHOD__`	The method where this audit log is created in or is on behalf of.
actor_email `string`	`email` attribute (default)	The email address of the actor. Auto-populated from the user; pass to override.
actor_id `string`	`id` attribute (default)	The database ID of the actor. Auto-populated from the user; pass to override.
actor_name `string`	`name` ?? `full_name` (default)	The first and last name of the actor. Auto-populated from the user; pass to override.
actor_provider_id `string`	`provider_id` attribute (default)	The 3rd party vendor API ID of the actor (ex. Okta User ID). Auto-populated from the user; pass to override.
actor_session_id `string`	`session()->getId()`	The session ID of the actor. Auto-populated; pass to override.
actor_source `string`	`system` / `api` / `web` (auto-detected)	The origin of the request. Auto-detected when omitted, or pass `cli`/a custom value explicitly; see Actor Source. Validated against `config('audit-log.actor.source.allowed')`.
actor_model `string`	authenticated user model class	The fully-qualified class name of the authenticated user model. Auto-populated; pass to override.
actor_type `string`	snake_case of the user model class	A human-friendly snake_case string derived from `actor_model` (ex. `user`). Auto-populated; pass to override.
actor_username `string`	`username` attribute (default)	The username of the actor. Auto-populated from the user; pass to override.
attribute_key `string`		(State Changes) The database column name that has changed.
attribute_value_old `string`		(State Changes) The value in the database before the update.
attribute_value_new `string`		(State Changes) The API value that is now updated in the database.
count_records `int`	`count($array)`	(Multiple records) Count of records processed.
database `bool`	`true` `false` (default)	Whether to persist this event to the database. See Database Persistence.
dump_config `string`	`default`	(Response Schema) The array key in `config/audit-log.php` that contains the `date`, `keys`, `strings` schema configuration. The other `dump_*` parameters are ignored if `dump_config` is set.
dump_date `string`	`c` `Y-m-d` `Y-m-d H:i:s`	(Response Schema) The PHP datetime format string for timestamps returned in the response array.
dump_keys `array`	See docs	(Response Schema) An filtered list of array of keys from the `AuditLog::create()` method that returned in the response array.
dump_strings `array`	See docs	(Response Schema) An array of key value pairs of static strings that should be included in the in the response array (instead of having to add them yourself with collection transformation later).
duration_ms `CarbonInterface`	`$duration_ms`	Carbon instance (timestamp) used for long running batch jobs to provide a point-in-time duration since job started. Any `CarbonInterface` implementation is accepted, including `CarbonImmutable`.
duration_ms_per_record `int`	`(int) ($duration_ms / count($records))`	Number of milliseconds divided by count of records. This is not auto-calculated to allow flexibility for custom Carbon timestamps
errors `array`		Flat array of error message(s) that will be encoded as JSON
event_ms `CarbonInterface`	`$event_ms`	Carbon instance (timestamp) that was initialized at the start of the action and provides a point-in-time duration for this specific action within a longer running job. Any `CarbonInterface` implementation is accepted, including `CarbonImmutable`.
event_ms_per_record `int`	`(int) ($event_ms / count($records))`	Number of milliseconds divided by count of records. This is not auto-calculated to allow flexibility for custom Carbon timestamps
job_batch `string`		(Background Job Logs) The human identifier string or system ID of the batch of jobs. Format is at your discretion.
job_id `string`		(Background Job Logs) The human identifier string or system ID of the specific job that triggered this log entry. Format is at your discretion.
job_platform `string`	`github` `gitlab` `lambda` `redis` `{your string}`	(Background Job Logs) The human identifier string of the platform that the background jobs are running in. Format is at your discretion.
job_pipeline_id `string`		(Background Job Logs) The system ID of the CI/CD pipeline (if applicable).
job_timestamp `string`	`now()->getTimestamp()`	(Background Job Logs) The timestamp that the job or pipeline was started. This is useful for identifying which scheduled job timestamp triggered this event.
job_transaction_id `string`	`now()->getTimestamp()`	(Background Job Logs) An alternative to `job_id` that can be used for additional indexable identifiers used by your application or business logic.
log `bool`	`true` (default) `false`	Whether to create a system log entry for this event. See docs.
metadata `array`		An array of custom metadata that should be included in the log
occurred_at `string`	`2023-02-01T03:45:27.612584Z`	A datetime that will be formatted with Carbon for when the event occurred at based on a created_at or updated_at API timestamp
parent_id `string`	`{uuid}`	(Many-to-Many Relationship Events) The database ID of the database model with a many-to-many relationship.
parent_type `string`	`App\Models\Path\To\ModelName`	(Many-to-Many Relationship Events) The fully-qualified namespace of the database model with a many-to-many relationship.
parent_model `string`	`ProviderApplication::class`	(Many-to-Many Relationship Events) The model class name. Auto-calculates `parent_type`; see Model References.
parent_provider_id `string`	`a1b2c3d4e5f6`	(Many-to-Many Relationship Events) The API ID of the database model with a many-to-many relationship that is usually stored in the database in the `provider_id` column.
parent_reference_key `string`	`name`	(Many-to-Many Relationship Events) The database column name for value that is human readable in logs
parent_reference_value `string`		(Many-to-Many Relationship Events) The value of the human readable database column
record_id `string`	`{uuid}`	The database ID of the affected database model
record_type `string`	`App\Models\Path\To\ModelName`	The fully-qualified namespace of the database model
record_model `string`	`ProviderEntity::class`	The model class name of the affected record. Auto-calculates `record_type`; see Model References.
record_provider_id `string`	`a1b2c3d4e5f6`	The API ID of the affected database model that is usually stored in the database in the `provider_id` column.
record_reference_key `string`	`name`	The database column name for value that is human readable in logs
record_reference_value `string`		The value of the human readable database column
related_id `string`	`{uuid}`	The database ID of a related model that should be referenced in logs.
related_model `string`	`ProviderUser::class`	The model class name of a related model that should be referenced in logs. Auto-calculates `related_type`.
subject_id `string`	`{uuid}`	The database ID of the impacted human user, service account, or other audited subject.
subject_model `string`	`ProviderService::class`	The model class name of the subject. Kept generic so any application model may be used. Auto-calculates `subject_type`.
tenant_id `string`	`{uuid}`	The database ID of the top-level organization/tenant for the provider
tenant_type `string`	`App\Models\VendorName\Organization`	The fully-qualified namespace of the database model of the top-level entity (organization, tenant, etc) for the provider.
tenant_model `string`	`ProviderOrganization::class`	The model class name of the top-level entity. Auto-calculates `tenant_type`.
transaction `bool` (deprecated)	`true` `false` (default)	Deprecated alias for `database`. Either flag persists the event. Prefer `database`.

Advanced Usage

Actor Metadata

The following fields related to the actor (authenticated user) are captured with each log entry.

This uses Auth::user() that uses the model configured in the providers array in config/auth.php. The Laravel default is App\Models\User::class, however your application may use a different model.

Mapping Custom User Attributes

If your user model uses different column names (for example work_email or display_name), map each actor field to the attribute(s) it should read in config('audit-log.actor.attributes'). A mapping may be a single attribute name or an ordered list of candidates, in which case the first non-null value wins (this is how name falls back to full_name by default).

// config/audit-log.php
'actor' => [
    'attributes' => [
        'id' => 'id',
        'email' => 'work_email',
        'name' => ['display_name', 'name', 'full_name'],
        'provider_id' => 'okta_id',
        'username' => 'handle',
    ],
],

Attribute	Authenticated (`Auth::check()`)	Unauthenticated
`actor_email`	`Auth::user()->email`	null
`actor_id`	`Auth::user()->id`	null
`actor_ip_addr`	proxy header or `request()->ip()`	proxy header or `request()->ip()`
`actor_name`	`Auth::user()->name ?? Auth::user()->full_name`	null
`actor_provider_id`	`Auth::user()->provider_id`	null
`actor_session_id`	`session()->getId()`	`session()->getId()`
`actor_source`	`system` / `api` / `web` (auto-detected)	`system` / `api` / `web`
`actor_model`	`Auth::user()::class` (FQCN)	null
`actor_type`	snake_case of `Auth::user()::class`	null
`actor_username`	`Auth::user()->username`	null

Actor IP Address Behind a Proxy or CDN

If your application is behind a proxy or CDN, add the trusted header(s) that carry the originating IP to config('audit-log.actor.ip_headers'). The first non-empty header wins, falling back to request()->ip().

// config/audit-log.php
'actor' => [
    'ip_headers' => [
        'CF-Connecting-IP',
        'X-Forwarded-For',
    ],
],

Actor Source

The actor_source field records the origin of the request. It is auto-detected as system (console commands and queued jobs), api (API routes or requests that expect JSON), or web. The cli value is available for applications that detect device-based tokens, and must be passed explicitly.

The allowed vocabulary lives in one place. Add your own values (for example service) there, and any value passed to AuditLog::create(actor_source: '...') is validated against the list.

// config/audit-log.php
'actor' => [
    'source' => [
        'enabled' => true,
        'allowed' => ['system', 'cli', 'api', 'web'],
    ],
],

The table above shows the defaults that are auto-populated for each actor field. You can override any of them by passing the corresponding argument to AuditLog::create().

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    // ...
    actor_email: '{string}',
    actor_id: '{string}',
    actor_ip_addr: '{string}',
    actor_model: '{string}',
    actor_name: '{string}',
    actor_provider_id: '{string}',
    actor_session_id: '{string}',
    actor_source: '{string}',
    actor_type: '{string}',
    actor_username: '{string}',
    // ...
);

Disabling Actor Metadata

Actor metadata is enabled by default. You can disable actor metdata if you do not want to capture actor metadata automatically or your application does not support request and session data (ex. Laravel Zero CLI app).

Set the enabled flag to false in config/audit-log.php:

    'actor' => [
-        'enabled' => true,
+        'enabled' => false,
    ],

Background Job Log Entry

You can add the job_* parameters if you are running background jobs and want to add metadata to your logs and persisted database records. All of these values (except job_timestamp) are freeform strings that you can standardize however you'd like.

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    // ...
    job_batch: '{string}',
    job_id: '{string}',
    job_platform: '{string}',
    job_pipeline_id: '{string}',
    job_timestamp: now()->getTimestamp(),
    job_transaction_id: '{string}',
    // ...
);

Model References and Automatic Types

Each relationship (parent, record, related, subject, tenant) accepts a fully-qualified model class name via a *_model parameter. The paired *_type value is auto-calculated as a snake_case string using the namespace configured in config('audit-log.model.namespace') (default App\Models\).

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    // ...
    record_id: $user->id,
    record_model: \App\Models\Okta\User::class, // record_type => "okta_user"
    related_id: $manager->id,
    related_model: \App\Models\Okta\User::class,
    subject_id: $service->id,
    subject_model: \App\Models\Service::class,  // any module's model may be used
    // ...
);

The legacy string parameters (record_type: 'App\\Models\\Okta\\User') still work for backwards compatibility. When both are provided, an explicit *_type overrides the value calculated from *_model — so you can point the *_model column at a class while logging a custom *_type key.

Simple String Searches with `*_type`

The whereMorphedTo() / whereHasMorph() relationship queries operate on the FQCN *_model columns — pass a class or model instance, not the snake_case string.

For everything else, prefer the paired *_type column. It stores a stable, human-friendly snake_case string (okta_user) rather than a PHP class name (App\Models\Okta\User), so it is a plain column you can match with where() or raw SQL:

$events = AuditLog::where('record_type', 'okta_user')->get();

This is the better fit whenever the consumer is not PHP:

API filters — clients pass record_type=okta_user, not a fully-qualified class string. The example API endpoints expose exactly this.
CSV / JSON exports and SIEM ingestion — downstream tools search and correlate on okta_user without needing to know your namespace, and the value stays stable even if the underlying model class is later moved or renamed.
Records whose model no longer exists — the string is preserved regardless of whether the class is still resolvable.

The actor relationship follows the same pattern: actor_model stores the FQCN (match it with the class string, where('actor_model', User::class)) and actor_type stores the snake_case string (where('actor_type', 'user')).

Indexing. Every *_type column is indexed by the shipped migration as a compound (*_type, *_id) index (for actor, record, parent, related, subject, and tenant). A bare where('record_type', ...) still uses the index via its leftmost prefix, and a where('record_type', ...)->where('record_id', ...) "history of one record" lookup is fully covered — no extra work on your part. The (*_model, *_id) columns are indexed too, so the relationship queries (whereMorphedTo() / morphTo eager-loading) are index-backed as well.

Database Persistence

In addition to writing to the system log, entries can be persisted to a database table for perpetual audit storage and querying.

Publish and run the migration (skip the publish if you already ran vendor:publish --tag=audit-log):
```
php artisan vendor:publish --tag=audit-log
php artisan migrate
```

Pass database: true on the events you want to persist:

use BoldlyGrow\AuditLog\AuditLog;

AuditLog::create(
    // ...
    database: true,
    // ...
);

Database persistence is enabled by default via config('audit-log.database.enabled'); set it to false if your application does not use a database. Entries are stored using the package's BoldlyGrow\AuditLog\Models\AuditLog model by default.

To add relationships, casts, or scopes — for example to reference the audit log from your UI or API — create your own model that extends the base model and point config('audit-log.database.model') at it:

namespace App\Models;

use BoldlyGrow\AuditLog\Models\AuditLog as BaseAuditLog;

class AuditLog extends BaseAuditLog
{
    // Add your relationships, casts, and scopes here.
}

The table name is configurable via config('audit-log.database.table'). If persistence is enabled but the table has not been migrated (or the configured model is invalid), a warning is logged and the event is still written to the system log — a misconfiguration never prevents your code from completing.

Encryption at Rest

The shipped model encrypts several columns that commonly hold PII or changed values — actor_email, actor_name, actor_username, attribute_value_old, attribute_value_new, parent_reference_value, record_reference_value, and metadata — using Laravel's encrypted casts. Those columns are stored as TEXT, and the model decrypts them transparently on read. This protects the database copy only; the same values are not encrypted in the system log channel. Encryption requires your application's APP_KEY to be set. To encrypt additional columns, add encrypted casts on a model that extends the base and switch the corresponding columns to TEXT.

Immutability

Audit trails are frequently required to be tamper-evident, so persisted records are immutable by default. Two independent controls in config('audit-log.immutable') govern this:

'immutable' => [
    'update' => true,   // block updates to an existing record
    'destroy' => true,  // block permanent deletion (forceDelete)
],

When a control is true, the operation throws BoldlyGrow\AuditLog\Exceptions\ImmutableRecordException:

$log->update(['message' => 'changed']); // throws when immutable.update is true
$log->forceDelete();                     // throws when immutable.destroy is true

A record may always be soft deleted — this is never blocked (destroy only gates forceDelete()), so you can hide/expire entries while keeping them recoverable:

$log->delete();   // always allowed; the record is retained (soft deleted)

Every mutation is itself recorded as a new audit entry — including who did it (resolved through the standard actor pipeline) — so the trail is self-describing. Soft deletes and restores are always recorded; updates and force deletes are recorded when their control is false (i.e. allowed):

Operation	`immutable.*`	Result	Recorded event
Soft delete (`delete()`)	—	always allowed	`audit.log.soft_deleted`
Restore (`restore()`)	—	always allowed	`audit.log.restored`
Update	`update: true`	throws	—
Update	`update: false`	allowed	`audit.log.updated`
Force delete (`forceDelete()`)	`destroy: true`	throws	—
Force delete (`forceDelete()`)	`destroy: false`	allowed	`audit.log.destroyed`

The meta entry links back to the mutated record via record_id / record_model.

Atomicity. Each mutation and the entry it records run in a single database transaction, so a record is never changed without its log — if writing the audit entry fails, the mutation rolls back with it.

Justification. For compliance workflows you can attach a reason that is stored on the meta entry's metadata (encrypted at rest):

$log->withJustification('Legal hold released, ticket #4567')->delete();

Because these controls are enforced on the model, they apply to any model that extends BoldlyGrow\AuditLog\Models\AuditLog. Turning a control off is a deliberate, auditable act — the change from true to false is itself the thing your compliance process should gate.

Searching Encrypted Fields

The encrypted columns — actor_email, actor_name, actor_username, attribute_value_old, attribute_value_new, parent_reference_value, record_reference_value, and the metadata array — are stored as ciphertext. Laravel's encryption is non-deterministic (encrypting the same value twice produces different ciphertext), so a normal SQL query can never match them:

// Never matches — the column holds ciphertext, not the plaintext
AuditLog::where('actor_email', 'jsmith@acme.com')->get();

The base model uses the BoldlyGrow\AuditLog\Traits\ModelEncryptedLookup trait, which adds query scopes that decrypt the column in PHP, build a cached id => value lookup index, and constrain the query to the matching primary keys.

Throughout this section, AuditLog refers to your Eloquent model — either the base BoldlyGrow\AuditLog\Models\AuditLog or your own App\Models\AuditLog that extends it. Every scope returns an Eloquent query builder, so you can chain ->get(), ->first(), ->count(), ->paginate(), ->orderBy(), and additional ->where() constraints just like a normal query.

Available Scopes

Scope	Description	Example
`whereEncryptedStringExact($column, $value)`	Exact, case-insensitive match on an encrypted string column	Example
`whereEncryptedStringPartial($column, $value)`	Case-insensitive substring match anywhere in the value	Example
`whereEncryptedStringStartsWith($column, $value)`	Value begins with the term	Example
`whereEncryptedStringEndsWith($column, $value)`	Value ends with the term	Example
`whereEncryptedArraySearch($column, $search)`	Substring match across every key and value of an encrypted array column	Example
`whereEncryptedArrayExact($column, $key, $value)`	Exact match for a specific array key	Example
`whereEncryptedArrayPartial($column, $key, $value)`	Substring match for a specific array key	Example
`whereEncryptedArrayStartsWith($column, $key, $value)`	A specific array key begins with the term	Example
`whereEncryptedArrayEndsWith($column, $key, $value)`	A specific array key ends with the term	Example
`encryptedArrayKeys($column)` (static)	List the distinct keys present in an encrypted array column	Example

Every scope except whereEncryptedArraySearch accepts a final bool $cache = true argument — pass false to rebuild the index from fresh data. See Caching and Fresh Data.

String Column Searches

Exact String Match

whereEncryptedStringExact() returns records whose decrypted value equals your term. Matching is case-insensitive.

use App\Models\AuditLog;

// Every event attributed to a specific email address
$events = AuditLog::whereEncryptedStringExact('actor_email', 'jsmith@acme.com')->get();

// Case does not matter — this also matches "JSmith@Acme.com"
$event = AuditLog::whereEncryptedStringExact('actor_name', 'john smith')->first();

This is the encrypted-column equivalent of:

SELECT * FROM audit_logs WHERE LOWER(actor_email) = LOWER('jsmith@acme.com');

Partial String Match

whereEncryptedStringPartial() returns records where the term appears anywhere in the decrypted value (case-insensitive substring).

// Every actor whose email is on the acme.com domain
$events = AuditLog::whereEncryptedStringPartial('actor_email', 'acme.com')->get();

// Every event whose old value contained "pending"
$events = AuditLog::whereEncryptedStringPartial('attribute_value_old', 'pending')->get();

Starts-With and Ends-With

whereEncryptedStringStartsWith() and whereEncryptedStringEndsWith() anchor the match to the beginning or end of the value.

// Emails that start with "jsmith"
$events = AuditLog::whereEncryptedStringStartsWith('actor_email', 'jsmith')->get();

// Emails that end with the acme.com domain
$events = AuditLog::whereEncryptedStringEndsWith('actor_email', 'acme.com')->get();

Matching is case-insensitive, like the other scopes. See Case Sensitivity and Normalization.

Array Column Searches

The metadata column is an encrypted array (encrypted:array). These scopes search inside it. The examples assume rows created with metadata like:

AuditLog::create(
    // ...
    database: true,
    metadata: [
        'approved_by' => 'John Smith',
        'ticket' => 'CHG-10482',
    ],
);

Search the Entire Array

whereEncryptedArraySearch() performs a case-insensitive substring search across all keys and values of the array.

// Any metadata that mentions "acme" in any key or value
$events = AuditLog::whereEncryptedArraySearch('metadata', 'acme')->get();

whereEncryptedArraySearch() always reads live data and does not take a cache argument.

Match a Specific Array Key

The keyed scopes target one array key:

// Exact (case-insensitive) match on metadata['approved_by']
$events = AuditLog::whereEncryptedArrayExact('metadata', 'approved_by', 'John Smith')->get();

// Partial match on metadata['approved_by']
$events = AuditLog::whereEncryptedArrayPartial('metadata', 'approved_by', 'john')->get();

// Prefix / suffix match on metadata['ticket']
$events = AuditLog::whereEncryptedArrayStartsWith('metadata', 'ticket', 'chg-')->get();
$events = AuditLog::whereEncryptedArrayEndsWith('metadata', 'ticket', '10482')->get();

Listing Array Keys

encryptedArrayKeys() (a static method, not a scope) returns the distinct set of keys present across an encrypted array column — useful for building filters or discovering what has been stored.

$keys = AuditLog::encryptedArrayKeys('metadata');

// [
//     0 => 'approved_by',
//     1 => 'ticket',
//     2 => 'source_ip',
// ]

Chaining with Other Constraints

Because the scopes return a query builder, combine them with ordinary constraints, ordering, and pagination:

// Failed login events for a given user, newest first, paginated
$events = AuditLog::whereEncryptedStringExact('actor_email', 'jsmith@acme.com')
    ->where('event_type', 'okta.auth.login.error.invalid')
    ->orderByDesc('occurred_at')
    ->paginate(25);

// Count how many events referenced a value
$count = AuditLog::whereEncryptedStringPartial('record_reference_value', 'acme corp')->count();

// Include soft-deleted rows in the results
$events = AuditLog::withTrashed()
    ->whereEncryptedStringExact('actor_username', 'jsmith')
    ->get();

The lookup index is built including soft-deleted rows, but the returned query still applies the model's soft-delete scope. Chain ->withTrashed() (as above) if you want trashed records in the results.

Case Sensitivity and Normalization

All of the scopes are case-insensitive. The lookup index normalizes every stored value to lowercase, and each scope lowercases your search term before comparing, so John Smith, john smith, and JOHN SMITH all match the same records.

Caching and Fresh Data

Building the lookup index decrypts every row, so the result is cached (the cache payload is itself encrypted) for two minutes. Repeated searches within that window are served from cache.

Pass cache: false as the final argument to bypass and rebuild the index — use this immediately after writing rows you need to search:

// Force a fresh index (e.g., right after creating new audit rows)
$events = AuditLog::whereEncryptedStringExact('actor_email', 'jsmith@acme.com', cache: false)->get();

$events = AuditLog::whereEncryptedArrayExact('metadata', 'approved_by', 'John Smith', cache: false)->get();

Performance Considerations

These scopes trade database-side filtering for the ability to search encrypted data:

On a cache miss, the entire column is decrypted in memory to build the id => value index, so cost grows with table size. The index is built over the whole table regardless of any constraints you chain afterward (those constrain the returned builder, not the index). This suits moderate tables and background jobs.
Prefer non-encrypted, indexed columns (event_type, record_type / record_id, actor_id, occurred_at) for high-volume filtering, and use encrypted search to locate specific actors or values.

Date Range Scopes

The base model ships query scopes for filtering persisted records by date. Each accepts any Carbon-parsable date or datetime string (or a Carbon/DateTime instance), and the comparison is inclusive (<= / >=). Throughout this section, AuditLog refers to your Eloquent model — either the base BoldlyGrow\AuditLog\Models\AuditLog or your own App\Models\AuditLog that extends it.

Scope	Column	Description
`createdBefore($date)`	`created_at`	Records written on or before the date
`createdAfter($date)`	`created_at`	Records written on or after the date
`occurredBefore($date)`	`occurred_at`	Records whose event `occurred_at` is on or before the date
`occurredAfter($date)`	`occurred_at`	Records whose event `occurred_at` is on or after the date
`deletedBefore($date)`	`deleted_at`	Soft-deleted records deleted on or before the date
`deletedAfter($date)`	`deleted_at`	Soft-deleted records deleted on or after the date

Every scope returns an Eloquent query builder, so it chains with additional ->where() constraints, ordering, and pagination just like a normal query:

use App\Models\AuditLog;

// Records written within a single day
$events = AuditLog::createdAfter('2026-07-01')
    ->createdBefore('2026-07-01 23:59:59')
    ->get();

// Events that occurred in the last week, most recent first
$events = AuditLog::occurredAfter(now()->subWeek())
    ->orderByDesc('occurred_at')
    ->paginate(25);

// Combine with any other constraint
$events = AuditLog::createdAfter('2026-01-01')
    ->where('event_type', 'okta.auth.login.error.invalid')
    ->count();

The created_at scopes always apply. occurred_at is only populated when you pass occurred_at to AuditLog::create(), so records logged without it are excluded from the occurred* scopes. The deleted* scopes call onlyTrashed() internally — they return only soft-deleted records, so there is no need to add withTrashed() yourself.

Querying by Relationship

Each audit log carries six polymorphic relationships — actor, parent, record, related, subject, and tenant — that morph on the fully-qualified class name stored in the paired *_model column. Because the model registers these as standard MorphTo relationships and requires no morph map, you can filter by them with Laravel's native query builder methods — no package-specific scopes needed. Throughout this section, AuditLog refers to your Eloquent model — either the base BoldlyGrow\AuditLog\Models\AuditLog or your own App\Models\AuditLog that extends it.

Matching a Related Model with `whereMorphedTo()`

whereMorphedTo() takes a relationship name plus either a model instance or a class-string, and resolves the underlying columns for you:

use App\Models\AuditLog;
use App\Models\Okta\User;

// Logs for ONE specific record — matches record_model = User::class AND record_id = $user->id
$events = AuditLog::whereMorphedTo('record', $user)->get();

// Logs for ANY record of a class — matches record_model = 'App\Models\Okta\User' (any id)
$events = AuditLog::whereMorphedTo('record', User::class)->get();

The same call works for every relationship — just swap the first argument:

$events = AuditLog::whereMorphedTo('actor', $user)->get();     // who performed the action
$events = AuditLog::whereMorphedTo('subject', $user)->get();   // who/what was impacted
$events = AuditLog::whereMorphedTo('parent', $model)->get();   // the parent record
$events = AuditLog::whereMorphedTo('record', $model)->get();   // the affected record
$events = AuditLog::whereMorphedTo('related', $model)->get();  // a related record
$events = AuditLog::whereMorphedTo('tenant', $org)->get();     // the owning organization/tenant

What you pass determines how the query is constrained:

Argument	Constrains	Meaning
A model instance (`$user`)	`_model` and* `*_id`	Records tied to this exact model
A class-string (`User::class`)	`*_model` only	Records tied to any instance of this class

Because every scope returns a query builder, these compose with the date range scopes and any other constraint, ordering, or pagination:

// Everything this actor did in the last 7 days, most recent first
$events = AuditLog::whereMorphedTo('actor', $user)
    ->occurredAfter(now()->subDays(7))
    ->orderByDesc('occurred_at')
    ->get();

// Actions against a specific tenant since the start of the year, paginated
$events = AuditLog::whereMorphedTo('tenant', $organization)
    ->createdAfter('2026-01-01')
    ->paginate(25);

whereNotMorphedTo() is available for the inverse.

Filtering by the Related Model's Attributes with `whereHasMorph()`

When you need a condition on the related record itself — not just its identity — use whereHasMorph(). Pass the type(s) to check as the second argument, since a MorphTo may point at several classes:

use App\Models\Okta\User;

// Logs whose subject is an active user
$events = AuditLog::whereHasMorph('subject', [User::class], function ($query) {
    $query->where('is_active', true);
})->get();

Example API Endpoints

The package ships copyable reference implementations of a read-only list + describe audit log API in the examples/ directory — in two flavors:

api-endpoints-no-dependency — a primitive listing (the model results, paginated) using pure Laravel/Eloquent; no extra packages.
api-endpoints-spatie-data-query — declarative filter[...] query parameters (including encrypted-field search) and a typed response DTO, using spatie/laravel-query-builder and spatie/laravel-data.

The Spatie variant exposes the *_type strings described above as query filters. They are reference stubs (not autoloaded) — copy them into your app and adapt; each folder's README covers install, setup, and authorization.

Adding Custom Fields

You will often need to store application-specific fields (for example a tenant, organization, or workspace ID) on your audit log records. There are two approaches.

Recommended: Metadata Flatten (no package changes)

Add the column(s) to the table with your own migration:

Schema::table('audit_logs', function (Blueprint $table) {
    $table->string('federation_organization_id')->nullable()->index();
});

Whitelist the key in config('audit-log.database.custom_fields'):

'database' => [
    'custom_fields' => [
        'federation_organization_id',
    ],
],

Add a relationship to your own App\Models\AuditLog model (if you created one extending the base model) if desired.

Pass the value inside metadata:

AuditLog::create(
    // ...
    database: true,
    metadata: [
        'federation_organization_id' => $organization->id,
    ],
    // ...
);

Whitelisted keys are flattened out of metadata into their matching columns. They also remain in the metadata JSON for the system log.

Advanced: First-Class Parameter

If you want a custom field as a first-class parameter of AuditLog::create() (rather than passed via metadata), the value must be added in each of these places within the package:

The create() method signature and docblock
The $log_context_keys grouping
The validate() rules
The $log_data array (for persistence)
The base model casts() (if a non-string cast is needed)
The migration

Skipping Log Creation

You can specify true/false booleans for the log and database parameters. By default, log is true and database is false. (transaction is retained as a deprecated alias for database.)

The parsed and formatted schema is always returned as an array.

`log`	`database`	Behavior
`true`	`false`	(Default) Log entry is created.
`true`	`true`	Log entry is created. Database row is persisted.
`false`	`true`	No log is created. Database row is persisted.
`false`	`false`	No log or database row is created. Used for schema parsing.

Response Schema

One of the benefits to this package is the formatted array with predictable keys.

In addition to (or instead of) writing a log or persisting to the database, every call returns a formatted array with all of the keys and their provided or default values. This is useful if you simply need an array that you will use for your own changelog or some other purpose. You can also disable log creation and use this like a data transfer object (DTO).

Simply define a variable to get the returned array.

use BoldlyGrow\AuditLog\AuditLog;

// Create a log entry with no returned array
AuditLog::create(
    // ...
    log: true
    // ...
);

// Define a variable with the returned array
$schema = AuditLog::create(
    // ...
    log: true
    // ...
);

// Append the return array to an existing array of records that are not created in system logs
foreach($records as $record) {
    // ...

    $changelog[] = AuditLog::create(
        // ...
        log: false
        // ...
    );
}

Example Response Array with No Configuration

use BoldlyGrow\AuditLog\AuditLog;

$event_ms = now();

$result = AuditLog::create(
    event_ms: $event_ms,
    event_type: "okta.api.post.success.ok",
    level: "info",
    message: "Success",
    metadata: [
        "okta_request_id" => "REDACTED",
        "rate_limit_remaining" => "199",
        "uri" => "users",
        "url" => "https://dev-12345678.okta.com/api/v1/users?activate=true"
    ],
    method: "BoldlyGrow\Okta\ApiClient::get"
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:51:10+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "level" => "info",
//     "message" => "Success",
//     "method" => "BoldlyGrow\Okta\ApiClient::get",
//     "actor_email" => null,
//     "actor_id" => null,
//     "actor_ip_addr" => null,
//     "actor_model" => null,
//     "actor_name" => null,
//     "actor_provider_id" => null,
//     "actor_session_id" => "…",
//     "actor_source" => "system",
//     "actor_type" => null,
//     "actor_username" => null,
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "count_records" => null,
//     "duration_ms" => null,
//     "duration_ms_per_record" => null,
//     "errors" => [],
//     "event_ms" => 4,
//     "event_ms_per_record" => null,
//     "job_batch" => null,
//     "job_id" => null,
//     "job_platform" => null,
//     "job_pipeline_id" => null,
//     "job_timestamp" => null,
//     "job_transaction_id" => null,
//     "metadata" => [
//       "okta_request_id" => "REDACTED",
//       "rate_limit_remaining" => "199",
//       "uri" => "users",
//       "url" => "https://dev-12345678.okta.com/api/v1/users?activate=true",
//     ],
//     "occurred_at" => null,
//     "parent_id" => null,
//     "parent_type" => null,
//     "parent_provider_id" => null,
//     "parent_reference_key" => null,
//     "parent_reference_value" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
//     "related_id" => null,
//     "related_type" => null,
//     "subject_id" => null,
//     "subject_type" => null,
//     "tenant_id" => null,
//     "tenant_type" => null,
// ]

The *_model parameters do not appear as separate keys in the returned array — they are folded into their paired *_type value. When a database row is persisted, both the *_model (fully-qualified class) and *_type (snake_case) columns are stored.

Specifying Keys in Response Array

There are a large number of parameter keys in the schema. To avoid having to use Laravel Collections transform methods with the result array, you can simply pass an array of keys to the dump_keys array that you want to be included.

use BoldlyGrow\AuditLog\AuditLog;

$result = AuditLog::create(
    // ...
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:53:35+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "message" => "Success",
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
// ]

Specifying Custom Static Strings in Response Array

If you need to add custom static strings to your array, they can be specified in the dump_strings array. Strings are returned at the end of the array.

use BoldlyGrow\AuditLog\AuditLog;

$result = AuditLog::create(
    // ...
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
    dump_strings: [
        'custom_key' => 'my_value',
        'another_key' => 'my_value',
    ],
    // ...
);

dd($result);

// [
//     "datetime" => "2024-03-02T18:54:55+00:00",
//     "event_type" => "okta.api.post.success.ok",
//     "message" => "Success",
//     "attribute_key" => null,
//     "attribute_value_old" => null,
//     "attribute_value_new" => null,
//     "record_id" => null,
//     "record_type" => null,
//     "record_provider_id" => null,
//     "record_reference_key" => null,
//     "record_reference_value" => null,
//     "custom_key" => "my_value",
//     "another_key" => "my_value",
// ]

Custom Datetime Format in Response Array

The datetime is always returned in the first key (table column) of the array. You can customize the format using a string of supported PHP datetime format characters. By default, we use c for the ISO 8601 format (YYYY-MM-DDTHH:II:SS+00:00). You may want to simplify this with Y-m-d or Y-m-d H:i.

use BoldlyGrow\AuditLog\AuditLog;

$result = AuditLog::create(
    // ...
    dump_date: 'c',
    dump_keys: [
        'event_type',
        'message',
        'attribute_key',
        'attribute_value_old',
        'attribute_value_new',
        'record_id',
        'record_type',
        'record_provider_id',
        'record_reference_key',
        'record_reference_value'
    ],
    dump_strings: [
        'custom_key' => 'my_value',
        'another_key' => 'my_value',
    ],
    // ...
);

dd($result);

// [
//     "datetime" => "2024-03-02",
//     "event_type" => "okta.api.post.success.ok",
//     // ....
// ]

Standardized Configurations for Response Array

Reminder: You need to publish the configuration file for it to appear in config/audit-log.php or it will use the default one in the vendor/boldlygrow/audit-log directory that cannot be modified.

It can be difficult to manage your simplified schemas throughout your code base.

You can define standardized simplified schemas in the config/audit-log.php file for each of your use cases. The default key is a placeholder that can be customized and you can add additional arrays for each type of resource if needed (ex. okta_user).

After a schema is defined, simply set the dump_config key to the same key that was defined in config/audit-log.php.

use BoldlyGrow\AuditLog\AuditLog;

$result = AuditLog::create(
    // ...
    dump_config: 'okta_user'
    // ...
);

// config/audit-log.php

return [
    'dump' => [
        'default' => [
            'date' => 'c',
            'strings' => [
                'custom_key' => 'my_value'
            ],
            'keys' => [
                'event_type',
                'message',
                'record_id',
                'record_type',
                'record_provider_id',
                'record_reference_key',
                'record_reference_value'
            ],
        ],
        'okta_user' => [
            'date' => 'c',
            'strings' => [
                'custom_key' => 'my_value'
            ],
            'keys' => [
                'event_type',
                'message',
                'attribute_key',
                'attribute_value_old',
                'attribute_value_new',
                'record_id',
                'record_type',
                'record_provider_id',
                'record_reference_key',
                'record_reference_value'
            ]
        ]
    ]
];

Real World Example for Response Arrays

use BoldlyGrow\AuditLog\AuditLog;

$result = AuditLog::create(
    attribute_key: $attribute,
    attribute_value_old: $manifest_record[$attribute],
    attribute_value_new: $api_record[$attribute],
    duration_ms: $this->duration_ms,
    event_type: $this->event_type . '.datadumper.manifest.attribute.changed.' . $attribute,
    level: 'info',
    log: true,
    message: Str::title($attribute) . ' Attribute Value Changed',
    method: __METHOD__,
    record_provider_id: $manifest_record['provider_id'],
    record_reference_key: $this->reference_key,
    record_reference_value: $manifest_record[$this->reference_key] ?? null,
    database: true
);

dd($result);

// [
//     'datetime' => 'YYYY-MM-DDTHH:II:SS+00:00',
//     'event_type' => 'okta.user.sync.datadumper.manifest.attribute.changed.manager',
//     'message' => 'Manager Attribute Value Changed',
//     'attribute_key' => 'manager',
//     'attribute_value_old' => 'klibby',
//     'attribute_value_new' => 'dmurphy',
//     'record_id' => null,
//     'record_type' => 'okta_user',
//     'record_provider_id' => '00u1b2c3d4e5f6g7h8i9',
//     'record_reference_key' => 'handle',
//     'record_reference_value' => 'jpardella'
//     'custom_key' => 'my_value',
// ]

boldlygrow / audit-log

Maintainers

Package info

Statistics

Security

README

Problem Statement

Feature Comparison

Audit Record Completeness & Scope

Issue Tracking and Bug Reports

Contributing

Maintainers

Contributor Credit

Installation

Requirements

Upgrade Guide

Add Composer Package

Publish the config and migration

Bundled Examples

Usage Examples

Basic Usage

Comprehensive Usage

Example Output

Log Parameter Definitions

Advanced Usage

Actor Metadata

Mapping Custom User Attributes

Actor IP Address Behind a Proxy or CDN

Actor Source

Disabling Actor Metadata

Background Job Log Entry

Model References and Automatic Types

Simple String Searches with *_type

Database Persistence

Encryption at Rest

Immutability

Searching Encrypted Fields

Available Scopes

String Column Searches

Exact String Match

Partial String Match

Starts-With and Ends-With

Array Column Searches

Search the Entire Array

Match a Specific Array Key

Listing Array Keys

Chaining with Other Constraints

Case Sensitivity and Normalization

Caching and Fresh Data

Performance Considerations

Date Range Scopes

Querying by Relationship

Matching a Related Model with whereMorphedTo()

Filtering by the Related Model's Attributes with whereHasMorph()

Example API Endpoints

Adding Custom Fields

Recommended: Metadata Flatten (no package changes)

Advanced: First-Class Parameter

Skipping Log Creation

Response Schema

Example Response Array with No Configuration

Specifying Keys in Response Array

Specifying Custom Static Strings in Response Array

Custom Datetime Format in Response Array

Standardized Configurations for Response Array

Real World Example for Response Arrays

Simple String Searches with `*_type`

Matching a Related Model with `whereMorphedTo()`

Filtering by the Related Model's Attributes with `whereHasMorph()`