Skip to main content
Version: 1.x

Filters Reference

Fine-grained control over audit queries

Filters allow you to restrict the results returned by a Query. They can be added via createQuery() options or directly on the Query object.

📋 Available Filters​

FilterClassDescription
SimpleFilterSimpleFilterEquality or IN match on a column
DateRangeFilterDateRangeFilterFilter by a date range on a datetime column
RangeFilterRangeFilterFilter by a numeric range
NullFilterNullFilterFilter for NULL / NOT NULL values
JsonFilterJsonFilterFilter by a value inside the diffs JSON column

All filter classes live under:

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\{FilterClass};
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

🔵 SimpleFilter​

Matches a single value or a list of values (generates = ? or IN (?,?) SQL).

Usage​

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\SimpleFilter;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

// Match a single value
$query->addFilter(new SimpleFilter(Query::TYPE, 'update'));

// Match multiple values (IN clause)
$query->addFilter(new SimpleFilter(Query::TYPE, ['insert', 'update']));

// Filter by user ID
$query->addFilter(new SimpleFilter(Query::USER_ID, 'user-42'));

// Filter by entity ID
$query->addFilter(new SimpleFilter(Query::OBJECT_ID, '100'));

Supported Columns​

ConstantColumn
Query::IDid
Query::TYPEtype
Query::OBJECT_IDobject_id
Query::DISCRIMINATORdiscriminator
Query::TRANSACTION_HASHtransaction_hash
Query::USER_IDblame_id

📅 DateRangeFilter​

Filters entries by a date range on created_at.

Usage​

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\DateRangeFilter;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

// Entries created in January 2024
$query->addFilter(new DateRangeFilter(
    Query::CREATED_AT,
    new \DateTimeImmutable('2024-01-01'),
    new \DateTimeImmutable('2024-01-31')
));

// Entries created after a given date (open end)
$query->addFilter(new DateRangeFilter(
    Query::CREATED_AT,
    new \DateTimeImmutable('2024-06-01'),
    null
));

// Entries created before a given date (open start)
$query->addFilter(new DateRangeFilter(
    Query::CREATED_AT,
    null,
    new \DateTimeImmutable('2024-06-01')
));

🔢 RangeFilter​

Filters entries by a numeric range (e.g., id between two values).

Usage​

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\RangeFilter;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

// Entries with ID between 100 and 200
$query->addFilter(new RangeFilter(Query::ID, 100, 200));

// IDs greater than 500 (open end)
$query->addFilter(new RangeFilter(Query::ID, 500, null));

❌ NullFilter​

Filters entries where a column is NULL or NOT NULL.

Usage​

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\NullFilter;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

// Entries where blame_id IS NULL (anonymous changes)
$query->addFilter(new NullFilter(Query::USER_ID, isNull: true));

// Entries where blame_id IS NOT NULL (authenticated changes)
$query->addFilter(new NullFilter(Query::USER_ID, isNull: false));

WARNING

NullFilter works on indexed columns such as blame_id, object_id, type, etc. Do not use Query::JSON with NullFilter — there is no json column in the audit table. To find entries where extra_data IS NULL, query without a filter and check $entry->extraData === null.

🔍 JsonFilter​

Filters entries by the presence of a field key within the diffs JSON column. Useful to find all audits where a specific field was changed.

Usage​

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\JsonFilter;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

// Entries where the 'title' field was part of the diff
$query->addFilter(new JsonFilter(Query::JSON, 'title'));

NOTE

JsonFilter implements PlatformAwareFilterInterface. The exact SQL it generates is platform-specific:

  • MySQL / MariaDB — Uses JSON_CONTAINS_PATH(diffs, 'one', '$.title')
  • PostgreSQL — Uses diffs ? 'title'
  • SQLite — Uses json_extract(diffs, '$.title') IS NOT NULL

🔗 Combining Filters​

Multiple filters are combined with AND:

use DH\Auditor\Provider\Doctrine\Persistence\Reader\Filter\{DateRangeFilter, SimpleFilter};
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Query;

$query = $reader->createQuery(Post::class);

// All updates by user '42' in the last 30 days
$query->addFilter(new SimpleFilter(Query::TYPE, 'update'));
$query->addFilter(new SimpleFilter(Query::USER_ID, '42'));
$query->addFilter(new DateRangeFilter(
    Query::CREATED_AT,
    new \DateTimeImmutable('-30 days'),
    null
));

$entries = $query->execute();

📐 Ordering Results​

// Default order: created_at DESC, id DESC
// Override:
$query->addOrderBy(Query::CREATED_AT, 'ASC');
$query->addOrderBy(Query::ID, 'ASC');

📄 Manual Pagination​

// 20 results starting at offset 40 (page 3 of 20 per page)
$query->limit(20, 40);
$entries = $query->execute();