curl_unescape — Funktion · PHP-Referenz

Signatur

curl_unescape(CurlHandle $handle, string $string): string|false

Beschreibung

curl_unescape() dekodiert einen URL-kodierten String (Percent-Encoding gemäß RFC 3986) unter Verwendung der internen cURL-Bibliothek. Die Funktion wandelt Sequenzen wie %2F oder %20 in ihre entsprechenden Zeichen zurück und behandelt auch +-Zeichen nicht als Leerzeichen – im Gegensatz zu urldecode() oder rawurldecode().

Ein gültiges cURL-Handle ist erforderlich, da die Funktion die interne cURL-Implementierung zur Dekodierung nutzt. Das Handle muss zuvor mit curl_init() erstellt worden sein. Dies ist besonders dann sinnvoll, wenn man ohnehin mit cURL arbeitet und eine konsistente URL-Dekodierung innerhalb desselben Kontexts benötigt.

Die Funktion eignet sich gut für die Verarbeitung von URL-Komponenten, die per cURL-Request empfangen wurden, zum Beispiel Redirect-URLs oder Query-Parameter aus Antwort-Headern. Für allgemeine URL-Dekodierung ohne cURL-Kontext sind urldecode() oder rawurldecode() die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	CurlHandle		Ein gültiges cURL-Handle, das zuvor mit `curl_init()` erstellt wurde.
$string Pflicht	string		Der URL-kodierte String, der dekodiert werden soll. Percent-kodierte Sequenzen wie `%20` oder `%C3%A4` werden in ihre ursprünglichen Zeichen umgewandelt.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den dekodierter String zurück. Im Fehlerfall (z. B. ungültiges Handle) wird false zurückgegeben.

Beispiele

Einfaches Dekodieren einer URL-kodierten Zeichenkette

<?php
$ch = curl_init();

$encoded = 'Hallo%20Welt%21%20%C3%84rger%20%26%20Spa%C3%9F';
$decoded = curl_unescape($ch, $encoded);

echo $decoded;

curl_close($ch);

Hallo Welt! Ärger & Spaß

Dekodieren einer Redirect-URL aus einem cURL-Response

<?php
$ch = curl_init('https://example.com/redirect');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($ch, CURLOPT_HEADER, true);

$response = curl_exec($ch);

// Redirect-URL aus dem Location-Header extrahieren
if (preg_match('/^Location:\s*(.+)$/mi', $response, $matches)) {
    $locationEncoded = trim($matches[1]);
    $locationDecoded = curl_unescape($ch, $locationEncoded);
    echo 'Weiterleitungsziel: ' . $locationDecoded . PHP_EOL;
}

curl_close($ch);

Vergleich mit rawurldecode: Unterschied bei +-Zeichen

<?php
$ch = curl_init();

$encoded = 'foo+bar%20baz';

// curl_unescape behandelt '+' NICHT als Leerzeichen
echo curl_unescape($ch, $encoded) . PHP_EOL;

// rawurldecode ebenfalls nicht
echo rawurldecode($encoded) . PHP_EOL;

// urldecode hingegen schon
echo urldecode($encoded) . PHP_EOL;

curl_close($ch);

foo+bar baz foo+bar baz foo bar baz

// Wichtig · Fallstricke

Achtung: Im Gegensatz zu urldecode() wird das +-Zeichen von curl_unescape() nicht als Leerzeichen interpretiert. Dies entspricht dem Verhalten von rawurldecode() und dem RFC-3986-Standard. Wer Query-Strings aus HTML-Formularen dekodiert, sollte daher urldecode() bevorzugen.

Die Funktion gibt false zurück, wenn das cURL-Handle ungültig ist. Das Ergebnis sollte daher mit === auf false geprüft werden, da ein leerer String ebenfalls ein gültiges Ergebnis sein kann.

Ab PHP 8.0 ist der Parameter $handle vom Typ CurlHandle (Objekt), in früheren PHP-Versionen war es eine Ressource.

Siehe auch

curl_escape curl_init urldecode rawurldecode rawurlencode