rawurlencode
Percent-encodes a string according to RFC 3986, encoding spaces as %20.
rawurlencode(string $string): string- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The string to be encoded. |
Return value
stringA string in which all characters except A-Z, a-z, 0-9 and -_.~ are replaced with a percent sign followed by two hex digits.
Errors
Does not throw.
rawurlencode() is the RFC 3986 encoder: everything outside A-Z a-z 0-9 - _ . ~ becomes % plus two hex digits, and a space becomes %20. That makes it the right tool for path segments, where a literal + means a plus sign and not a space.
rawurlencode or urlencode?
Use rawurlencode() for anything that is not an HTML form field: path segments, filenames in a URL, values inside an Authorization header, OAuth signature base strings, and anywhere a non-PHP consumer will read the value. Use urlencode() only when you are imitating browser form submission. The two differ in exactly two places: the space character, and the treatment of ~, which rawurlencode() leaves alone.
Encode the parts, never the whole
Encoding a complete URL destroys it — the :, /, ? and & that give it structure all become percent escapes. Build the URL from encoded pieces instead. And encode each path segment separately, because a / inside a single segment must become %2F rather than staying a directory separator.
The function is byte-oriented: multibyte UTF-8 characters simply become several percent escapes.
Example
When to use it
- Put a filename containing spaces or slashes into a URL path segment
- Build the signature base string for an OAuth 1.0 or AWS request
- Encode a tag or username that will appear in a pretty permalink
- Escape a value going into a Location or Content-Disposition header
Frequently asked questions
What is the difference between rawurlencode and urlencode?
rawurlencode follows RFC 3986 and encodes a space as %20, leaving ~ untouched; urlencode encodes a space as + and escapes ~ as %7E. Use rawurlencode for path segments and headers, urlencode for HTML form-style data.
Can I run rawurlencode on a full URL?
No. It would escape the ://, / and ? characters that give the URL its structure. Encode individual segments and parameter values instead.
Which characters does rawurlencode leave unchanged?
Letters, digits, and the four unreserved characters - _ . ~ . Everything else, including spaces and UTF-8 bytes, becomes a percent escape.
More examples
Encoding each path segment separately
Mapping over the segments keeps the real / separators intact while escaping the / inside "r/w guide.pdf" as %2F. The second line shows the mistake: every structural slash became %2F, producing a single meaningless path segment.
<?php
$segments = ['docs', 'url & encoding', 'r/w guide.pdf'];
$path = '/' . implode('/', array_map('rawurlencode', $segments));
echo 'https://example.com' . $path, "\n";
// Encoding the joined path instead would wrongly escape the separators.
echo rawurlencode('/' . implode('/', $segments)), "\n";The exact difference from urlencode
Only two rows differ: a space becomes %20 with rawurlencode but + with urlencode, and ~ is left alone by rawurlencode while urlencode escapes it to %7E. Everything else, including the alphanumeric-safe -, _ and ., is identical.
<?php
$chars = [' ', '+', '~', '/', '&', '=', '.', '-', '_'];
foreach ($chars as $c) {
printf("%-3s raw=%-3s url=%-3s\n", var_export($c, true), rawurlencode($c), urlencode($c));
}Building a query string by hand, correctly
Both lines produce q=a%2Bb%20%26%20c&lang=en-GB. The literal + in the value is escaped to %2B so the receiver does not read it as a space, and the & inside the value becomes %26 so it cannot split the pair.
<?php
$params = ['q' => 'a+b & c', 'lang' => 'en-GB'];
$pairs = [];
foreach ($params as $k => $v) {
$pairs[] = rawurlencode($k) . '=' . rawurlencode($v);
}
echo implode('&', $pairs), "\n";
// http_build_query with RFC 3986 does the same thing in one call.
echo http_build_query($params, '', '&', PHP_QUERY_RFC3986), "\n";
Discussion