ipsocode / hypervel-auditing

v0.1.2 2026-10-01 14:01 UTC

Requires

• php: ^8.4
• ext-json: *
• hypervel/contracts: ^0.4
• hypervel/database: ^0.4
• hypervel/reflection: ^0.4
• hypervel/support: ^0.4

Requires (Dev)

• brianium/paratest: ^7.24
• fakerphp/faker: ^1.24
• friendsofphp/php-cs-fixer: ^3.57.2
• hypervel/components: 0.4.x-dev
• hypervel/testbench: ^0.4
• mockery/mockery: ^1.6
• phpstan/phpstan: ^2.2.15
• phpunit/phpunit: ^13.0.3
• symfony/yaml: ^8.0.12

MIT

• Gregory Daus

• Audit
• auditing
• eloquent
• coroutine
• hypervel

Published on Packagist.org on 2026-10-01 14:08 UTC

README

Audit changes to your Eloquent models on Hypervel.

Warning

Development only — do not use this package in production until Hypervel 0.4 is released.

It is built for Hypervel 0.4, which has no release yet: 0.4 exists only as the 0.4.x-dev branch of hypervel/components, and this package is developed and tested against that moving branch. Until 0.4 ships, anything here can change without a deprecation period — the API, the configuration and the database schema included. Use it to evaluate or to build against Hypervel 0.4, and pin the version you tested.

$article->update(['title' => 'Revised title']);

$article->audits()->latest()->first()->getModified();
// ['title' => ['old' => 'Draft title', 'new' => 'Revised title']]

What this is

A port of owen-it/laravel-auditing to Hypervel — the same class topology (an Auditable trait, an Auditor manager, resolvers, redactors, encoders, AuditableTransitionException), so upstream's documentation and mental model mostly carry over.

It is not a drop-in replacement. Two things differ enough to break an assumption before you write a line of code:

1. There are no old_values / new_values columns. Audits are stored normalized across two tables — see Schema.
2. Auditing is coroutine-aware. On a long-lived Swoole worker, "process state" is shared by every concurrent request. Anything you plug in has rules to honour — see Coroutines.

Differences from owen-it/laravel-auditing lists the rest.

Requirements

• PHP 8.4 or newer (CI runs 8.4 and 8.5)
• Hypervel 0.4, which today means hypervel/components at 0.4.x-dev. The package requires hypervel/contracts, hypervel/support, hypervel/database and hypervel/reflection ^0.4; hypervel/components provides all four.

Installation

The package is not on Packagist, so add this repository to your application's Composer repositories first:

composer config repositories.hypervel-auditing vcs https://github.com/ipsocode/hypervel-auditing
composer require ipsocode/hypervel-auditing
php artisan auditing:install
php artisan migrate

Hypervel 0.4 is only available as a dev branch, so your application's composer.json must already allow it: "minimum-stability": "dev" together with "prefer-stable": true. Tags are not re-tested as 0.4.x-dev moves on, and neither is main between changes: each change is tested against the 0.4.x-dev of its day before it merges. To pick up changes as they land, require ipsocode/hypervel-auditing:dev-main instead. Each release's notes, breaking changes first, are on the Releases page.

auditing:install picks the two table names and writes them to config/auditing.php; Installation explains the prompts, the non-interactive options, adopting existing tables and the publish tags.

Then make a model auditable:

use Hypervel\Database\Eloquent\Model;
use Ipsocode\Auditing\Auditable;
use Ipsocode\Auditing\Contracts\Auditable as AuditableContract;

class Article extends Model implements AuditableContract
{
    use Auditable;
}

Both parts are required: the trait supplies the behaviour, the interface is what the Auditor and the driver type-hint against.

Usage at a glance

use Ipsocode\Auditing\Facades\Auditor;

// Creates, updates, deletes and restores are audited by default.
$article->update(['title' => 'Revised title']);
$article->audits()->latest()->first()->getModified();

// Skip auditing Article models for one callback, on the current coroutine only.
Article::withoutAuditing(fn () => $article->update(['title' => 'Quietly']));

// Record an event that has no column behind it.
Auditor::on($article)->as('exported')->with(['format' => 'pdf'])->log();

// Stamp every audit written inside the callback with the same batch_uuid.
Auditor::withinBatch(function () use ($article, $author) {
    $article->save();
    $author->save();
});

php artisan auditing:prune   # delete audits past the retention period (365 days by default)

In a console process (an Artisan command, a seeder, a queue worker, a test run) model events are audited only once auditing.console is true; see Recording.

The examples above are covered in full in Reading audits, Disabling auditing, Manual audits, Batches and Retention.

Documentation

Page	Covers
Installation	Table names, adopting existing tables, publishing the config and migrations
Schema	The audits and audit_details tables and how values are stored
Recording	Which events and attributes are audited; per-model properties and hooks
Attribute modifiers	Redactors and encoders for sensitive attributes
Reading audits	getModified(), getMetadata(), tags and the audit's relations
Disabling auditing	withoutAuditing(), the worker-wide switches, auditing.enabled and auditing.console
Relationship auditing	Audited attach, detach and sync on many-to-many relations
Manual audits	Auditor::on() for events with no column behind them
Batches	Grouping the audits of one operation under a batch_uuid
Retention	The per-row threshold and auditing:prune
Queued auditing	Writing model audits through a queue connection, and what crosses it
Events	The events dispatched around an audit, and vetoing one
Drivers	The audit_details driver and writing your own
Resolvers	How the causer, url, ip_address and user_agent are filled; custom resolvers
Audit model	Extending or replacing the Audit model
Transitions	Filling a model with an audit's old or new values
Testing	Recording audits in tests, the state reset after each test, and asserting on audits
Coroutines	The coroutine-safety rules the package follows, and that extensions must follow
Configuration	Every config/auditing.php key and its default

Differences from owen-it/laravel-auditing

	owen-it/laravel-auditing	This package
Storage	old_values / new_values JSON columns on audits	Normalized: audits + one audit_details row per field
Drivers	Database driver	audit_details driver; no Database driver
old_values / new_values	Columns	Accessors, built from the detail rows
auditing:install	Publishes the config	Chooses and persists the table names, can adopt existing tables
Driver generator	make:audit-driver	None
Retention	Threshold only	Threshold plus auditing:prune
Batches	None	Auditor::withinBatch(), batch_uuid column
Manual audits	Hand-assembled AuditCustom dispatch	Auditor::on(...)->as(...)->log()
withoutAuditing()	Static flag	Coroutine-scoped
Table names	Fixed	auditing.tables.*

Contributing

The development setup, the checks CI runs, the coroutine-safety rules every change is held to, and how releases are cut are in CONTRIBUTING.md. Report security issues privately, as described in SECURITY.md, rather than in a public issue.

Credits

A port of owen-it/laravel-auditing by Antério Vieira, Quetzy Garcia, Raphael França and its contributors, to Hypervel.

License

MIT. See LICENSE, which carries the copyright notices of this package and of owen-it/laravel-auditing.