https://github.com/utopia-php/audit
Lite & fast micro PHP audit log library that is **easy to use**.
https://github.com/utopia-php/audit
hacktoberfest php
Last synced: 12 days ago
JSON representation
Lite & fast micro PHP audit log library that is **easy to use**.
- Host: GitHub
- URL: https://github.com/utopia-php/audit
- Owner: utopia-php
- License: mit
- Created: 2019-12-28T19:39:05.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2026-02-01T08:14:10.000Z (13 days ago)
- Last Synced: 2026-02-01T17:09:26.365Z (13 days ago)
- Topics: hacktoberfest, php
- Language: PHP
- Homepage:
- Size: 525 KB
- Stars: 23
- Watchers: 7
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Utopia Audit
[](https://travis-ci.com/utopia-php/audit)
[](https://appwrite.io/discord)
Utopia framework audit library is simple and lite library for managing application user logs. This library is aiming to be as simple and easy to learn and use. This library is maintained by the [Appwrite team](https://appwrite.io).
Although this library is part of the [Utopia Framework](https://github.com/utopia-php/framework) project it is dependency free, and can be used as standalone with any other PHP project or framework.
## Features
- **Adapter Pattern**: Support for multiple storage backends through adapters
- **Default Database Adapter**: Built-in support for utopia-php/database
- **Extensible**: Easy to create custom adapters for different storage solutions
- **Batch Operations**: Support for logging multiple events at once
- **Query Support**: Rich querying capabilities for retrieving logs
## Getting Started
Install using composer:
```bash
composer require utopia-php/audit
```
## Usage
### Using the Database Adapter (Default)
The simplest way to use Utopia Audit is with the built-in Database adapter:
```php
3,
PDO::ATTR_PERSISTENT => true,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_EMULATE_PREPARES => true,
PDO::ATTR_STRINGIFY_FETCHES => true,
]);
$cache = new Cache(new NoCache());
$database = new Database(new MySQL($pdo), $cache);
$database->setNamespace('namespace');
// Create audit instance with Database adapter
$audit = new Audit(new DatabaseAdapter($database));
$audit->setup();
```
### Using a Custom Adapter
You can create custom adapters by extending the `Utopia\Audit\Adapter` abstract class:
```php
'value1','key2' => 'value2']; // Any key-value pair you need to log
$audit->log($userId, $event, $resource, $userAgent, $ip, $location, $data);
```
**Get Logs By User**
Fetch all logs by given user ID with optional filtering parameters:
```php
// Basic usage
$logs = $audit->getLogsByUser('userId');
// With pagination
$logs = $audit->getLogsByUser(
userId: 'userId',
limit: 10,
offset: 0
);
// With time filtering using DateTime objects
$logs = $audit->getLogsByUser(
userId: 'userId',
after: new \DateTime('2024-01-01 00:00:00'),
before: new \DateTime('2024-12-31 23:59:59'),
limit: 25,
offset: 0,
ascending: false // false = newest first (default), true = oldest first
);
```
**Get Logs By User and Action**
Fetch all logs by given user ID and specific event names with optional filtering:
```php
// Basic usage
$logs = $audit->getLogsByUserAndEvents(
userId: 'userId',
events: ['update', 'delete']
);
// With time filtering and pagination
$logs = $audit->getLogsByUserAndEvents(
userId: 'userId',
events: ['update', 'delete'],
after: new \DateTime('-7 days'),
before: new \DateTime('now'),
limit: 50,
offset: 0,
ascending: false
);
```
**Get Logs By Resource**
Fetch all logs by a given resource name with optional filtering:
```php
// Basic usage
$logs = $audit->getLogsByResource('database/document-1');
// With time filtering and pagination
$logs = $audit->getLogsByResource(
resource: 'database/document-1',
after: new \DateTime('-30 days'),
before: new \DateTime('now'),
limit: 100,
offset: 0,
ascending: true // Get oldest logs first
);
```
**Batch Logging**
Log multiple events at once for better performance:
```php
use Utopia\Database\DateTime;
$events = [
[
'userId' => 'user-1',
'event' => 'create',
'resource' => 'database/document/1',
'userAgent' => 'Mozilla/5.0...',
'ip' => '127.0.0.1',
'location' => 'US',
'data' => ['key' => 'value'],
'time' => DateTime::now()
],
[
'userId' => 'user-2',
'event' => 'update',
'resource' => 'database/document/2',
'userAgent' => 'Mozilla/5.0...',
'ip' => '192.168.1.1',
'location' => 'UK',
'data' => ['key' => 'value'],
'time' => DateTime::now()
]
];
$documents = $audit->logBatch($events);
```
**Counting Logs**
All retrieval methods have corresponding count methods with the same filtering capabilities:
```php
// Count all logs for a user
$count = $audit->countLogsByUser('userId');
// Count logs within a time range
$count = $audit->countLogsByUser(
userId: 'userId',
after: new \DateTime('-7 days'),
before: new \DateTime('now')
);
// Count logs by resource
$count = $audit->countLogsByResource('database/document-1');
// Count logs by user and events
$count = $audit->countLogsByUserAndEvents(
userId: 'userId',
events: ['create', 'update', 'delete'],
after: new \DateTime('-30 days')
);
// Count logs by resource and events
$count = $audit->countLogsByResourceAndEvents(
resource: 'database/document-1',
events: ['update', 'delete']
);
```
**Advanced Filtering**
Get logs by resource and specific events:
```php
$logs = $audit->getLogsByResourceAndEvents(
resource: 'database/document-1',
events: ['create', 'update'],
after: new \DateTime('-24 hours'),
limit: 20,
offset: 0,
ascending: false
);
```
### Filtering Parameters
All retrieval methods support the following optional parameters:
- **after** (`?\DateTime`): Get logs created after this datetime
- **before** (`?\DateTime`): Get logs created before this datetime
- **limit** (`int`, default: 25): Maximum number of logs to return
- **offset** (`int`, default: 0): Number of logs to skip (for pagination)
- **ascending** (`bool`, default: false): Sort order - false for newest first, true for oldest first
## Adapters
Utopia Audit uses an adapter pattern to support different storage backends. Currently available adapters:
### Database Adapter (Default)
The Database adapter uses [utopia-php/database](https://github.com/utopia-php/database) to store audit logs in a database.
### ClickHouse Adapter
The ClickHouse adapter uses [ClickHouse](https://clickhouse.com/) for high-performance analytical queries on massive amounts of log data. It communicates with ClickHouse via HTTP interface using Utopia Fetch.
**Features:**
- Optimized for analytical queries and aggregations
- Handles billions of log entries efficiently
- Column-oriented storage for fast queries
- Automatic partitioning by month
- Bloom filter indexes for fast lookups
**Usage:**
```php
setup(); // Creates database and table
// Use as normal
$document = $audit->log(
userId: 'user-123',
event: 'document.create',
resource: 'database/document/1',
userAgent: 'Mozilla/5.0...',
ip: '127.0.0.1',
location: 'US',
data: ['key' => 'value']
);
```
**Performance Benefits:**
- Ideal for high-volume logging (millions of events per day)
- Fast aggregation queries (counts, analytics)
- Efficient storage with compression
- Automatic data partitioning and retention policies
### Creating Custom Adapters
To create a custom adapter, extend the `Utopia\Audit\Adapter` abstract class and implement all required methods:
```php