Siirry sisältöön

Suodattimet

Näytä Markdown-muodossa Muokkaa palvelussa GitHub Dokumentaatio: 60c6cc7

Suodattimet määrittävät, mitä tietoja tilannekuvaan sisällytetään. Sulje välimuistitaulut pois, ohita usein muuttuvat aikaleimasarakkeet tai jätä tilapäiset rivit pois. Suodattimia käytetään tilannekuvan tallennuksen aikana, ja ne vaikuttavat kaikkiin myöhempiin toimintoihin (vertailu, yhdistäminen, käyttöönotto).

PHP
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

Määrittää, mitkä taulut sisällytetään tilannekuvaan. Tukee glob-malleja PHPn fnmatch()n avulla.

Sulje tauluja pois

PHP
use Merql\Filter\TableFilter;

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

Kaikki poissulkumallia vastaavat taulut jätetään tilannekuvan ulkopuolelle. Jokerimerkki * vastaa mitä tahansa merkkijonoa.

Sisällytä tauluja

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

Vain sisällytysmallia vastaavat taulut tallennetaan. Kaikki muut jätetään pois.

Näin se toimii

Suodattimen apply()-metodi ottaa vastaan taulunimien luettelon ja palauttaa suodatetun osajoukon:

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

Kun sekä sisällytys- että poissulkumallit ovat käytössä (erillisissä suodatininstansseissa), poissulku arvioidaan ensin. Taulu säilytetään vain, jos se ei vastaa yhtäkään poissulkumallia ja vastaa vähintään yhtä sisällytysmallia.

ColumnFilter

Poistaa tietyt sarakkeet rivitiedoista tallennuksen aikana. Hyödyllinen usein muuttuville sarakkeille, joiden arvot muuttuvat jokaisella kirjoituskerralla ja aiheuttaisivat vääriä eroja.

PHP
use Merql\Filter\ColumnFilter;

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

Yleisiä käyttötapauksia

  • updated_at / modified_at, jotka muuttuvat jokaisella tallennuskerralla.
  • revision, joiden arvo kasvaa automaattisesti.
  • session_token tai muut tilapäiset kentät.

Näin se toimii

Suodatin poistaa nimetyt sarakkeet kustakin rivistä rivitunnisteen laskemisen jälkeen:

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

Rivitunniste (identiteetti) lasketaan suodattamattomasta rivistä. Sarakesuodatin ei siis vaikuta identiteettisarakkeisiin. Vain sormenjäljen ja erojen laskennassa käytettävät tiedot suodatetaan.

RowFilter

Suodattaa yksittäisiä rivejä predikaattilausekkeella. Lauseke saa parametreikseen taulun nimen ja rivin kaikki tiedot ja palauttaa arvon true rivin sisällyttämiseksi tai false sen poissulkemiseksi.

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

Näin se toimii

shouldInclude()-metodia kutsutaan tallennuksen aikana jokaiselle riville:

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

Poissuljettuja rivejä ei sormenjälkitetä eikä tallenneta tilannevedokseen, eivätkä ne näy eroissa tai yhdistämisissä.

Suodattimien yhdistäminen

Välitä useita suodattimia metodille capture(). Kutakin suodatintyyppiä käytetään enintään yhtä:

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

Käsittelyjärjestys:

  1. TableFilter suoritetaan ensin, ja se määrittää tallennettavat taulut.
  2. Kunkin taulun rivit luetaan tietokannasta.
  3. RowFilter suoritetaan jokaiselle riville ja hylkää ehdon vastaiset rivit.
  4. Rivitunniste lasketaan suodattamattomasta rivistä (identiteettisarakkeet säilyvät).
  5. ColumnFilter poistaa ohitettavat sarakkeet rivitiedoista.
  6. Sormenjälki lasketaan suodatetuista rivitiedoista.

Tässä järjestyksessä identiteettisarakkeet ovat aina käytettävissä tunnisteen laskentaa varten, vaikka sarakesuodatin poistaisi ne myöhemmin.

Suodattimet ja yhdenmukaisuus

Yhdistämisen kaikissa kolmessa tilannevedoksessa (base, ours, theirs) tulisi käyttää samoja suodattimia. Jos suodattimet eroavat, rivejä tai sarakkeita voi näyttää lisätyn tai poistuneen, vaikka ne on vain suodatettu eri tavoin.

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