eio_rename — Funktion · PHP-Referenz

Signatur

eio_rename(string $path, string $new_path, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource|false

Beschreibung

eio_rename() ist Teil der EIO-Erweiterung (Async I/O) und führt die POSIX-Operation rename(2) asynchron im Hintergrund aus. Damit lässt sich eine Datei oder ein Verzeichnis umbenennen oder an einen anderen Ort im Dateisystem verschieben, ohne den PHP-Prozess zu blockieren.

Im Gegensatz zur synchronen Funktion rename() gibt eio_rename() sofort eine Anfrage-Ressource zurück und benachrichtigt den Aufrufer über den Abschluss der Operation via Callback-Funktion. Dies ist besonders in Event-Loop-basierten Anwendungen (z. B. mit event- oder libevent-Erweiterung) nützlich, um hohe I/O-Parallelität zu erreichen.

Der Callback erhält drei Parameter: $data (benutzerdefinierte Daten), $result (0 bei Erfolg, -1 bei Fehler) und $req (die Anfrage-Ressource). Im Fehlerfall kann eio_get_last_error($req) oder eio_get_errno($req) zur Fehleranalyse verwendet werden.

Die EIO-Erweiterung muss separat installiert sein (PECL) und erfordert typischerweise die Integration in eine Event-Loop, damit die Anfragen tatsächlich abgearbeitet werden.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zur Quelldatei oder zum Quellverzeichnis, das umbenannt oder verschoben werden soll.
$new_path Pflicht	string		Neuer Pfad (Zielname oder Zielort). Liegt der Zielort auf einem anderen Dateisystem, schlägt die Operation fehl.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback	callable	NULL	Wird aufgerufen, sobald die Operation abgeschlossen ist. Signatur: `callback(mixed $data, int $result, resource $req): void`. `$result` ist 0 bei Erfolg, -1 bei Fehler.
$data	mixed	NULL	Beliebige benutzerdefinierte Daten, die unverändert an den Callback übergeben werden.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt eine EIO-Anfrage-Ressource zurück, wenn die Anfrage erfolgreich in die Warteschlange eingereiht wurde, oder false bei einem Fehler.

Beispiele

Datei asynchron umbenennen

<?php
// EIO-Event-Loop initialisieren
eio_init();

$sourcePath = '/tmp/old_name.txt';
$targetPath = '/tmp/new_name.txt';

// Quelldatei anlegen
file_put_contents($sourcePath, 'Testinhalt');

$req = eio_rename(
    $sourcePath,
    $targetPath,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === 0) {
            echo "Datei erfolgreich umbenannt zu: " . $data['target'] . PHP_EOL;
        } else {
            echo "Fehler beim Umbenennen: " . eio_get_last_error($req) . PHP_EOL;
        }
    },
    ['target' => $targetPath]
);

// Event-Loop ausführen, bis alle Anfragen abgearbeitet sind
eio_event_loop();

Datei erfolgreich umbenannt zu: /tmp/new_name.txt

Datei asynchron in ein anderes Verzeichnis verschieben

<?php
eio_init();

$source = '/tmp/upload_temp_abc123.jpg';
$destination = '/var/www/uploads/final_image.jpg';

// Temporäre Quelldatei simulieren
file_put_contents($source, 'Bilddaten...');

eio_rename(
    $source,
    $destination,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === 0) {
            echo "Datei verschoben: {$data['from']} -> {$data['to']}" . PHP_EOL;
        } else {
            echo "Fehler (errno " . eio_get_errno($req) . "): " . eio_get_last_error($req) . PHP_EOL;
        }
    },
    ['from' => $source, 'to' => $destination]
);

eio_event_loop();

Datei verschoben: /tmp/upload_temp_abc123.jpg -> /var/www/uploads/final_image.jpg

// Wichtig · Fallstricke

Dateisystemgrenzen: eio_rename() kann eine Datei nicht über Dateisystemgrenzen hinweg verschieben (analog zu rename(2) unter POSIX). In diesem Fall gibt eio_get_errno() den Fehlercode EXDEV zurück. Als Workaround muss die Datei erst kopiert (eio_sendfile()) und dann gelöscht werden.

Callback ist entscheidend: Ohne korrekte Event-Loop-Integration (z. B. eio_event_loop() oder libevent-Integration) wird der Callback möglicherweise nie aufgerufen. Stelle sicher, dass die Event-Loop läuft.

Sicherheit: Pfade sollten vor der Übergabe validiert und kanonisiert werden (z. B. mit realpath()), um Path-Traversal-Angriffe zu vermeiden, falls Benutzereingaben in die Pfade einfließen.

PECL-Abhängigkeit: Die EIO-Erweiterung ist nicht standardmäßig in PHP enthalten und muss über PECL installiert werden (pecl install eio).

Siehe auch

eio_init eio_unlink eio_mkdir eio_get_last_error eio_get_errno eio_event_loop rename