Obsługa konfliktów

Konflikt występuje, gdy obie strony scalania zmieniają te same dane w niezgodny sposób. merql wykrywa cztery typy konfliktów i udostępnia automatyczne oraz ręczne strategie ich rozwiązywania.

$result = $merge->merge($base, $ours, $theirs);

if (!$result->isClean()) {
    foreach ($result->conflicts() as $conflict) {
        echo "{$conflict->table()}.{$conflict->column()}: "
           . "{$conflict->oursValue()} vs {$conflict->theirsValue()}\n";
    }
}

Typy konfliktów

update_update

Obie strony zmieniły tę samą kolumnę w tym samym wierszu na różne wartości. To najczęstszy typ konfliktu.

Base:    posts #42  title = "Hello"
Ours:    posts #42  title = "Welcome"
Theirs:  posts #42  title = "Greetings"

Konflikt zawiera: tabelę posts, klucz wiersza 42, kolumnę title, naszą wartość Welcome, wartość drugiej strony Greetings i wartość bazową Hello.

update_delete

Jedna strona zaktualizowała wiersz, a druga go usunęła. merql nie może ustalić, czy powinna wygrać aktualizacja, czy usunięcie.

Ours:    posts #42  title = "Updated Title"    (updated)
Theirs:  posts #42  (deleted)

Konflikt zawiera: tabelę posts, klucz wiersza 42 i typ update_delete. Nasza wartość zawiera cały zaktualizowany wiersz. Wartość drugiej strony to null.

delete_update

Odwrotność update_delete. Druga strona zaktualizowała wiersz, a nasza go usunęła.

Ours:    posts #42  (deleted)
Theirs:  posts #42  title = "Updated Title"    (updated)

Konflikt zawiera: typ delete_update. Nasza wartość to null, a wartość drugiej strony zawiera cały zaktualizowany wiersz.

insert_insert

Obie strony wstawiły wiersz z tym samym kluczem głównym. Ponieważ oba wiersze są nowe (nie występują w bazie), merql nie może ich scalić.

Base:    (no row #99)
Ours:    posts #99  { title: "My Post" }
Theirs:  posts #99  { title: "Their Post" }

Konflikt zawiera: typ insert_insert. Nasza wartość zawiera dane naszego wiersza, a wartość drugiej strony — dane jej wiersza.

Klasa Conflict

Każdy konflikt jest obiektem tylko do odczytu z następującymi akcesorami:

$conflict->table();      // string: table name
$conflict->rowKey();     // string: encoded row identity key
$conflict->type();       // string: "update_update"|"update_delete"|"delete_update"|"insert_insert"
$conflict->column();     // ?string: column name (null for structural conflicts)
$conflict->oursValue();  // mixed: our value (null for delete side, full row for structural)
$conflict->theirsValue(); // mixed: their value (null for delete side, full row for structural)
$conflict->baseValue();  // mixed: base value (null for inserts)

Metoda column() zwraca nazwę kolumny dla konfliktów update_update, a null dla konfliktów strukturalnych (update_delete, delete_update, insert_insert).

Odczytywanie klucza głównego

Klucz wiersza jest zakodowanym ciągiem. Aby uzyskać tablicę z nazwami kluczy głównych, przekaż kolumny tożsamości:

$pk = $conflict->primaryKey(['id']);
// ['id' => '42']

$pk = $conflict->primaryKey(['tenant_id', 'user_id']);
// ['tenant_id' => '1', 'user_id' => '99']

Automatyczne rozwiązywanie za pomocą ConflictPolicy

ConflictResolver stosuje zasady, aby rozwiązać wszystkie konflikty jednocześnie:

use Merql\Merge\ConflictPolicy;
use Merql\Merge\ConflictResolver;

// One side wins everywhere.
$resolved = ConflictResolver::resolve($result, ConflictPolicy::OursWins);
$resolved = ConflictResolver::resolve($result, ConflictPolicy::TheirsWins);

// Manual: return the result unchanged (inspect conflicts yourself).
$resolved = ConflictResolver::resolve($result, ConflictPolicy::Manual);

Wyliczenie ConflictPolicy

Jak działa rozwiązywanie

W przypadku konfliktów update_update mechanizm rozwiązywania modyfikuje istniejącą operację scalania dla danego wiersza, zastępując wartość konfliktowej kolumny wartością wygrywającej strony.

W przypadku konfliktów strukturalnych (update_delete, delete_update, insert_insert) mechanizm rozwiązywania dodaje do wyniku nową operację:

• update_delete z OursWins dodaje operację UPDATE.
• update_delete z TheirsWins dodaje operację DELETE.
• delete_update z OursWins dodaje operację DELETE.
• delete_update z TheirsWins dodaje operację UPDATE.
• insert_insert używa wartości wiersza ze zwycięskiej strony.

Rozwiązany obiekt MergeResult ma pustą listę konfliktów i można go zastosować bezpośrednio.

Ręczne rozwiązywanie

Aby uzyskać szczegółową kontrolę, sprawdź każdy konflikt i przygotuj własne rozwiązanie:

foreach ($result->conflicts() as $conflict) {
    echo "Table:  {$conflict->table()}\n";
    echo "Row:    {$conflict->rowKey()}\n";
    echo "Type:   {$conflict->type()}\n";

    if ($conflict->column() !== null) {
        echo "Column: {$conflict->column()}\n";
        echo "Base:   " . var_export($conflict->baseValue(), true) . "\n";
        echo "Ours:   " . var_export($conflict->oursValue(), true) . "\n";
        echo "Theirs: " . var_export($conflict->theirsValue(), true) . "\n";
    }
}

Zastosowanie przy nierozwiązanych konfliktach

Applier odmawia zastosowania wyniku scalania z nierozwiązanymi konfliktami. Zgłasza wyjątek ConflictException:

use Merql\Exceptions\ConflictException;

try {
    $applier->apply($result);
} catch (ConflictException $e) {
    echo $e->getMessage();
    // "Cannot apply merge with 3 unresolved conflicts"
}

Zawsze rozwiązuj konflikty przed zastosowaniem wyniku, używając ConflictResolver::resolve() albo ręcznie tworząc czysty obiekt MergeResult.