{"id":20540588,"url":"https://github.com/utopia-php/audit","last_synced_at":"2026-05-08T12:05:58.326Z","repository":{"id":36841724,"uuid":"230656861","full_name":"utopia-php/audit","owner":"utopia-php","description":"Lite \u0026 fast micro PHP audit log library that is **easy to use**.","archived":false,"fork":false,"pushed_at":"2026-02-01T08:14:10.000Z","size":538,"stargazers_count":23,"open_issues_count":1,"forks_count":9,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-02-01T17:09:26.365Z","etag":null,"topics":["hacktoberfest","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utopia-php.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-12-28T19:39:05.000Z","updated_at":"2026-02-01T08:12:57.000Z","dependencies_parsed_at":"2026-01-16T08:02:45.289Z","dependency_job_id":null,"html_url":"https://github.com/utopia-php/audit","commit_stats":{"total_commits":190,"total_committers":18,"mean_commits":"10.555555555555555","dds":0.7736842105263158,"last_synced_commit":"237538b618506bbc0efc0e7884d49cdf52c20004"},"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"purl":"pkg:github/utopia-php/audit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Faudit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Faudit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Faudit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Faudit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utopia-php","download_url":"https://codeload.github.com/utopia-php/audit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Faudit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29012554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T10:37:29.253Z","status":"ssl_error","status_checked_at":"2026-02-02T10:37:28.644Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","php"],"created_at":"2024-11-16T01:16:26.520Z","updated_at":"2026-02-02T12:31:33.803Z","avatar_url":"https://github.com/utopia-php.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Utopia Audit\n\n[![Build Status](https://travis-ci.org/utopia-php/audit.svg?branch=master)](https://travis-ci.com/utopia-php/audit)\n![Total Downloads](https://img.shields.io/packagist/dt/utopia-php/audit.svg)\n[![Discord](https://img.shields.io/discord/564160730845151244)](https://appwrite.io/discord)\n\nUtopia 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).\n\nAlthough 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.\n\n## Features\n\n- **Adapter Pattern**: Support for multiple storage backends through adapters\n- **Default Database Adapter**: Built-in support for utopia-php/database\n- **Extensible**: Easy to create custom adapters for different storage solutions\n- **Batch Operations**: Support for logging multiple events at once\n- **Query Support**: Rich querying capabilities for retrieving logs\n\n## Getting Started\n\nInstall using composer:\n```bash\ncomposer require utopia-php/audit\n```\n\n## Usage\n\n### Using the Database Adapter (Default)\n\nThe simplest way to use Utopia Audit is with the built-in Database adapter:\n\n```php\n\u003c?php\n\nrequire_once __DIR__ . '/../../vendor/autoload.php';\n\nuse PDO;\nuse Utopia\\Audit\\Audit;\nuse Utopia\\Cache\\Cache;\nuse Utopia\\Cache\\Adapter\\None as NoCache;\nuse Utopia\\Database\\Adapter\\MySQL;\nuse Utopia\\Database\\Database;\nuse Utopia\\Audit\\Adapter\\Database as DatabaseAdapter;\n\n$dbHost = '127.0.0.1';\n$dbUser = 'travis';\n$dbPass = '';\n$dbPort = '3306';\n\n$pdo = new PDO(\"mysql:host={$dbHost};port={$dbPort};charset=utf8mb4\", $dbUser, $dbPass, [\n    PDO::ATTR_TIMEOUT =\u003e 3,\n    PDO::ATTR_PERSISTENT =\u003e true,\n    PDO::ATTR_DEFAULT_FETCH_MODE =\u003e PDO::FETCH_ASSOC,\n    PDO::ATTR_ERRMODE =\u003e PDO::ERRMODE_EXCEPTION,\n    PDO::ATTR_EMULATE_PREPARES =\u003e true,\n    PDO::ATTR_STRINGIFY_FETCHES =\u003e true,\n]);\n        \n$cache = new Cache(new NoCache());\n\n$database = new Database(new MySQL($pdo), $cache);\n$database-\u003esetNamespace('namespace');\n\n// Create audit instance with Database adapter\n$audit = new Audit(new DatabaseAdapter($database));\n$audit-\u003esetup();\n```\n\n### Using a Custom Adapter\n\nYou can create custom adapters by extending the `Utopia\\Audit\\Adapter` abstract class:\n\n```php\n\u003c?php\n\nuse Utopia\\Audit\\Audit;\nuse Utopia\\Audit\\Adapter\\Database as DatabaseAdapter;\nuse Utopia\\Database\\Database;\n\n// Using the Database adapter directly\n$adapter = new DatabaseAdapter($database);\n$audit = new Audit($adapter);\n```\n\n### Basic Operations\n\n**Create Log**\n\nA simple example for logging a user action in the audit DB.\n\n```php\n$userId = 'user-unique-id';\n$event = 'deleted'; // Log specific action name\n$resource = 'database/document-1'; // Resource unique ID (great for filtering specific logs)\n$userAgent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36'; // Set user-agent\n$ip = '127.0.0.1'; // User IP\n$location = 'US'; // Country name or code\n$data = ['key1' =\u003e 'value1','key2' =\u003e 'value2']; // Any key-value pair you need to log\n\n$audit-\u003elog($userId, $event, $resource, $userAgent, $ip, $location, $data);\n```\n\n**Get Logs By User**\n\nFetch all logs by given user ID with optional filtering parameters:\n\n```php\n// Basic usage\n$logs = $audit-\u003egetLogsByUser('userId');\n\n// With pagination\n$logs = $audit-\u003egetLogsByUser(\n    userId: 'userId',\n    limit: 10,\n    offset: 0\n);\n\n// With time filtering using DateTime objects\n$logs = $audit-\u003egetLogsByUser(\n    userId: 'userId',\n    after: new \\DateTime('2024-01-01 00:00:00'),\n    before: new \\DateTime('2024-12-31 23:59:59'),\n    limit: 25,\n    offset: 0,\n    ascending: false  // false = newest first (default), true = oldest first\n);\n```\n\n**Get Logs By User and Action**\n\nFetch all logs by given user ID and specific event names with optional filtering:\n\n```php\n// Basic usage\n$logs = $audit-\u003egetLogsByUserAndEvents(\n    userId: 'userId',\n    events: ['update', 'delete']\n);\n\n// With time filtering and pagination\n$logs = $audit-\u003egetLogsByUserAndEvents(\n    userId: 'userId',\n    events: ['update', 'delete'],\n    after: new \\DateTime('-7 days'),\n    before: new \\DateTime('now'),\n    limit: 50,\n    offset: 0,\n    ascending: false\n);\n```\n\n**Get Logs By Resource**\n\nFetch all logs by a given resource name with optional filtering:\n\n```php\n// Basic usage\n$logs = $audit-\u003egetLogsByResource('database/document-1');\n\n// With time filtering and pagination\n$logs = $audit-\u003egetLogsByResource(\n    resource: 'database/document-1',\n    after: new \\DateTime('-30 days'),\n    before: new \\DateTime('now'),\n    limit: 100,\n    offset: 0,\n    ascending: true  // Get oldest logs first\n);\n```\n\n**Batch Logging**\n\nLog multiple events at once for better performance:\n\n```php\nuse Utopia\\Database\\DateTime;\n\n$events = [\n    [\n        'userId' =\u003e 'user-1',\n        'event' =\u003e 'create',\n        'resource' =\u003e 'database/document/1',\n        'userAgent' =\u003e 'Mozilla/5.0...',\n        'ip' =\u003e '127.0.0.1',\n        'location' =\u003e 'US',\n        'data' =\u003e ['key' =\u003e 'value'],\n        'time' =\u003e DateTime::now()\n    ],\n    [\n        'userId' =\u003e 'user-2',\n        'event' =\u003e 'update',\n        'resource' =\u003e 'database/document/2',\n        'userAgent' =\u003e 'Mozilla/5.0...',\n        'ip' =\u003e '192.168.1.1',\n        'location' =\u003e 'UK',\n        'data' =\u003e ['key' =\u003e 'value'],\n        'time' =\u003e DateTime::now()\n    ]\n];\n\n$documents = $audit-\u003elogBatch($events);\n```\n\n**Counting Logs**\n\nAll retrieval methods have corresponding count methods with the same filtering capabilities:\n\n```php\n// Count all logs for a user\n$count = $audit-\u003ecountLogsByUser('userId');\n\n// Count logs within a time range\n$count = $audit-\u003ecountLogsByUser(\n    userId: 'userId',\n    after: new \\DateTime('-7 days'),\n    before: new \\DateTime('now')\n);\n\n// Count logs by resource\n$count = $audit-\u003ecountLogsByResource('database/document-1');\n\n// Count logs by user and events\n$count = $audit-\u003ecountLogsByUserAndEvents(\n    userId: 'userId',\n    events: ['create', 'update', 'delete'],\n    after: new \\DateTime('-30 days')\n);\n\n// Count logs by resource and events\n$count = $audit-\u003ecountLogsByResourceAndEvents(\n    resource: 'database/document-1',\n    events: ['update', 'delete']\n);\n```\n\n**Advanced Filtering**\n\nGet logs by resource and specific events:\n\n```php\n$logs = $audit-\u003egetLogsByResourceAndEvents(\n    resource: 'database/document-1',\n    events: ['create', 'update'],\n    after: new \\DateTime('-24 hours'),\n    limit: 20,\n    offset: 0,\n    ascending: false\n);\n```\n\n### Filtering Parameters\n\nAll retrieval methods support the following optional parameters:\n\n- **after** (`?\\DateTime`): Get logs created after this datetime\n- **before** (`?\\DateTime`): Get logs created before this datetime  \n- **limit** (`int`, default: 25): Maximum number of logs to return\n- **offset** (`int`, default: 0): Number of logs to skip (for pagination)\n- **ascending** (`bool`, default: false): Sort order - false for newest first, true for oldest first\n\n## Adapters\n\nUtopia Audit uses an adapter pattern to support different storage backends. Currently available adapters:\n\n### Database Adapter (Default)\n\nThe Database adapter uses [utopia-php/database](https://github.com/utopia-php/database) to store audit logs in a database.\n\n\n### ClickHouse Adapter\n\nThe 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.\n\n**Features:**\n- Optimized for analytical queries and aggregations\n- Handles billions of log entries efficiently\n- Column-oriented storage for fast queries\n- Automatic partitioning by month\n- Bloom filter indexes for fast lookups\n\n**Usage:**\n\n```php\n\u003c?php\n\nuse Utopia\\Audit\\Audit;\nuse Utopia\\Audit\\Adapter\\ClickHouse;\n\n// Create ClickHouse adapter\n$adapter = new ClickHouse(\n    host: 'localhost',\n    database: 'audit',\n    username: 'default',\n    password: '',\n    port: 8123,\n    table: 'audit_logs'\n);\n\n$audit = new Audit($adapter);\n$audit-\u003esetup(); // Creates database and table\n\n// Use as normal\n$document = $audit-\u003elog(\n    userId: 'user-123',\n    event: 'document.create',\n    resource: 'database/document/1',\n    userAgent: 'Mozilla/5.0...',\n    ip: '127.0.0.1',\n    location: 'US',\n    data: ['key' =\u003e 'value']\n);\n```\n\n**Performance Benefits:**\n- Ideal for high-volume logging (millions of events per day)\n- Fast aggregation queries (counts, analytics)\n- Efficient storage with compression\n- Automatic data partitioning and retention policies\n\n### Creating Custom Adapters\n\nTo create a custom adapter, extend the `Utopia\\Audit\\Adapter` abstract class and implement all required methods:\n\n```php\n\u003c?php\n\nnamespace MyApp\\Audit;\n\nuse Utopia\\Audit\\Adapter;\nuse Utopia\\Audit\\Log;\n\nclass CustomAdapter extends Adapter\n{\n    public function getName(): string\n    {\n        return 'Custom';\n    }\n\n    public function setup(): void\n    {\n        // Initialize your storage backend (create tables, indexes, etc.)\n    }\n\n    public function create(array $log): Log\n    {\n        // Store a single log entry and return a Log object\n    }\n\n    public function createBatch(array $logs): array\n    {\n        // Store multiple log entries and return array of Log objects\n    }\n\n    public function getByUser(\n        string $userId,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n        int $limit = 25,\n        int $offset = 0,\n        bool $ascending = false,\n    ): array {\n        // Retrieve logs by user ID with optional filtering\n    }\n\n    public function countByUser(\n        string $userId,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n    ): int {\n        // Count logs by user ID with optional time filtering\n    }\n\n    public function getByResource(\n        string $resource,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n        int $limit = 25,\n        int $offset = 0,\n        bool $ascending = false,\n    ): array {\n        // Retrieve logs by resource with optional filtering\n    }\n\n    public function countByResource(\n        string $resource,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n    ): int {\n        // Count logs by resource with optional time filtering\n    }\n\n    public function getByUserAndEvents(\n        string $userId,\n        array $events,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n        int $limit = 25,\n        int $offset = 0,\n        bool $ascending = false,\n    ): array {\n        // Retrieve logs by user ID and specific events with optional filtering\n    }\n\n    public function countByUserAndEvents(\n        string $userId,\n        array $events,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n    ): int {\n        // Count logs by user ID and events with optional time filtering\n    }\n\n    public function getByResourceAndEvents(\n        string $resource,\n        array $events,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n        int $limit = 25,\n        int $offset = 0,\n        bool $ascending = false,\n    ): array {\n        // Retrieve logs by resource and specific events with optional filtering\n    }\n\n    public function countByResourceAndEvents(\n        string $resource,\n        array $events,\n        ?\\DateTime $after = null,\n        ?\\DateTime $before = null,\n    ): int {\n        // Count logs by resource and events with optional time filtering\n    }\n\n    public function cleanup(\\DateTime $datetime): bool\n    {\n        // Delete logs older than the specified datetime\n        // Return true on success, false otherwise\n    }\n}\n```\n\nThen use your custom adapter:\n\n```php\n$adapter = new CustomAdapter();\n$audit = new Audit($adapter);\n```\n\n## System Requirements\n\nUtopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.\n\n## Copyright and license\n\nThe MIT License (MIT) [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futopia-php%2Faudit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futopia-php%2Faudit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futopia-php%2Faudit/lists"}