convert_uuencode()

Purpose

convert_uuencode() converts a string into the classic uuencode format. Uuencode maps any bytes, including binary data, onto a small set of printable ASCII characters. That made the data safe to send over channels that only handled text, such as old mail systems. Today you will mostly meet it when reading legacy data or talking to older tools. For new designs, base64_encode() is usually the better choice.

The function encodes only the data. It does not write the begin line or the end line that a complete uuencoded file contains. If you need a full file-style block, you must add those lines yourself.

Signature

Parameters and defaults

• $string: the data to encode. It can hold text or arbitrary binary bytes. There are no other parameters and no default values.

Because the function works on bytes, a multibyte UTF-8 string is encoded byte by byte. The result can be decoded back to the same bytes with convert_uudecode().

Return value and failure cases

The function returns the uuencoded data as a string. The output is organised in lines. Each line starts with one character that encodes how many input bytes the line holds, followed by the encoded groups, then a newline. A final line containing a single backtick ends the data. The manual notes that the encoded data is about 35% larger than the original.

The zero value is written as a backtick instead of a space, which is why backticks appear often in the output.

The function has no documented error return in PHP 8. Before PHP 8.0.0, passing an empty string returned false for no particular reason. Since 8.0.0 you can rely on the return type being string. If you pass a non-string value under declare(strict_types=1), PHP raises a TypeError like any other typed built-in.

Example 1: the manual-style sample

The input below contains a newline and a carriage return plus newline. The first character of the output, 0, encodes a length of 16 bytes. The last line is the lone backtick terminator.

<?php
$some_string = "test\ntext text\r\n";

echo convert_uuencode($some_string);

0=&5S=`IT97AT('1E>'0-"@``
`

Example 2: seeing the exact bytes

Printing uuencoded text directly can be confusing, because it contains quotes, backticks and newlines. Encoding the result as JSON makes the line breaks visible as \n. For the three bytes abc, the length character is # (3 bytes), followed by the four characters 86)C, a newline, and the terminator line.

<?php
echo json_encode(convert_uuencode("abc"), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

"#86)C\n`\n"

Example 3: line length and round trip

Uuencode splits long input into lines of up to 45 input bytes. A 45-byte line begins with M. With 50 bytes of input, the first line holds 45 bytes (62 characters including the newline), the second holds 5 bytes (10 characters), and the terminator adds 2 more, giving 74. The data survives a round trip through convert_uudecode().

<?php
$data = str_repeat("A", 50);
$encoded = convert_uuencode($data);
echo json_encode([
    "encodedLength" => strlen($encoded),
    "firstChar" => $encoded[0],
    "roundTrip" => convert_uudecode($encoded) === $data,
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

{"encodedLength":74,"firstChar":"M","roundTrip":true}

Edge cases

• Binary input is fine. The function does not care about character encodings, so null bytes and high bytes are encoded like any others.
• Length is not constant per character. Groups of three input bytes become four output characters, but each line adds a length character and a newline, and the data ends with the terminator line. Do not estimate sizes with a fixed multiplier when you need an exact number.
• Padding. When the input length is not a multiple of three, the last group is padded internally, and the line's length character tells a decoder how many bytes are real.
• Newlines in the output. The result always contains newline characters. If you embed it in JSON, a log line or a header, escape or wrap it appropriately.

Common mistakes

1. Expecting a complete uuencoded file. The function adds no begin or end lines and no file mode or name.
2. Treating it as encryption. Uuencode is only a reversible representation. Anyone can decode it.
3. Trimming the output. The trailing backtick line and newlines are part of the encoded data. Removing them can break decoding.
4. Mixing it up with Base64. The two formats use different alphabets. Data from convert_uuencode() must be decoded with convert_uudecode(), not base64_decode().
5. Choosing it for new web APIs. Base64 is more widely supported, so prefer it unless you must match an existing uuencode consumer.
6. Comparing displayed output by eye. Backticks, quotes and control characters are easy to misread. Use json_encode() or bin2hex() when debugging.

Related functions

• convert_uudecode(): decodes uuencoded data back to the original string.
• base64_encode(): the more common text-safe encoding for binary data.
• bin2hex(): another way to show bytes as printable characters.
• strlen(): useful when checking the size overhead of an encoding.

Recap

convert_uuencode(string $string): string turns any byte string into printable uuencoded lines, ending with a lone backtick line. It adds no begin or end lines, grows the data by roughly a third, and always returns a string in PHP 8. Pair it with convert_uudecode() for round trips, and prefer Base64 for new work.