xdiff_file_patch — Funktion · PHP-Referenz

Signatur

xdiff_file_patch(string $file, string $patch, string $dest, int $flags = XDIFF_PATCH_NORMAL): mixed

Beschreibung

xdiff_file_patch() liest eine Quelldatei und einen Patch im Unified-Diff-Format ein, wendet die im Patch beschriebenen Änderungen an und schreibt das Ergebnis in die angegebene Zieldatei. Die Funktion gehört zur PECL-Erweiterung xdiff und ist besonders nützlich für Deployments, Versionierung oder automatisierte Patch-Workflows.

Der Patch muss im Unified-Diff-Format vorliegen, wie es etwa von diff -u oder xdiff_file_diff() erzeugt wird. Über den Parameter flags kann gesteuert werden, ob vorwärts (XDIFF_PATCH_NORMAL) oder rückwärts (XDIFF_PATCH_REVERSE) gepatcht wird – letzteres macht einen bereits angewandten Patch rückgängig.

Im Erfolgsfall gibt die Funktion true zurück. Falls einzelne Hunks (Diff-Blöcke) nicht angewendet werden konnten, wird ein string mit den abgelehnten Hunks zurückgegeben. Bei einem vollständigen Fehler ist der Rückgabewert false.

Zu beachten ist, dass diese Funktion nur mit Textdateien sinnvoll eingesetzt werden kann. Für binäre Daten stehen xdiff_file_bdiff() und xdiff_file_bpatch() zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$file Pflicht	string		Pfad zur Originaldatei, auf die der Patch angewendet werden soll.
$patch Pflicht	string		Pfad zur Patch-Datei im Unified-Diff-Format (z. B. erzeugt durch `xdiff_file_diff()` oder `diff -u`).
$dest Pflicht	string		Pfad zur Zieldatei, in die das gepatchte Ergebnis geschrieben wird. Wenn die Datei bereits existiert, wird sie überschrieben.
$flags	int	XDIFF_PATCH_NORMAL	Steuert die Patch-Richtung: `XDIFF_PATCH_NORMAL` (vorwärts, Standard) oder `XDIFF_PATCH_REVERSE` (rückwärts, macht einen Patch rückgängig).

Rückgabewert

Typ

mixed

Beschreibung

Gibt true zurück, wenn der Patch vollständig angewendet wurde. Gibt einen string mit den nicht anwendbaren Hunks zurück, wenn nur ein Teil des Patches erfolgreich war. Gibt false zurück, wenn ein vollständiger Fehler aufgetreten ist (z. B. Datei nicht lesbar).

Beispiele

Patch auf eine Textdatei anwenden

<?php
// Voraussetzung: PECL-Erweiterung xdiff ist installiert

// Original- und Patch-Datei definieren
$originalFile = '/tmp/original.txt';
$patchFile    = '/tmp/changes.patch';
$resultFile   = '/tmp/patched.txt';

// Patch anwenden
$result = xdiff_file_patch($originalFile, $patchFile, $resultFile);

if ($result === true) {
    echo "Patch erfolgreich angewendet. Ergebnis in: $resultFile\n";
} elseif (is_string($result)) {
    echo "Patch teilweise angewendet. Abgelehnte Hunks:\n" . $result;
} else {
    echo "Fehler beim Anwenden des Patches.\n";
}

Patch erfolgreich angewendet. Ergebnis in: /tmp/patched.txt

Patch rückgängig machen (Reverse Patch)

<?php
// Einen bereits angewandten Patch rückgängig machen

$patchedFile = '/tmp/patched.txt';
$patchFile   = '/tmp/changes.patch';
$restoredFile = '/tmp/restored.txt';

$result = xdiff_file_patch($patchedFile, $patchFile, $restoredFile, XDIFF_PATCH_REVERSE);

if ($result === true) {
    echo "Patch erfolgreich rückgängig gemacht. Original wiederhergestellt in: $restoredFile\n";
} elseif (is_string($result)) {
    echo "Rückwärts-Patch nur teilweise angewendet. Abgelehnte Hunks:\n" . $result;
} else {
    echo "Fehler beim Rückgängigmachen des Patches.\n";
}

Patch erfolgreich rückgängig gemacht. Original wiederhergestellt in: /tmp/restored.txt

// Wichtig · Fallstricke

PECL-Erweiterung: xdiff_file_patch() ist Teil der PECL-Erweiterung xdiff und nicht in der Standard-PHP-Distribution enthalten. Die Erweiterung muss separat installiert werden (pecl install xdiff).

Nur für Textdateien: Diese Funktion arbeitet ausschließlich mit Textdateien. Für binäre Dateien sollten xdiff_file_bdiff() und xdiff_file_bpatch() verwendet werden.

Sicherheitshinweis: Wenn Pfade oder Patch-Inhalte aus Benutzereingaben stammen, müssen diese sorgfältig validiert und bereinigt werden, um Path-Traversal-Angriffe oder das ungewollte Überschreiben von Systemdateien zu verhindern.

Veraltung: Die xdiff-Erweiterung wird nicht mehr aktiv gewartet und steht auf älteren PECL-Versionen möglicherweise nicht für neuere PHP-Versionen zur Verfügung. Für neue Projekte sollte der Einsatz von Alternativen wie dem Shell-Befehl patch oder spezialisierten Bibliotheken erwogen werden.

Siehe auch

xdiff_file_diff xdiff_string_patch xdiff_file_bdiff xdiff_file_bpatch xdiff_file_diff_binary