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<sup>
n</sup> notation. It can handle non-standard variants of many standard encoding schemes such as [Base64][rfc4648base64]
and [Base32][rfc4648base32]. 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.

[rfc4648base64]:    http://tools.ietf.org/html/rfc4648#section-4 "RFC 4648 Base64 Specification"

[rfc4648base32]:    http://tools.ietf.org/html/rfc4648#section-6 "RFC 4648 Base32 Specification"

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][rfc4648base32] encoder:

```php
// RFC 4648 base32 alphabet; case-insensitive
$base32 = new Base2n(5, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567', FALSE, TRUE, TRUE);
$encoded = $base32->encode('encode this');
// MVXGG33EMUQHI2DJOM======
```

### Constructor Parameters

- <code>integer $bitsPerCharacter</code> **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: <code>2^$bitsPerCharacter</code>.
    1. [base-2, binary][binary]
    2. [base-4, quaternary][quaternary]
    3. [base-8, octal][octal]
    4. [base-16, hexadecimal][hexadecimal]
    5. [base-32][base32]
    6. [base-64][base64]
    7. base-128
    8. base-256

[binary]:       http://en.wikipedia.org/wiki/Binary_numeral_system "Binary Notation"

[quaternary]:   http://en.wikipedia.org/wiki/Quaternary_numeral_system "Base-2 Notation"

[octal]:        http://en.wikipedia.org/wiki/Octal "Octal Notation"

[hexadecimal]:  http://en.wikipedia.org/wiki/Base16 "Hexadecimal Notation"

[base32]:       http://en.wikipedia.org/wiki/Base32 "Base32 Encoding"

[base64]:       http://en.wikipedia.org/wiki/Base64 "Base64 Encoding"

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

- <code>boolean $caseSensitive</code> To decode in a case-sensitive manner. Default: <code>FALSE</code>

- <code>boolean $rightPadFinalBits</code> How to encode the last character when the bits remaining are fewer than <code>
  $bitsPerCharacter</code>. When <code>TRUE</code>, the bits to encode are placed in the most significant position of
  the final group of bits, with the lower bits set to <code>0</code>. When <code>FALSE</code>, the final bits are placed
  in the least significant position. For [RFC 4648][rfc4648] encodings, <code>$rightPadFinalBits</code>should be <code>
  TRUE</code>. Default: <code>FALSE</code>

[rfc4648]:  http://tools.ietf.org/html/rfc4648 "RFC 4648: Base16, Base32, Base64"

- <code>boolean $padFinalGroup</code> 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 <code>=</code> 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: <code>FALSE</code>

- <code>string $padCharacter</code> When <code>$padFinalGroup</code> is <code>TRUE</code>, this is the pad character
  used. Default: <code>=</code>

### <code>encode()</code> Parameters

- <code>string $rawString</code> **Required**. The data to be encoded.

### <code>decode()</code> Parameters

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

Examples
--------

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

```php
// RFC 4648 base32 alphabet; case-insensitive
$base32 = new Base2n(5, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567', FALSE, TRUE, TRUE);
$encoded = $base32->encode('encode this');
// MVXGG33EMUQHI2DJOM======
```

```php
// RFC 4648 base32hex alphabet
$base32hex = new Base2n(5, '0123456789ABCDEFGHIJKLMNOPQRSTUV', FALSE, TRUE, TRUE);
$encoded = $base32hex->encode('encode this');
// CLN66RR4CKG78Q39EC======
```

Octal notation:

```php
$octal = new Base2n(3);
$encoded = $octal->encode('encode this');
// 312671433366214510072150322711
```

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

```php
$binary = new Base2n(1);
$encoded = $binary->encode('encode this');
// 0110010101101110011000110110111101100100011001010010000001110100011010000110100101110011
$decoded = $binary->decode($encoded);
// encode this
```

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 <code>[session.hash_bits_per_character][phphashbits]</code> php.ini setting. The decoded
size depends on the hash function, set with <code>[session.hash_function][phphash]</code> in php.ini.

