Download the PHP package ayup-creative/event-log without Composer

Laravel Event Logger

A high-performance, structured, asynchronous, and relational event logging package for Laravel. Designed for auditability, traceability, and cross-service correlation without storing sensitive payload data.

Core Design Goals

• Log Facts, Not State: Records what happened (the event), not the resulting state of the model.
• Privacy by Design: Avoids storing sensitive data, JSON blobs, or PII. It links to models instead of copying their data.
• Async-First: All event persistence is handled via Laravel's queue system to ensure zero impact on request performance.
• Exactly-Once Delivery: Built-in idempotency ensures that retried queue jobs do not create duplicate event records.
• Relational Graph: Supports a primary "subject" and multiple "related" models per event, allowing for complex traceability.
• Audit Ready: Captures causers (users, system, jobs), correlation IDs, and transaction IDs.
• OpenTelemetry Ready: Seamlessly integrates with distributed tracing systems.

Installation

You can install the package via composer:

The service provider will automatically register itself.

You should publish and run the migrations:

You can optionally publish the config file:

Versions

The package follows semantic versioning. Major version changes indicate breaking changes, while minor and patch versions introduce new features and bug fixes, respectively.

Configuration

The published config file config/event-log.php allows you to customize the models used by the package:

Usage

1. Manual Domain Events

Use the log_event helper to record significant domain events asynchronously. It is recommended to use the namespaced log_event() function.

Event Enums

The log_event helper also supports BackedEnum for event names, providing better type safety and IDE autocompletion.

• Event Name: A human-readable dot-notation string or a BackedEnum.
  • Subject: The primary Eloquent model the event is about.
  • Related: (Optional) An array of additional Eloquent models linked to this event.
  • Causer Type: (Optional) Explicitly set the type of actor ('user', 'system', 'worker', 'cron').
  • Metadata: (Optional) Key-value pairs of additional context for the event.

2. Automatic Lifecycle Logging

Add the LogsEvents trait to any Eloquent model to automatically log lifecycle events (created, updated, deleted, restored).

Customizing Trait Behavior

You can override these methods in your model:

3. Custom Actor & Causer Resolution

By default, the package uses auth()->id() to identify the current user and determines if the action was triggered by a 'user' (web request) or 'worker' (CLI).

You can customize this behavior using the EventLog Facade in your AppServiceProvider:

4. Grouping Events with Transactions

Use the WithEventTransaction wrapper to group multiple events occurring within a single database transaction. This assigns a shared transaction_id to all events logged inside the closure.

5. Correlation IDs & Middleware

Correlation IDs allow you to trace a logical action across multiple services and background jobs.

Global Middleware

Add the EventCorrelationMiddleware to your global or web/api middleware stack to automatically capture or generate a correlation ID for every request.

Propagation via HTTP Client

The package adds a macro to the Laravel HTTP client to easily propagate the correlation ID:

6. Human-Readable Event Formatting

You can map internal dot-notation event names (e.g., user.created) to human-readable strings (e.g., A new user was created). This is useful for displaying a timeline of events to end-users.

Using the Facade (Closure-based)

Register a formatter in your AppServiceProvider:

Using a Formatter Class (Cache-friendly)

For better performance and to keep your AppServiceProvider clean, you can use a dedicated class. This is also required if you want to use php artisan config:cache, as closures cannot be serialized.

1. Create your formatter class:

2. Register it in config/event-log.php:

Accessing the Formatted Description

Once a formatter is registered, you can access the human-readable string via the description attribute on the EventLog model:

Querying Events

You can retrieve a unified timeline of events for any model using the EventLog Facade. This returns events where the model is either the subject or a related model.

Causer Labels

The EventLog model provides a causerLabel() helper to identify the actor:

• user: Returns the user's name (if authenticated).
• system: Internal system action.
• job: Action triggered by a background job.
• webhook: Action triggered by an external service.

Metadata Helper

The meta attribute provides a shorthand for the metadata collection, allowing you to access values directly as properties:

Alternatively, you can access the full metadata relationship, which returns an Eloquent collection of metadata models.

Advanced Features

Idempotency

To prevent duplicate logs during queue retries, the package generates a deterministic idempotency_key for every event. If a job runs twice, the database uniqueness constraint will silently prevent the second record from being created.

OpenTelemetry Bridge

If the open-telemetry/opentelemetry package is installed, the logger will automatically create spans for each event. The correlation_id is used to maintain trace context.

Testing

The package includes a comprehensive test suite. To run the tests:

Or manually:

License

The MIT License (MIT).