PHPackages glesys/butler-audit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. glesys/butler-audit ActiveLibrary[Utility & Helpers](/categories/utility) glesys/butler-audit =================== Glesys Butler Audit package. v0.8.1(1y ago)121.7k—0%1MITPHPPHP ^8.2CI passing Since Nov 6Pushed 5mo ago11 watchersCompare [ Source](https://github.com/glesys/butler-audit)[ Packagist](https://packagist.org/packages/glesys/butler-audit)[ RSS](/packages/glesys-butler-audit/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (12)Versions (21)Used By (1) 🚧 **Not ready for production.** Butler Audit ============ [](#butler-audit) Laravel package for sending audit events to a remote endpoint. Example ------- [](#example) ``` audit($user)->subscribed(['months' => 12]); ``` ``` POST /log HTTP/1.1 Host: example.local Accept: application/json Content-Type: application/json Authorization: Bearer secret { "correlationId": "d9afea6a-14ed-4777-ae2f-a4d8baf4d5b7", "correlationTrail": "Mv9Jd6VM:GaIngT2j", "entities": [ { "type": "user", "identifier": 1 } ], "event": "user.subscribed", "eventContext": [ { "key": "months", "value": 12 } ], "initiator": "service-a", "occurredAt": 1600432185 } ``` Getting Started --------------- [](#getting-started) ``` composer require glesys/butler-audit php artisan vendor:publish --provider="Butler\Audit\ServiceProvider" --tag=config ``` Configure --------- [](#configure) ``` BUTLER_AUDIT_DRIVER=http BUTLER_AUDIT_URL=https://example.local/log BUTLER_AUDIT_TOKEN=secret ``` Make sure you have a [queue](https://laravel.com/docs/master/queues) configured to speed up your application. ### Log driver [](#log-driver) When developing you can use the log driver to prevent http requests being sent. ``` BUTLER_AUDIT_DRIVER=log ``` ### Initiator resolver [](#initiator-resolver) A default "initiator resolver" is registered in the [ServiceProvider](src/ServiceProvider.php). Your application can have its own resolver to avoid setting initiator manually for every audit call. You can still use `initiator()` and `initiatorContext()` to override the values set by the resolver. ``` Auditor::initiatorResolver(fn () => [ auth()->id(), [ 'ip' => request()->ip(), 'userAgent' => request()->userAgent(), ] ]); ``` You can disable the default resolver by setting `butler.audit.default_initiator_resolver` to `false`. Auditable --------- [](#auditable) You can pass "Auditables" to the helper method. ``` class Car extends Fluent implements Auditable { public function auditorType(): string { return $this->type; } public function auditorIdentifier() { return $this->id; } } $car = new Car(['id' => 1, 'type' => 'volvo']); audit($car)->started(); // equivalent to audit(['volvo', 1])->started(); ``` ### Trait for Eloquent models [](#trait-for-eloquent-models) For convenience there is a `IsAuditable` trait that can be used by eloquent models. ``` class User extends Model implements Auditable { use IsAuditable; } $user = User::find(1); audit($user)->subscribed(); // equivalent to audit(['user', 1])->subscribed(); ``` X-Correlation-ID ---------------- [](#x-correlation-id) We use "X-Correlation-ID" header to "relate" audits. A "X-Correlation-Trail" header is also used to figure out the order of events without relying on the events `occured_at`, see the example json below. ### Http client macro [](#http-client-macro) Use the "withCorrelation" macro to add the "X-Correlation-ID" header when sending requests with the Http client. In the example below, all "audits" will have the same correlation-id. ``` // Service A audit($user)->signedUp(); Http::withCorrelation()->post('https://service-b.example/welcome-email', $user); // Service B audit($user)->welcomed(); Http::withCorrelation()->post('https://service-c.example/notify-staff'); // Service C audit($employee)->notified(); ``` The requests sent to your configured `BUTLER_AUDIT_URL` will look something like: ``` { "initiator": "api", "event": "user.signedUp", "correlationId": "92a55a99-82c1-4129-a587-96006f6aac82", "correlationTrail": null } { "initiator": "service-a", "event": "user.welcomed", "correlationId": "92a55a99-82c1-4129-a587-96006f6aac82", "correlationTrail": "Mv9Jd6VM" } { "initiator": "service-b", "event": "employee.notified", "correlationId": "92a55a99-82c1-4129-a587-96006f6aac82", "correlationTrail": "Mv9Jd6VM:GaIngT2j" } ``` ### Queued jobs [](#queued-jobs) The trait `WithCorrelation` can be used on queable jobs that needs the same correlation id as the request. #### How it works [](#how-it-works) 1. A job using the `WithCorrelation` trait is dispatched to the queue. 2. Our `Dispatcher` will set a `correlationId` property on the job. 3. The job is handled by a worker. 4. The middleware `SetCorrelation` will tell `Auditor` to use the correlation id from the job. Extending the dispatcher can be disabled by setting `butler.audit.extend_bus_dispatcher` to `false`. Auditor Fake ------------ [](#auditor-fake) Instead of [faking the queue](https://laravel.com/docs/master/mocking#queue-fake) in your tests and e.g. `Queue::assertPushed(function (AuditJob) {})` you can fake requests, see example below. ``` public function test_welcome_user() { Auditor::fake(); // Assert that nothing was logged... Auditor::nothingLogged(); // Perform user welcoming... // Assert 1 event was logged... Auditor::assertLoggedCount(1); // Assert a event was logged... Auditor::assertLogged('user.welcomed'); // Assert a event with context, initiator and entity was logged... Auditor::assertLogged('user.welcomed', fn (AuditData $audit) => $audit->initiator === 'service-a' && $audit->hasEntity('user', 1) && $audit->hasEventContext('months', 12) ); } ``` Testing ------- [](#testing) ``` vendor/bin/phpunit vendor/bin/pint --test ``` How To Contribute ----------------- [](#how-to-contribute) Development happens at GitHub; any typical workflow using Pull Requests are welcome. In the same spirit, we use the GitHub issue tracker for all reports (regardless of the nature of the report, feature request, bugs, etc.). All changes are supposed to be covered by unit tests, if testing is impossible or very unpractical that warrants a discussion in the comments section of the pull request. ### Code standard [](#code-standard) As the library is intended for use in Laravel applications we encourage code standard to follow [upstream Laravel practices](https://laravel.com/docs/master/contributions#coding-style) - in short that would mean [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) and [PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md). ### Health Score 46 — FairBetter than 93% of packages Maintenance61 Regular maintenance activity Popularity28 Limited adoption so far Community19 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 77.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~117 days Recently: every ~284 days Total 15 Last Release 371d ago PHP version history (6 changes)v0.1.0PHP ^7.4 v0.1.3PHP ^7.4|^8.0 v0.4.0PHP ^8.0 v0.6.0PHP ^8.0.2 v0.7.0PHP ^8.1 v0.8.0PHP ^8.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/708205?v=4)[Christoffer Andersson](/maintainers/wecc)[@wecc](https://github.com/wecc) ![](https://avatars.githubusercontent.com/u/2156132?v=4)[Markus Lilienberg](/maintainers/ttrig)[@ttrig](https://github.com/ttrig) --- Top Contributors [![ttrig](https://avatars.githubusercontent.com/u/2156132?v=4)](https://github.com/ttrig "ttrig (37 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![wecc](https://avatars.githubusercontent.com/u/708205?v=4)](https://github.com/wecc "wecc (3 commits)")[![brother](https://avatars.githubusercontent.com/u/243351?v=4)](https://github.com/brother "brother (2 commits)")[![emil-nasso](https://avatars.githubusercontent.com/u/1119706?v=4)](https://github.com/emil-nasso "emil-nasso (1 commits)") --- Tags auditlaravel ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/glesys-butler-audit/health.svg) ``` [![Health](https://phpackages.com/badges/glesys-butler-audit/health.svg)](https://phpackages.com/packages/glesys-butler-audit) ``` ### Alternatives [laravel/scout Laravel Scout provides a driver based solution to searching your Eloquent models. 1.7k49.4M479](/packages/laravel-scout)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[flarum/core Delightfully simple forum software. 211.3M1.9k](/packages/flarum-core)[spatie/laravel-enum Laravel Enum support 3655.4M31](/packages/spatie-laravel-enum)[psalm/plugin-laravel Psalm plugin for Laravel 3274.9M308](/packages/psalm-plugin-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)