Why urlencode Won't Handle Your API's Specific Encoding Requirements
When building integrations with third-party APIs, you often encounter requests for "fully encoded" URLs. The standard expectation is to encode reserved characters like spaces, ampersands, and question marks using PHP's built-in functions. However, some legacy systems or specific API gateways demand a stricter interpretation where every characterâincluding alphanumeric ones, dots (.), and hyphens (-)âmust be represented by their percent-encoded equivalents.
Consider the input URL:http://test.site-raj.co/999999?lpp=1&px2=IjN
A standard encoding approach might yield something like http%3A//test.site-raj.co/999999?lpp%3D1&px2%3DIjN. While technically correct by RFC 3986 standards (where letters and digits are unreserved), your specific API requires this output:http%3a%2f%test%site%2draj%2eco%2f999999%3flpp%3d1%26px2%3dIjN
Notice that t, e, s, t, ., -, c, o are all percent-encoded. This is not standard URL encoding; it is a character-by-character hex conversion applied to the entire string, treating the URL as raw data rather than a parsed resource identifier.
The Limitation of Native PHP Functions
PHP provides robust tools for URL manipulation, but they operate based on semantic logic rather than blind character replacement. The urlencode() function is designed to encode query string parameters, escaping spaces as + and converting special characters like & to %26. It leaves alphanumeric characters untouched because the RFC 3986 specification defines them as "unreserved" characters that do not require encoding in most contexts.
Similarly, rawurlencode() is often the go-to for full URL encoding. It uses the %HH format and does not convert spaces to +, making it safer for embedding in headers or paths. However, it still respects the unreserved character set. Neither function will attempt to encode a dot or a hyphen unless you explicitly tell them to treat those characters as dangerous data.
Attempting to force these functions to encode every single character is possible but requires stripping the URL of its meaning first. You are essentially treating the URL string as an opaque blob of bytes, which contradicts how PHP's URL utilities normally function.
Implementing a Raw Character Map
To achieve the output format where a becomes %61, - becomes %2D, and . becomes %2E, you must bypass semantic parsing entirely. The most reliable way to do this in PHP is using mb_convert_encoding or a direct character-to-hex mapping via pack.
Using mb_convert_encoding with the "ISO-8859-1" (Latin-1) single-byte encoding often forces the conversion of every byte into its hex representation when combined with specific output filters, but it can be finicky with non-ASCII characters. A more deterministic approach for this specific requirement is to iterate through the string or use pack to convert the UTF-8 (or Latin-1) string directly into a hexadecimal string.
Here is a practical implementation pattern:
function fullyEncodedUrl($url) {
// Convert the input string to bytes, then pack them as hex
// This effectively encodes every character including dots and hyphens
$hexString = bin2hex($url);
// Insert '%' between every two hex digits
$encoded = '';
for ($i = 0; $i < strlen($hexString); $i += 2) {
$encoded .= '%' . substr($hexString, $i, 2);
}
return $encoded;
}
$input = 'http://test.site-raj.co/999999?lpp=1&px2=IjN';
$output = fullyEncodedUrl($input);
// Result: http%3a%2f%2f... (matching the required format)
This approach treats the input as a sequence of bytes. Since bin2hex outputs lowercase hex by default, ensure your API expects lowercase if that is a requirement (the source material shows lowercase 3a and 2f). The trade-off here is performance; this method processes every character individually in PHP loops or relies on string manipulation overhead compared to C-level library calls. For high-throughput APIs, you might need to consider using the pack function directly on large payloads if supported by your environment, though a simple loop remains readable and maintainable for most use cases.
Handling Encoding Collisions and Pitfalls
The primary risk with fully character-by-character encoding is collision. If your payload contains characters that are valid hex digits (like a, f, 0), they will be encoded as %61, %66, %30. This is generally safe, but if your downstream parser expects to decode this string back into a usable URL without knowing the original context, you risk breaking any internal logic that assumes hex digits remain unencoded.
Additionally, be wary of line breaks or newlines in the input string. If the API passes the encoded string through a network layer that interprets %0A as a newline, your payload could be truncated or misinterpreted. Always ensure the final encoded string is transmitted as a single continuous block without embedded whitespace.
If you are working within the Laravel ecosystem and need to handle this for multiple endpoints, consider creating a reusable service trait or helper method to centralize this logic. While Laravel offers excellent tools for URL building (url(), route()), none of these will produce the raw hex representation required by such strict APIs without custom intervention. You might explore packages like laravelcompany.com's suggested utilities if you need pre-built wrappers, but understanding the underlying byte conversion is essential to debugging why an integration fails silently.
Final Verification
Before deploying this solution, validate the output against the API's specification. Some APIs claim to want "encoded URLs" but actually accept standard RFC 3986 compliant strings where dots and hyphens are unreserved. Blindly encoding every character as shown above can render a URL unusable in standard browsers or other HTTP clients that expect to parse it back into a valid resource path. Always confirm whether the API expects this specific format or if they simply misunderstand RFC 3986 rules regarding reserved characters.