```php
// session.hash_function = 0
// session.hash_bits_per_character = 5
// 128-bit session ID
$sessionId = 'q3c8n4vqpq11i0vr6ucmafg1h3';
// Decodes to 16 bytes
$phpBase32 = new Base2n(5, '0123456789abcdefghijklmnopqrstuv');
$rawSessionId = $phpBase32->decode($sessionId);
```

```php
// session.hash_function = 1
// session.hash_bits_per_character = 6
// 160-bit session ID
$sessionId = '7Hf91mVc,q-9W1VndNNh3evVN83';
// Decodes to 20 bytes
$phpBase64 = new Base2n(6, '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-,');
$rawSessionId = $phpBase64->decode($sessionId);
```

[phphashbits]: http://php.net/manual/en/session.configuration.php#ini.session.hash-bits-per-character "PHP session.hash_bits_per_character"

[phphash]: http://php.net/manual/en/session.configuration.php#ini.session.hash-function "PHP session.hash_function"


Generate random security tokens:

```php
$tokenEncoder = new Base2n(6, '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-,');
$binaryToken = openssl_random_pseudo_bytes(32); // PHP >= 5.3
$token = $tokenEncoder->encode($binaryToken);
// Example: U6M132v9FG-AHhBVaQWOg1gjyUi1IogNxuen0i3u3ep
```

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][7bit].)

```php
// This uses all 7-bit ASCII characters
$base128chars = "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
              . "\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F"
              . "\x20\x21\x22\x23\x24\x25\x26\x27\x28\x29\x2A\x2B\x2C\x2D\x2E\x2F"
              . "\x30\x31\x32\x33\x34\x35\x36\x37\x38\x39\x3A\x3B\x3C\x3D\x3E\x3F"
              . "\x40\x41\x42\x43\x44\x45\x46\x47\x48\x49\x4A\x4B\x4C\x4D\x4E\x4F"
              . "\x50\x51\x52\x53\x54\x55\x56\x57\x58\x59\x5A\x5B\x5C\x5D\x5E\x5F"
              . "\x60\x61\x62\x63\x64\x65\x66\x67\x68\x69\x6A\x6B\x6C\x6D\x6E\x6F"
              . "\x70\x71\x72\x73\x74\x75\x76\x77\x78\x69\x7A\x7B\x7C\x7D\x7E\x7F";

$base128 = new Base2n(7, $base128chars);
$encoded = $base128->encode('encode this');
```

[7bit]: http://msdn.microsoft.com/en-us/library/ms526290(v=exchg.10).aspx "7bit MIME Content-Transfer-Encoding"


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

```php
// "High" base-128 encoding
$high128chars = "\x80\x81\x82\x83\x84\x85\x86\x87\x88\x89\x8A\x8B\x8C\x8D\x8E\x8F"
              . "\x90\x91\x92\x93\x94\x95\x96\x97\x98\x99\x9A\x9B\x9C\x9D\x9E\x9F"
              . "\xA0\xA1\xA2\xA3\xA4\xA5\xA6\xA7\xA8\xA9\xAA\xAB\xAC\xAD\xAE\xAF"
              . "\xB0\xB1\xB2\xB3\xB4\xB5\xB6\xB7\xB8\xB9\xBA\xBB\xBC\xBD\xBE\xBF"
              . "\xC0\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xCA\xCB\xCC\xCD\xCE\xCF"
              . "\xD0\xD1\xD2\xD3\xD4\xD5\xD6\xD7\xD8\xD9\xDA\xDB\xDC\xDD\xDE\xDF"
              . "\xE0\xE1\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xEA\xEB\xEC\xED\xEE\xEF"
              . "\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF7\xF8\xF9\xFA\xFB\xFC\xFD\xFE\xFF";

$high128 = new Base2n(7, $high128chars);
$encoded = $high128->encode('encode this');
```

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

