Filtre

Filtre určujú, ktoré údaje sa zahrnú do snímky. Vylúčte tabuľky vyrovnávacej pamäte, ignorujte nestále stĺpce časových značiek alebo preskočte dočasné riadky. Filtre sa použijú pri zachytávaní snímky a ovplyvňujú všetky nadväzujúce operácie (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

Určuje, ktoré tabuľky sa zahrnú do snímky. Podporuje vzory glob pomocou PHPfnmatch().

Vylúčenie tabuliek

use Merql\Filter\TableFilter;

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

Každá tabuľka zodpovedajúca vzoru vylúčenia sa zo snímky vynechá. Zástupný znak * zodpovedá ľubovoľnej postupnosti znakov.

Zahrnutie tabuliek

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

Zachytia sa iba tabuľky zodpovedajúce vzoru zahrnutia. Všetky ostatné sa vylúčia.

Ako to funguje

Metóda apply() filtra prijíma zoznam názvov tabuliek a vracia prefiltrovanú podmnožinu:

$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']

Ak sú prítomné vzory zahrnutia aj vylúčenia (prostredníctvom samostatných inštancií filtrov), najprv sa vyhodnotí vylúčenie. Tabuľka nesmie zodpovedať žiadnemu vzoru vylúčenia a musí zodpovedať aspoň jednému vzoru zahrnutia, aby zostala zachovaná.

ColumnFilter

Pri zachytávaní odstráni z údajov riadka konkrétne stĺpce. Hodí sa pre nestále stĺpce, ktoré sa menia pri každom zápise a spôsobovali by falošné rozdiely.

use Merql\Filter\ColumnFilter;

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

Bežné prípady použitia

• updated_at / modified_at časové značky, ktoré sa menia pri každom uložení.
• revision počítadlá, ktoré sa automaticky zvyšujú.
• session_token alebo iné dočasné polia.

Ako to funguje

Filter odstráni pomenované stĺpce z každého riadka po výpočte kľúča riadka:

$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']

Kľúč riadka (identita) sa vypočíta z nefiltrovaného riadka. Stĺpcový filter preto nikdy neovplyvní stĺpce identity. Filtrujú sa iba údaje používané na výpočet odtlačku a porovnávanie rozdielov.

RowFilter

Filtruje jednotlivé riadky pomocou predikátovej uzatváracej funkcie. Funkcia dostane názov tabuľky a úplné údaje riadka a vráti true na zahrnutie riadka alebo false na jeho vylúčenie.

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;
});

Ako to funguje

Metóda shouldInclude() sa volá pri zachytávaní pre každý riadok:

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

Vylúčené riadky sa neotlačkujú, neukladajú do snímky a nezobrazia sa v rozdieloch ani zlúčeniach.

Kombinovanie filtrov

Odovzdajte viacero filtrov do capture(). Použije sa najviac jeden filter každého typu:

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

Poradie spracovania:

1. TableFilter sa spustí ako prvý a určí, ktoré tabuľky sa zachytia.
2. Z databázy sa načítajú riadky každej tabuľky.
3. RowFilter sa spustí pre každý riadok a vylúči tie, ktoré nevyhovujú.
4. Kľúč riadka sa vypočíta z nefiltrovaného riadka (stĺpce identity zostanú zachované).
5. ColumnFilter odstráni ignorované stĺpce z údajov riadka.
6. Odtlačok sa vypočíta z prefiltrovaných údajov riadka.

Toto poradie zaručuje, že stĺpce identity sú vždy dostupné pri výpočte kľúča, aj keď ich stĺpcový filter neskôr odstráni.

Filtre a konzistentnosť

Pri zlúčení by sa mali pre všetky tri snímky použiť rovnaké filtre (základ, naše, ich). Pri použití rôznych filtrov sa môžu riadky alebo stĺpce javiť ako pridané či odstránené, hoci sa v skutočnosti líšili iba použité filtre.

// 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);