Filter

Filter styr vilka data som tas med i en ögonblicksbild. Uteslut cachetabeller, ignorera föränderliga tidsstämpelkolumner eller hoppa över temporära rader. Filter tillämpas när ögonblicksbilden tas och påverkar alla efterföljande operationer (diff, merge, apply).

use Merql\Filter\TableFilter;
use Merql\Filter\ColumnFilter;
use Merql\Snapshot\Snapshotter;

$snapshotter = new Snapshotter($connection);

$snapshot = $snapshotter->capture('baseline', filters: [
    TableFilter::exclude(['sessions', 'cache_*']),
    ColumnFilter::ignore(['updated_at', 'modified_date']),
]);

TableFilter

Styr vilka tabeller som tas med i en ögonblicksbild. Stöder glob-mönster via PHPs fnmatch().

Uteslut tabeller

use Merql\Filter\TableFilter;

$filter = TableFilter::exclude(['sessions', 'cache_*', 'wp_*_log']);

Alla tabeller som matchar ett uteslutningsmönster utelämnas från ögonblicksbilden. Jokertecknet * matchar valfri teckenföljd.

Inkludera tabeller

$filter = TableFilter::include(['posts', 'comments', 'users']);

Endast tabeller som matchar ett inkluderingsmönster tas med. Alla andra utesluts.

Så fungerar det

Filtrets metod apply() tar en lista med tabellnamn och returnerar den filtrerade delmängden:

$allTables = ['posts', 'comments', 'sessions', 'cache_pages', 'users'];

$filter = TableFilter::exclude(['sessions', 'cache_*']);
$filtered = $filter->apply($allTables);
// ['posts', 'comments', 'users']

$filter = TableFilter::include(['posts', 'users']);
$filtered = $filter->apply($allTables);
// ['posts', 'users']

När både inkluderings- och uteslutningsmönster finns (via separata filterinstanser) utvärderas uteslutning först. En tabell måste undvika alla uteslutningsmönster och matcha minst ett inkluderingsmönster för att tas med.

ColumnFilter

Tar bort specifika kolumner från raddata när ögonblicksbilden tas. Användbart för föränderliga kolumner som ändras vid varje skrivning och annars skulle orsaka falska diffar.

use Merql\Filter\ColumnFilter;

$filter = ColumnFilter::ignore(['updated_at', 'modified_date', 'last_login']);

Vanliga användningsområden

• Tidsstämplar för updated_at / modified_at som ändras vid varje sparning.
• revision-räknare som ökar automatiskt.
• session_token eller andra temporära fält.

Så fungerar det

Filtret tar bort namngivna kolumner från varje rad efter att radnyckeln har beräknats:

$filter = ColumnFilter::ignore(['updated_at']);

$row = ['id' => 1, 'title' => 'Hello', 'updated_at' => '2026-01-15 10:30:00'];
$filtered = $filter->applyToRow($row);
// ['id' => 1, 'title' => 'Hello']

Radnyckeln (identiteten) beräknas utifrån den ofiltrerade raden. Det innebär att identitetskolumner aldrig påverkas av kolumnfiltret. Endast data som används för fingeravtryck och diffning filtreras.

RowFilter

Filtrerar enskilda rader med ett predikat-closure. Closure-funktionen tar emot tabellnamnet och hela radens data och returnerar true för att ta med raden eller false för att utesluta den.

use Merql\Filter\RowFilter;

// Exclude draft posts.
$filter = RowFilter::create(function (string $table, array $row): bool {
    if ($table === 'posts' && ($row['status'] ?? '') === 'draft') {
        return false;
    }
    return true;
});

// Exclude rows with NULL email.
$filter = RowFilter::create(function (string $table, array $row): bool {
    if ($table === 'users') {
        return $row['email'] !== null;
    }
    return true;
});

Så fungerar det

Metoden shouldInclude() anropas för varje rad när ögonblicksbilden tas:

$include = $filter->shouldInclude('posts', ['id' => 1, 'status' => 'draft']);
// false

Uteslutna rader får inget fingeravtryck, lagras inte i ögonblicksbilden och visas inte i diffar eller sammanslagningar.

Kombinera filter

Skicka flera filter till capture(). Högst ett filter av varje typ används:

$snapshot = $snapshotter->capture('baseline', filters: [
    TableFilter::exclude(['cache_*']),
    ColumnFilter::ignore(['updated_at']),
    RowFilter::create(fn($table, $row) => ($row['active'] ?? '1') === '1'),
]);

Bearbetningsordning:

1. TableFilter körs först och avgör vilka tabeller som ska tas med.
2. För varje tabell läses rader från databasen.
3. RowFilter körs för varje rad och utesluter rader som inte matchar.
4. Radnyckeln beräknas utifrån den ofiltrerade raden (identitetskolumnerna är intakta).
5. ColumnFilter tar bort ignorerade kolumner från raddatan.
6. Fingeravtrycket beräknas utifrån den filtrerade raddatan.

Den här ordningen säkerställer att identitetskolumner alltid är tillgängliga när nyckeln beräknas, även om kolumnerna senare tas bort av kolumnfiltret.

Filter och konsekvens

Samma filter bör användas för alla tre ögonblicksbilder i en sammanslagning (base, ours, theirs). Om olika filter används kan det verka som om rader eller kolumner har lagts till eller tagits bort, trots att de bara har filtrerats på olika sätt.

// Use the same filter set for all snapshots.
$filters = [
    TableFilter::exclude(['sessions']),
    ColumnFilter::ignore(['updated_at']),
];

$base   = $snapshotter->capture('base', filters: $filters);
$ours   = $snapshotter->capture('ours', filters: $filters);
$theirs = $snapshotter->capture('theirs', filters: $filters);