PHPackages popphp/pop-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. popphp/pop-audit ActiveLibrary[Utility & Helpers](/categories/utility) popphp/pop-audit ================ Pop Audit Component for Pop PHP Framework 2.0.3(6mo ago)45.0k↓50%1BSD-3-ClausePHPPHP >=8.3.0CI passing Since Aug 25Pushed 6mo ago1 watchersCompare [ Source](https://github.com/popphp/pop-audit)[ Packagist](https://packagist.org/packages/popphp/pop-audit)[ Docs](http://github.com/popphp/pop-audit)[ RSS](/packages/popphp-pop-audit/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (20)Used By (1) pop-audit ========= [](#pop-audit) [![Build Status](https://github.com/popphp/pop-audit/workflows/phpunit/badge.svg)](https://github.com/popphp/pop-audit/actions)[![Coverage Status](https://camo.githubusercontent.com/c33959224060d3841cbc98473022e4c1a5a862709d59fc55ec38ac70cb7bdb5d/687474703a2f2f63632e706f707068702e6f72672f636f7665726167652e7068703f636f6d703d706f702d6175646974)](http://cc.popphp.org/pop-audit/) [![Join the chat at https://discord.gg/TZjgT74U7E](https://camo.githubusercontent.com/acad7b0eeb78b78d08ffd2b85681ab243436388b5f86f8bcb956a69246e53739/68747470733a2f2f6d656469612e706f707068702e6f72672f696d672f646973636f72642e737667)](https://discord.gg/TZjgT74U7E) - [Overview](#overview) - [Install](#install) - [Quickstart](#quickstart) - [Storing Changes](#storing-changes) - [Retrieving Changes](#retrieving-changes) - [Diffing](#diffing) - [Using Files](#using-files) - [Using a Database](#using-a-database) - [Using HTTP](#using-http) Overview -------- [](#overview) Pop Audit is an auditing component of the Pop PHP Framework. It allows you to track and recall changes in model states, which is useful for rolling back mistakes or recovering lost data. It provides different adapters to achieve this, all of which are interchangeable using the same interface: - File - Database - HTTP `pop-audit` is a component of the [Pop PHP Framework](http://www.popphp.org/). [Top](#pop-audit) Install ------- [](#install) Install `pop-audit` using Composer. ``` composer require popphp/pop-audit ``` Or, require it in your composer.json file ``` "require": { "popphp/pop-audit" : "^2.0.3" } ``` [Top](#pop-audit) Quickstart ---------- [](#quickstart) With the audit component, you can store model state data changes and recall them at a later date. ### Storing Changes [](#storing-changes) To store the model data, there are two required data points - the model name and model ID. After that, optional data points such as user data or the domain can be stored. First we create the auditor and set the data points: ``` use Pop\Audit\Auditor; use Pop\Audit\Adapter\File; $auditor = new Auditor(new File(__DIR__ . '/tmp')); // Folder passed to the File adapter $auditor->setModel('MyApp\Model\User', 1001); // Model name and model ID (required) $auditor->setUser('testuser', 101); // Username/ID that made the change (optional) $auditor->setDomain('users.localhost'); // Domain (optional) ``` Then, we look at the changed model data. In this example, the model state contains 4 data points, 2 of which have changed: `username` and `phone`. Once passed to the auditor's `send()` method, it will "diff" the two states and record the differences, as well as snapshot of the final changed state: ``` $old = [ 'id' => 1, 'username' => 'admin', 'email' => 'test@test.com', 'phone' => '504-555-5555' ]; $new = [ 'id' => 1, 'username' => 'admin2', 'email' => 'test@test.com', 'phone' => '504-555-6666' ]; $auditor->send($old, $new); ``` [Top](#pop-audit) ### Retrieving Changes [](#retrieving-changes) Interacting with the auditor's adapter, the previously stored model states can be retrieved: **List all stored states** ``` var_dump($auditor->adapter()->getStates()); ``` **List stored states for a particular model and model ID** ``` var_dump($auditor->adapter()->getStateByModel('MyApp\Model\User', 1001)); ``` Other methods are available to help refine your search for previous states: - `getStateById()` - `getStateByTimestamp()` - `getStateByDate()` The state structure will look like: ``` Array ( [user_id] => 101 [username] => testuser [domain] => users.localhost [route] => [method] => [model] => MyApp\Model\User [model_id] => 1001 [action] => updated [old] => Array ( [username] => admin [phone] => 504-555-5555 ) [new] => Array ( [username] => admin2 [phone] => 504-555-6666 ) [state] => Array ( [id] => 1 [username] => admin2 [email] => test@test.com [phone] => 504-555-6666 ) [metadata] => Array ( ) [timestamp] => 2023-10-29 16:05:53 ) ``` The storing of the full state is on by default, can be turned off by passing a `false` boolean to the `send()` method: ``` $auditor->send($old, $new, false); ``` [Top](#pop-audit) Diffing ------- [](#diffing) In the above examples, the `pop-audit` component automatically handles "diffing" for you. If you have another resource that evaluates the differences, you can pass those directly into the auditor as well: ``` use Pop\Audit\Auditor; use Pop\Audit\Adapter\File; $old = ['username' => 'admin']; $new = ['username' => 'admin2']; $state = [ 'id' => 1, 'username' => 'admin2', 'email' => 'test@test.com', 'phone' => '504-555-5555' ] $auditor = new Auditor(new File(__DIR__ . '/tmp')); $auditor->setModel('MyApp\Model\User', 1001); $auditor->setUser('testuser', 101); $auditor->setDomain('users.localhost'); $auditor->setDiff($old, $new); $auditor->setStateData($state); // optional if you want to record the final changed state $auditor->send(); ``` An example of this is the `Pop\Db\Record` class from the `pop-db` component. It automatically tracks the "dirty" values that have been changed while working with a record object. You can then used the `getDirty()`method of the `Pop\Db\Record` class to return an array with the keys `old` and `new` and pass them off to the auditor. [Top](#pop-audit) Using Files ----------- [](#using-files) With the file adapter, you set the folder you want to save the audit record to, and save the model state changes like this: ``` use Pop\Audit\Auditor; use Pop\Audit\Adapter\File; $auditor = new Auditor(new File(__DIR__ . '/tmp')); // Folder passed to the File adapter $auditor->setModel('MyApp\Model\User', 1001); // Model name and model ID (required) $auditor->setUser('testuser', 101); // Username/ID that made the change (optional) $auditor->setDomain('users.localhost'); // Domain (optional) $old = [ 'id' => 1, 'username' => 'admin', 'email' => 'test@test.com', 'phone' => '504-555-5555' ]; $new = [ 'id' => 1, 'username' => 'admin2', 'email' => 'test@test.com', 'phone' => '504-555-6666' ]; $logFile = $auditor->send($old, $new); ``` In this case, the variable `$logFile` would contain the name of the audit log file, for example `pop-audit-aed112d5d6de258762c03aa597a47f9b-653ec767ee591-1698613095.log` in case it needs to be referenced again. That file will contain the JSON-encoded data that tracks the difference between the model states, as well as a snapshot of the full state (if provided): ``` { "user_id": 101, "username": "testuser", "domain": "users.localhost", "model": "MyApp\\Model\\User", "model_id": 1001, "action": "updated", "old": { "username": "admin" }, "new": { "username": "admin2" }, "state": { "id": 1, "username": "admin2", "email": "test@test.com", "phone": "504-555-6666" }, "timestamp": "2023-08-23 16:56:36" } ``` [Top](#pop-audit) Using a Database ---------------- [](#using-a-database) Using a database connection requires the use of the `pop-db` component and a database table class that extends the `Pop\Db\Record` class. Consider a database and table class set up in your application like this: ``` class AuditLog extends \Pop\Db\Record {} AuditLog::setDb(\Pop\Db\Db::mysqlConnect([ 'database' => 'MY_DATABASE', 'username' => 'DB_USER', 'password' => 'DB_PASS' ])); ``` Then you can use the table adapter like this: ``` use Pop\Audit\Auditor; use Pop\Audit\Adapter\Table; $old = [ "id" => 1, 'username' => 'admin', 'email' => 'test@test.com' ]; $new = [ "id" => 1, 'username' => 'admin2', 'email' => 'test@test.com' ]; $auditor = new Auditor(new Table('AuditLog')); $auditor->setModel('MyApp\Model\User', 1001); $auditor->setUser('testuser', 101); $auditor->setDomain('users.localhost'); $row = $auditor->send($old, $new); ``` If needed, the variable `$row` contains the newly created record in the audit table. [Top](#pop-audit) Using HTTP ---------- [](#using-http) You can also send your audit data to an HTTP service like this: ``` use Pop\Http\Client; use Pop\Http\Auth; use Pop\Audit\Auditor; use Pop\Audit\Adapter\Http; $old = [ "id" => 1, 'username' => 'admin', 'email' => 'test@test.com' ]; $new = [ "id" => 1, 'username' => 'admin2', 'email' => 'test@test.com' ]; $client = new Client( 'http://audit.localhost', Auth::createBearer('AUTH_TOKEN'), ['method' => 'POST'] ); $auditor = new Auditor(new Http($stream)); $auditor->setModel('MyApp\Model\User', 1001); $auditor->setUser('testuser', 101); $auditor->setDomain('users.localhost'); $response = $auditor->send($old, $new); ``` If needed, the variable `$response` contains the HTTP response returned by the HTTP request. [Top](#pop-audit) ### Health Score 52 — FairBetter than 96% of packages Maintenance67 Regular maintenance activity Popularity26 Limited adoption so far Community9 Small or concentrated contributor base Maturity86 Battle-tested with a long release history Bus Factor1 Top contributor holds 100% 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 ~187 days Total 15 Last Release 196d ago Major Versions 1.4.0 → 2.0.02023-12-18 PHP version history (7 changes)1.0.0PHP >=7.0.0 1.1.3PHP >=7.1.0 1.3.0PHP >=7.3.0 1.3.1PHP >=7.4.0 2.0.0PHP >=8.1.0 2.0.1PHP >=8.2.0 2.0.3PHP >=8.3.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/c19dee900e9e20039c723cc403f76b5c22ac2dddb3f86773ae64fb082d4949e2?d=identicon)[nicksagona](/maintainers/nicksagona) --- Top Contributors [![nicksagona](https://avatars.githubusercontent.com/u/898670?v=4)](https://github.com/nicksagona "nicksagona (75 commits)") --- Tags phpAuditauditingpoppop phpapplication auditingphp auditphp auditing ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/popphp-pop-audit/health.svg) ``` [![Health](https://phpackages.com/badges/popphp-pop-audit/health.svg)](https://phpackages.com/packages/popphp-pop-audit) ``` ### Alternatives [tapp/filament-auditing Filament Laravel Auditing plugin. 113379.4k2](/packages/tapp-filament-auditing)[popphp/popphp-framework The Pop PHP Framework - Full Installation 686.5k1](/packages/popphp-popphp-framework)[popphp/popphp Pop PHP Framework, a lightweight, robust PHP framework 5713.5k9](/packages/popphp-popphp)[popphp/pop-db Pop Db Component for Pop PHP Framework 1814.6k11](/packages/popphp-pop-db)[popphp/pop-pdf PHP PDF library for generating and importing PDF documents. A component of the Pop PHP Framework 207.8k1](/packages/popphp-pop-pdf)[popphp/pop-http Pop Http Component for Pop PHP Framework 1018.5k13](/packages/popphp-pop-http) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)