fbird_restore — Funktion · PHP-Referenz

Signatur

fbird_restore(resource $service_handle, string $source_file, string $dest_db, int $options = 0, bool $verbose = false): mixed

Beschreibung

fbird_restore() ist ein Alias für ibase_restore() und ermöglicht es, eine zuvor mit fbird_backup() bzw. ibase_backup() erstellte Sicherungsdatei in eine neue oder vorhandene Firebird/InterBase-Datenbank zurückzuspielen. Die Funktion kommuniziert dabei über das Firebird Service-API direkt mit dem Datenbankserver.

Voraussetzung für den Aufruf ist ein gültiges Service-Handle, das mit ibase_service_attach() geöffnet wurde. Quell- und Zieldatei werden als serverseitige Pfade angegeben – der PHP-Prozess selbst greift nicht direkt auf die Dateien zu, sondern delegiert den Vorgang vollständig an den Firebird-Dienst.

Über den Parameter $options lässt sich das Verhalten der Wiederherstellung steuern, z. B. ob eine bestehende Zieldatenbank überschrieben werden soll (IBASE_RES_CREATE). Mit $verbose = true gibt die Funktion Fortschritts- und Statusinformationen zurück, die für Logging oder Diagnose genutzt werden können.

Diese Funktion ist besonders nützlich in Wartungsskripten, Migrations-Szenarien oder bei der Einrichtung von Testumgebungen, in denen eine Produktionsdatenbank schnell wiederhergestellt werden muss.

Parameter

Name	Typ	Default	Beschreibung
$service_handle Pflicht	resource		Ein gültiges Firebird/InterBase-Service-Handle, das zuvor mit `ibase_service_attach()` geöffnet wurde.
$source_file Pflicht	string		Der vollständige serverseitige Pfad zur Sicherungsdatei (z. B. `/var/backups/mydb.fbk`), die wiederhergestellt werden soll.
$dest_db Pflicht	string		Der vollständige serverseitige Pfad oder Datenbankname der Zieldatenbank, in die die Sicherung eingespielt wird (z. B. `/var/db/mydb_restored.fdb`).
$options	int	0	Bitmaske aus Optionskonstanten. Mögliche Werte sind z. B. `IBASE_RES_CREATE` (Datenbank neu anlegen), `IBASE_RES_REPLACE` (bestehende Datenbank überschreiben) oder `IBASE_RES_NO_SHADOW`. Mehrere Optionen werden mit `\|` verknüpft.
$verbose	bool	false	Wenn `true`, werden Fortschrittsinformationen des Restore-Prozesses als Zeichenkette zurückgegeben. Nützlich für Logging und Diagnose.

Rückgabewert

Typ

mixed

Beschreibung

Gibt bei $verbose = false true bei Erfolg zurück. Bei $verbose = true wird ein String mit den Ausgaben des Wiederherstellungsprozesses zurückgegeben. Im Fehlerfall wird false zurückgegeben.

Beispiele

Einfache Wiederherstellung einer Datenbank

<?php
// Service-Verbindung aufbauen
$service = ibase_service_attach('localhost', 'sysdba', 'masterkey');

if ($service === false) {
    die('Service-Verbindung fehlgeschlagen.');
}

// Datenbank aus Sicherungsdatei wiederherstellen
$result = fbird_restore(
    $service,
    '/var/backups/mydb.fbk',
    '/var/db/mydb_restored.fdb',
    IBASE_RES_CREATE
);

if ($result === true) {
    echo 'Datenbank erfolgreich wiederhergestellt.';
} else {
    echo 'Fehler bei der Wiederherstellung.';
}

ibase_service_detach($service);

Datenbank erfolgreich wiederhergestellt.

Wiederherstellung mit ausführlicher Ausgabe (verbose)

<?php
// Service-Verbindung aufbauen
$service = ibase_service_attach('localhost', 'sysdba', 'masterkey');

if ($service === false) {
    die('Service-Verbindung fehlgeschlagen.');
}

// Restore mit verbose-Ausgabe zur Diagnose
$log = fbird_restore(
    $service,
    '/var/backups/mydb.fbk',
    '/var/db/mydb_restored.fdb',
    IBASE_RES_REPLACE,
    true
);

if ($log !== false) {
    echo "Restore-Protokoll:\n";
    echo $log;
} else {
    echo 'Fehler bei der Wiederherstellung.';
}

ibase_service_detach($service);

Restore-Protokoll: gbak:opened file /var/backups/mydb.fbk gbak:created database /var/db/mydb_restored.fdb gbak:restoring domain ... gbak:finishing, closing, and going home

// Wichtig · Fallstricke

Deprecation-Hinweis: Die fbird_*-Funktionen (einschließlich fbird_restore()) sind Aliase der ibase_*-Funktionen aus der InterBase-Erweiterung. Ab PHP 8.0 wurde die InterBase-Erweiterung aus dem PHP-Kern entfernt. Für PHP 8+ steht die externe PECL-Erweiterung ibase oder alternativ die Firebird PDO-Erweiterung (PDO_Firebird) zur Verfügung.

Sicherheit: Die Pfadangaben für Quell- und Zieldatei werden serverseitig interpretiert. Werden diese Werte aus Benutzereingaben bezogen, besteht ein erhebliches Risiko für Path-Traversal-Angriffe. Pfade sollten grundsätzlich hart kodiert oder strikt validiert werden.

Berechtigungen: Der Firebird-Dienst benötigt Lese- und Schreibberechtigungen auf die angegebenen Pfade. PHP selbst muss keine Dateisystemrechte auf diese Dateien besitzen, da der Vorgang serverseitig durch den Firebird-Dienst ausgeführt wird.

Siehe auch

ibase_restore fbird_backup ibase_service_attach ibase_service_detach ibase_backup