curl_escape — Funktion · PHP-Referenz

Signatur

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

Beschreibung

curl_escape() kodiert einen beliebigen String so, dass er sicher als URL-Komponente (z. B. Query-Parameter-Wert) verwendet werden kann. Die Kodierung folgt RFC 3986 (Percent-Encoding): Alle Zeichen außer den unreservierten Zeichen (A–Z, a–z, 0–9, -, _, ., ~) werden als %XX-Sequenz kodiert.

Im Gegensatz zu urlencode() kodiert diese Funktion Leerzeichen als %20 statt als + und ist daher besonders geeignet, wenn cURL-Requests strikt RFC-3986-konform sein müssen. Die Funktion benötigt ein gültiges cURL-Handle, da sie intern die libcurl-Bibliothek nutzt.

Typischer Einsatz: Vorbereitung von Werten für Query-Strings oder Pfadsegmente in cURL-basierten HTTP-Requests, insbesondere bei REST-APIs, die eine strikte Percent-Encoding-Konformität erwarten.

Das Gegenstück zum Dekodieren ist curl_unescape().

Parameter

Name	Typ	Default	Beschreibung
$handle Pflicht	CurlHandle		Ein aktives cURL-Handle, wie es von `curl_init()` zurückgegeben wird. Die Funktion verwendet libcurl intern für die Kodierung.
$string Pflicht	string		Der zu kodierende String. Alle nicht-unreservierten Zeichen (gemäß RFC 3986) werden als `%XX`-Sequenz dargestellt.

Rückgabewert

Typ

string|false

Beschreibung

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

Beispiele

Einfache URL-Kodierung eines Suchbegriffs

<?php
$ch = curl_init();

$suchbegriff = 'Hallo Welt! & mehr';
$kodiert = curl_escape($ch, $suchbegriff);

echo $kodiert;
// Ausgabe: Hallo%20Welt%21%20%26%20mehr

curl_close($ch);

Hallo%20Welt%21%20%26%20mehr

Verwendung in einem cURL GET-Request mit kodierten Parametern

<?php
$ch = curl_init();

$basisUrl = 'https://api.example.com/suche';
$parameter = [
    'q'    => 'PHP & cURL',
    'lang' => 'de',
    'seite' => '1',
];

$queryTeile = [];
foreach ($parameter as $schluessel => $wert) {
    $queryTeile[] = curl_escape($ch, $schluessel) . '=' . curl_escape($ch, $wert);
}

$url = $basisUrl . '?' . implode('&', $queryTeile);
echo $url;
// Ausgabe: https://api.example.com/suche?q=PHP%20%26%20cURL&lang=de&seite=1

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$antwort = curl_exec($ch);
curl_close($ch);

https://api.example.com/suche?q=PHP%20%26%20cURL&lang=de&seite=1

// Wichtig · Fallstricke

Unterschied zu urlencode(): urlencode() kodiert Leerzeichen als + (application/x-www-form-urlencoded), während curl_escape() sie als %20 kodiert (RFC 3986). Für REST-APIs ist curl_escape() in der Regel die korrekte Wahl.

Unterschied zu rawurlencode(): rawurlencode() folgt ebenfalls RFC 3986 und liefert das gleiche Ergebnis – ohne jedoch ein cURL-Handle zu benötigen. Wenn kein cURL-Handle vorhanden ist, kann rawurlencode() als Alternative verwendet werden.

Verfügbarkeit: Die Funktion setzt voraus, dass PHP mit libcurl kompiliert wurde und ein gültiges Handle übergeben wird. Ab PHP 8.0 ist der Parameter-Typ CurlHandle (vorher resource).

Siehe auch

curl_unescape curl_init rawurlencode urlencode http_build_query