```php
// Base-32 non-printable character encoding
$noPrintChars = "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
              . "\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";

$nonPrintable32 = new Base2n(5, $noPrintChars);
$encoded = $nonPrintable32->encode('encode this');
```

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

```php
// Base-4 whitespace encoding
$whitespaceChars = " \t\n\r";

$whitespace = new Base2n(2, $whitespaceChars);
$encoded = $whitespace->encode('encode this');
// "\t\n\t\t\t\n\r\n\t\n \r\t\n\r\r\t\n\t \t\n\t\t \n  \t\r\t \t\n\n \t\n\n\t\t\r \r"

$decoded = $whitespace->decode(
    "\t\n\t\t\t\n\r\n\t\n \r\t\n\r\r\t\n\t \t\n\t\t \n  \t\r\t \t\n\n \t\n\n\t\t\r \r"
);
// encode this
```

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 <code>[base64_encode()][base64_encode]</code> and <code>[base64_decode()][base64_decode]</code>
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 <code>[strtr()][strtr]</code> or <code>[str_replace()][str_replace]</code>.

[base64_encode]: http://php.net/base64_encode "PHP base64_encode() Function"

[base64_decode]: http://php.net/base64_decode "PHP base64_decode() Function"

[strtr]: http://php.net/strtr "PHP strtr() Function"

[str_replace]: http://php.net/str_replace "PHP str_replace() Function"

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

```php
// RFC 4648 base64url with Base2n...
$base64url = new Base2n(6, 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_', TRUE, TRUE, FALSE);
$encoded = $base64url->encode("encode this \xBF\xC2\xBF");
// ZW5jb2RlIHRoaXMgv8K_

// RFC 4648 base64url with native functions...
$encoded = str_replace(array('+', '/', '='), array('-', '_', ''), base64_encode("encode this \xBF\xC2\xBF"));
// ZW5jb2RlIHRoaXMgv8K_
```

[rfc4648base64url]: http://tools.ietf.org/html/rfc4648#page-7 "Modified Base64 for URLs"


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

```php
// Decode the salt and digest from a Bcrypt hash

$hash = '$2y$14$i5btSOiulHhaPHPbgNUGdObga/GC.AVG/y5HHY1ra7L0C9dpCaw8u';
$encodedSalt    = substr($hash, 7, 22);
$encodedDigest  = substr($hash, 29, 31);

// Using Base2n...
$bcrypt64 = new Base2n(6, './ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789', TRUE, TRUE);
$rawSalt    = $bcrypt64->decode($encodedSalt);   // 16 bytes
$rawDigest  = $bcrypt64->decode($encodedDigest); // 23 bytes

// Using native functions...
$bcrypt64alphabet = './ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
$base64alphabet   = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
$rawSalt    = base64_decode(strtr($encodedSalt,   $bcrypt64alphabet, $base64alphabet)); // 16 bytes
$rawDigest  = base64_decode(strtr($encodedDigest, $bcrypt64alphabet, $base64alphabet)); // 23 bytes
```

[bmcf]: https://github.com/ademarre/binary-mcf "Binary Modular Crypt Format (BMCF)"

You can encode and decode hexadecimal with <code>[bin2hex()][bin2hex]</code> and <code>[pack()][pack]</code>:

```php
// Hexadecimal with Base2n...
$hexadecimal = new Base2n(4);
$encoded = $hexadecimal->encode('encode this'); // 656e636f64652074686973
$decoded = $hexadecimal->decode($encoded);      // encode this

// It's better to use native functions...
$encoded = bin2hex('encode this'); // 656e636f64652074686973
$decoded = pack('H*', $encoded);   // encode this
// As of PHP 5.4 you can use hex2bin() instead of pack()
```

[bin2hex]:  http://php.net/bin2hex  "PHP bin2hex() Function"

[pack]:     http://php.net/pack     "PHP pack() Function"