README

Extended production features for the AARO ORM (amtgard/active-record-orm).

Requirements

• PHP 8.3+
• Composer
• For integration tests: Docker (MariaDB via Compose)

Installation

composer require amtgard/aaro-extensions

Local development against the sibling ORM checkout:

composer install

The package composer.json includes a path repository to ../active-record-orm.

Usage

Wrap a core table (or repository) so inserts, updates, and deletes are recorded automatically in a companion audit table. Application code continues to use the core table normally.

Table level

use Amtgard\AaroExtensions\Audit\AuditConfiguration;
use Amtgard\AaroExtensions\Audit\AuditTableFactory;

$config = AuditConfiguration::builder()
    ->editedBySupplier(fn () => $currentUserId)
    ->build();

$table = AuditTableFactory::build($database, $policy, 'users', $config);

$table->clear();
$table->name = 'Alice';
$table->save();

Repository / EntityManager level

use Amtgard\AaroExtensions\Audit\AuditTableFactory;

$em = EntityManager::builder()
    ->database($database)
    ->dataAccessPolicy($policy)
    ->mapperSupplier(fn ($db, $policy, $name) => AuditTableFactory::mapperSupplier(
        $db,
        $policy,
        $name,
        $auditConfiguration,
    ))
    ->build();

Or use AuditRepositoryEntityTrait on a RepositoryEntity and implement auditConfiguration().

Configuration

AuditConfiguration::builder()
    ->auditTableName('users_history')   // default: {table}_audit
    ->editedBySupplier(fn () => 42)     // or EditedBySupplier instance
    ->auditInserts(false)               // default: true
    ->build();

Keeping audit tables in sync

Every auditable core table needs a matching audit table. By convention the audit table is named {core_table}_audit (configurable via AuditConfiguration).

When the core schema changes, the audit table must be updated as well:

The audit table always includes these metadata columns (Phinx adds an auto-increment id PK automatically):

• audit_id — core row id (NOT NULL)
• edit_at, edit_fields, edited_by_id, operation

See Audit reference below for full schema and write semantics.

Migration workflow

1. Create — after defining a core table, create its audit table in Phinx with mirrored columns (all nullable except metadata).
2. Patch — whenever a core migration adds, changes, or drops columns, apply the corresponding change to the audit table in the same release (use dropped_{n}_* for removed columns).

Migration generator and patcher commands:

# Generate Phinx migration(s) for audit table(s) from the live database schema
composer audit:phinx -- --env=.env --out-dir=db/migrations [--table=users]

# Emit a patch migration after core schema changes
composer audit:patch -- --env=.env --out-dir=db/migrations [--table=users]

# Merge project-specific table exclusions with the bundled defaults
composer audit:phinx -- --env=.env --out-dir=db/migrations --exclude-file=db/audit-exclusions.yaml

Or invoke the binary directly: vendor/bin/aaro-audit-migrate phinx ...

When --table is omitted, the CLI scans every table in the database and generates migrations for each one that is not excluded. Explicit --table always targets that table, even if it appears in an exclusions file.

Table exclusions

Infrastructure and framework tables (Phinx migration log, existing audit tables, etc.) should not receive audit migrations. The package ships a default list at resources/audit-table-exclusions.yaml:

tables:
  - phinxlog

suffixes:
  - _audit

Add project-specific exclusions in a local YAML file and pass it with --exclude-file. Entries are merged with the bundled defaults, not replaced:

# db/audit-exclusions.yaml
tables:
  - queue_jobs
  - sessions
suffixes:
  - _history

composer audit:patch -- --env=.env --out-dir=db/migrations --exclude-file=db/audit-exclusions.yaml

To exclude a table that ships in the defaults (unlikely), target it explicitly with --table instead of relying on the bulk scan.

Example audit migration (Phinx)

$this->table('users_audit')
    ->addColumn('audit_id', 'integer', ['null' => false])
    ->addColumn('edit_at', 'datetime', ['null' => false])
    ->addColumn('edit_fields', 'json', ['null' => true])
    ->addColumn('edited_by_id', 'integer', ['null' => true])
    ->addColumn('operation', 'enum', ['values' => ['insert', 'update', 'delete'], 'null' => false])
    ->addColumn('name', 'string', ['null' => true, 'limit' => 255])
    ->addColumn('email', 'string', ['null' => true, 'limit' => 255])
    ->create();

Testing

Unit tests

composer test:unit

Integration tests (Docker)

Integration tests use MariaDB on port 24307 via this package's docker-compose.dev.yml.

composer docker:up
composer migrate:test
composer test:integ
composer docker:down

Copy test-resources/.env.example to test-resources/.env if needed.

composer test    # unit + integration

Audit reference

Technical details for the row-level audit feature.

Overview

Transparent auditing for ORM Table and Repository usage. The wrapper records inserts, updates, and deletes in a companion audit table without audit-specific code in business logic.

Each audit row is a rolling snapshot of what happened (new/current values), ordered by time so you can answer “who changed this record to what?” and replay a record’s history from insert through delete.

Table pairing

Schema

Phinx adds an auto-increment id as the audit row primary key. You declare the rest.

Metadata columns

Mirrored core columns

• Every core column except id is replicated on the audit table.
• All mirrored columns are explicitly nullable.
• Values are snapshots after the operation (see write semantics).

When a core column is dropped, patch migrations preserve history as dropped_{n}_{column_name} on the audit table.

Write semantics

Example for core row id = 42:

id | audit_id | operation | edit_at          | edit_fields      | string_value
---+----------+-----------+------------------+------------------+-------------
 1 |       42 | insert    | 2026-06-07 10:00 | []               | Alice
 2 |       42 | update    | 2026-06-07 11:00 | ["string_value"] | Alicia
 3 |       42 | delete    | 2026-06-07 12:00 | []               | Alicia

Package layout

src/Audit/
  AuditTable.php              Wrapper around core Table
  AuditTableFactory.php       Builds AuditTable + EntityMapper supplier
  AuditConfiguration.php      Table name, supplier, insert toggle
  AuditSnapshotCapture.php    Computes snapshot payload per operation
  AuditSnapshot.php           Value object for one audit event
  AuditOperation.php          insert | update | delete
  AuditColumns.php            Metadata column name constants
  AuditRepository.php         Repository base class
  AuditRepositoryEntityTrait.php
  EditedBySupplier.php        Optional supplier interface
  Migration/
    AuditMigrationService.php       phinx / patch orchestration
    AuditSchemaGenerator.php        core schema → audit schema
    AuditSchemaDiffer.php             diff core vs audit for patches
    AuditPhinxWriter.php              Phinx migration file output
    AuditTableExclusions.php          table/suffix exclusion rules
    AuditTableExclusionsLoader.php    YAML loader for exclusions
    Cli/AuditMigrateCommand.php       aaro-audit-migrate CLI
resources/
  audit-table-exclusions.yaml   default tables skipped by bulk scan
bin/
  aaro-audit-migrate            CLI entry point

Roadmap

• Phase 1 — Runtime audit wrapper + unit tests
• Phase 2 — Docker Compose + integration tests
• Phase 3 — Phinx migration generator and audit-table patcher (audit:phinx, audit:patch)

License

MIT — see LICENSE.