Download the PHP package ideil/binary-to-text-php without Composer

Binary-to-Text Utilities for PHP

For now, the only class in this repository is Base2n.

Base2n is for binary-to-text conversion with arbitrary encoding schemes that represent binary data in a base 2ⁿ notation. It can handle non-standard variants of many standard encoding schemes such as Base64 and Base32. Many binary-to-text encoding schemes use a fixed number of bits of binary data to generate each encoded character. Such schemes generalize to a single algorithm, implemented here.

Binary-to-text encoding is usually used to represent data in a notation that is safe for transport over text-based protocols, and there are several other practical uses. See the examples below.

Basic Base2n Usage

With Base2n, you define your encoding scheme parametrically. Let's instantiate a Base32 encoder:

Constructor Parameters

• integer $bitsPerCharacter Required. The number of bits to use for each encoded character; 1–8. The most practical range is 1–6. The encoding's radix is a power of 2: 2^$bitsPerCharacter.

  1. base-2, binary
  2. base-4, quaternary
  3. base-8, octal
  4. base-16, hexadecimal
  5. base-32
  6. base-64
  7. base-128
  8. base-256

• string $chars This string specifies the base alphabet. Must be 2^$bitsPerCharacter long. Default: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_

• boolean $caseSensitive To decode in a case-sensitive manner. Default: FALSE

• boolean $rightPadFinalBits How to encode the last character when the bits remaining are fewer than $bitsPerCharacter. When TRUE, the bits to encode are placed in the most significant position of the final group of bits, with the lower bits set to 0. When FALSE, the final bits are placed in the least significant position. For RFC 4648 encodings, $rightPadFinalBitsshould be TRUE. Default: FALSE

• boolean $padFinalGroup It's common to encode characters in groups. For example, Base64 (which is based on 6 bits per character) converts 3 raw bytes into 4 encoded characters. If insufficient bytes remain at the end, the final group will be padded with = to complete a group of 4 characters, and the encoded length is always a multiple of 4. Although the information provided by the padding is redundant, some programs rely on it for decoding; Base2n does not. Default: FALSE

• string $padCharacter When $padFinalGroup is TRUE, this is the pad character used. Default: =

encode() Parameters

• string $rawString Required. The data to be encoded.

decode() Parameters

• string $encodedString Required. The string to be decoded.
• boolean $strict When TRUE, NULL will be returned if $encodedString contains an undecodable character. When FALSE, unknown characters are simply ignored. Default: FALSE

Examples

PHP does not provide any Base32 encoding functions. By setting $bitsPerCharacter to 5 and specifying your desired alphabet in $chars, you can handle any variant of Base32:

Octal notation:

A convenient way to go back and forth between binary notation and its real binary representation:

PHP uses a proprietary binary-to-text encoding scheme to generate session identifiers from random hash digests. The most efficient way to store these session IDs in a database is to decode them back to their raw hash digests. PHP's encoding scheme is configured with the session.hash_bits_per_character php.ini setting. The decoded size depends on the hash function, set with session.hash_function in php.ini.

Generate random security tokens:

The rest of these examples are probably more fun than they are practical.

We can encode arbitrary data with a 7-bit encoding. (Note that this is not the same as the 7bit MIME content-transfer-encoding.)

The following encoding guarantees that the most significant bit is set for every byte:

Let's create an encoding using exclusively non-printable control characters!

Why not encode data using only whitespace? Here's a base-4 encoding using space, tab, new line, and carriage return:

Counterexamples

Base2n is not slow, but it will never outperform an encoding function implemented in C. When one exists, use it instead.

PHP provides the base64_encode() and base64_decode() functions, and you should always use them for standard Base64. When you need to use a modified alphabet, you can translate the encoded output with strtr() or str_replace().

A common variant of Base64 is modified for URLs and filenames, where + and / are replaced with - and _, and the = padding is omitted. It's better to handle this variant with native PHP functions:

Native functions get slightly more cumbersome when every position in the alphabet has changed, as seen in this example of decoding a Bcrypt hash:

You can encode and decode hexadecimal with bin2hex() and pack():