### Install Base32 using Composer

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Instructions for installing the Base32 library using Composer for PHP projects. It specifies the command for the latest version and an alternative for older PHP versions (1.x branch).

```bash
$ composer require tuupola/base32
```

```bash
$ composer require "tuupola/base32:^1.0"
```

--------------------------------

### Install entr and Watch for Changes (Bash)

Source: https://github.com/tuupola/base32/blob/2.x/README.md

This snippet shows how to install the `entr` utility using Homebrew and then use it with `make watch` to automatically re-run tests whenever code files change. This requires `entr` to be installed.

```bash
$ brew install entr
$ make watch
```

--------------------------------

### GMP Character Set Encoding and Decoding in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Illustrates encoding and decoding using the GMP character set, which can offer performance benefits when the GMP extension is available. Examples show usage with and without padding.

```php
<?php

use Tuupola\Base32;

$gmp = new Base32([
    "characters" => Base32::GMP,
    "padding" => false
]);

$encoded = $gmp->encode("Hello world!");
// Output: 91IMOR3F41RMUSJCCGGG

$decoded = $gmp->decode("91IMOR3F41RMUSJCCGGG");
// Output: Hello world!

// With padding
$withPadding = new Base32([
    "characters" => Base32::GMP,
    "padding" => "="
]);

$encoded = $withPadding->encode("Hello world!");
// Output: 91IMOR3F41RMUSJCCGGG====

```

--------------------------------

### Integer Encoding and Decoding in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Illustrates how to encode and decode integer values using specialized methods provided by the Base32 library. This section includes examples for handling regular integers, large integers up to PHP_INT_MAX, and zero, highlighting the difference between string and integer encoding.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32();

// Encode integer
$encoded = $base32->encodeInteger(987654321);
// Output: 5N42FR==

// Decode integer
$decoded = $base32->decodeInteger("5N42FR==");
// Output: 987654321

// Handle large integers
$largeInt = PHP_INT_MAX;
$encoded = $base32->encodeInteger($largeInt);
$decoded = $base32->decodeInteger($encoded);
// $decoded === $largeInt

// Handle zero
$zero = $base32->encodeInteger(0);
$decoded = $base32->decodeInteger($zero);
// Output: 0

// Note: Encoding string vs integer yields different results
$stringEncoded = $base32->encode("987654321");
// Output: FHE4DONRVGQZTEMI=
$integerEncoded = $base32->encodeInteger(987654321);
// Output: 5N42FR==
// These are different!

```

--------------------------------

### RFC4648 HEX Encoding with Padding Options in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Demonstrates the use of the RFC4648 base32hex character set for creating lexically sortable Base32 encoded strings. Examples include encoding with and without padding.

```php
<?php

use Tuupola\Base32;

$base32hex = new Base32([
    "characters" => Base32::HEX,
    "padding" => "="
]);

$encoded = $base32hex->encode("Hello world!");
// Output: 91IMOR3F41RMUSJCCGGG====

// Without padding
$noPadding = new Base32([
    "characters" => Base32::HEX,
    "padding" => false
]);

$encoded = $noPadding->encode("Hello world!");
// Output: 91IMOR3F41RMUSJCCGGG

```

--------------------------------

### Crockford's Base32 Encoding and Decoding

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Demonstrates Crockford's Base32 encoding, which accepts mixed-case input, treats 'i'/'l' as '1' and 'o' as '0' during decoding, and ignores hyphens. Encoding uses uppercase letters and no padding is applied in this example.

```php
<?php

use Tuupola\Base32;

$crockford = new Base32([
    "characters" => Base32::CROCKFORD,
    "padding" => false,
    "crockford" => true,
]);

print $crockford->encode("Hello world!"); /* 91JPRV3F41VPYWKCCGGG */
print $crockford->decode("91JPRV3F41VPYWKCCGGG"); /* Hello world! */
print $crockford->decode("91jprv3f41vpywkccggg"); /* Hello world! */
print $crockford->decode("9ljprv3f4lvpywkccggg"); /* Hello world! */
```

--------------------------------

### Run Tests Manually (Bash)

Source: https://github.com/tuupola/base32/blob/2.x/README.md

This command executes the test suite for the project. It's a straightforward way to verify the library's functionality.

```bash
$ make test
```

--------------------------------

### Base32 Performance Optimization: Auto-selection (PHP)

Source: https://context7.com/tuupola/base32/llms.txt

Illustrates the Base32 library's automatic selection of the optimal encoder based on PHP extension availability, prioritizing GMP for performance. It includes code for benchmarking the GmpEncoder against the PhpEncoder to demonstrate the performance difference.

```php
<?php

use Tuupola\Base32;
use Tuupola\Base32\GmpEncoder;
use Tuupola\Base32\PhpEncoder;

// Auto-selection based on GMP availability
$base32 = new Base32();
// Uses GmpEncoder if ext-gmp is installed, otherwise PhpEncoder

// Check which encoder would be used
$hasGmp = function_exists("gmp_init");
if ($hasGmp) {
    // GmpEncoder will be used (faster)
    // Benchmarks show ~1.22x faster than pure PHP
} else {
    // PhpEncoder will be used (pure PHP, no extensions)
}

// Performance comparison (GMP vs PHP)
$data = random_bytes(128);

$start = microtime(true);
for ($i = 0; $i < 1000; $i++) {
    $encoded = (new GmpEncoder())->encode($data);
}
$gmpTime = microtime(true) - $start;

$start = microtime(true);
for ($i = 0; $i < 1000; $i++) {
    $encoded = (new PhpEncoder())->encode($data);
}
$phpTime = microtime(true) - $start;

// GMP is approximately 1.22x faster
// GmpEncoder: ~8,361 ops/s
// PhpEncoder: ~6,881 ops/s

```

--------------------------------

### Encode and Decode with Base32 Static Proxy (PHP)

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Demonstrates how to use the static proxy `Tuupola\Base32Proxy` for encoding binary data to Base32 and decoding Base32 strings back to binary. This is useful for applications preferring static syntax. It requires the `Tuupola\Base32Proxy` namespace.

```php
use Tuupola\Base32Proxy as Base32;

$encoded = Base32::encode(random_bytes(128));
$decoded = Base32::decode($encoded);
```

--------------------------------

### Handle Edge Cases with Zero Bytes in Base32 Encoding (PHP)

Source: https://context7.com/tuupola/base32/llms.txt

Demonstrates how the Base32 library correctly handles various edge cases involving zero bytes, including single zero bytes, multiple zero bytes, and zero byte prefixes during encoding and decoding. This ensures data integrity for all input types.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32();

// Single zero byte
$data = "\x00";
$encoded = $base32->encode($data);
$decoded = $base32->decode($encoded);
// $decoded === "\x00"

// Multiple zero bytes
$data = "\x00\x00\x00";
$encoded = $base32->encode($data);
$decoded = $base32->decode($encoded);
// $decoded === "\x00\x00\x00"

// Zero byte prefix
$data = "\x00\x01\x02";
$encoded = $base32->encode($data);
$decoded = $base32->decode($encoded);
// $decoded === "\x00\x01\x02"

// Multiple zero byte prefix
$data = "\x00\x00\x00\x01\x02";
$encoded = $base32->encode($data);
$decoded = $base32->decode($encoded);
// $decoded === "\x00\x00\x00\x01\x02"

// Progressive encoding (testing each length)
$encoded = $base32->encode("f");
// Output: MY======
$encoded = $base32->encode("fo");
// Output: MZXQ====
$encoded = $base32->encode("foo");
// Output: MZXW6===
$encoded = $base32->encode("foob");
// Output: MZXW6YQ=
$encoded = $base32->encode("fooba");
// Output: MZXW6YTB
$encoded = $base32->encode("foobar");
// Output: MZXW6YTBOI======

```

--------------------------------

### RFC4648 Standard Encoding with Padding Options in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Shows how to configure the Base32 library to use the RFC4648 standard character set. It demonstrates both the default behavior with padding and how to explicitly disable padding for different encoding requirements.

```php
<?php

use Tuupola\Base32;

// Explicit RFC4648 configuration (default)
$base32 = new Base32([
    "characters" => Base32::RFC4648,
    "padding" => "="
]);

$encoded = $base32->encode("Hello world!");
// Output: JBSWY3DPEB3W64TMMQQQ====

// Disable padding
$noPadding = new Base32([
    "characters" => Base32::RFC4648,
    "padding" => false
]);

$encoded = $noPadding->encode("Hello world!");
// Output: JBSWY3DPEB3W64TMMQQQ

```

--------------------------------

### Basic String Encoding and Decoding in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Demonstrates the fundamental usage of the Base32 library for encoding and decoding arbitrary string data using the default RFC4648 character set with padding. It covers encoding text, random bytes, empty strings, and binary data represented in hex.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32();

// Encode binary or text data
$encoded = $base32->encode("Hello world!");
// Output: JBSWY3DPEB3W64TMMQQQ====

// Decode back to original
$decoded = $base32->decode("JBSWY3DPEB3W64TMMQQQ====");
// Output: Hello world!

// Encode random bytes
$randomData = random_bytes(128);
$encoded = $base32->encode($randomData);
$decoded = $base32->decode($encoded);
// $decoded === $randomData

// Handle empty strings
$empty = $base32->encode("");
// Output: ""

// Encode hex binary data
$binary = hex2bin("0000010203040506");
$encoded = $base32->encode($binary);
// Output: AAAACAQDAQCQM===

```

--------------------------------

### Accessing Built-in Character Sets

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Shows how to access and print the predefined character sets available in the Base32 library, including RFC4648, Crockford, Z-base-32, GMP, and HEX. It also demonstrates creating encoders with custom character sets.

```php
<?php

use Tuupola\Base32;

print Base32::CROCKFORD; /* 0123456789ABCDEFGHJKMNPQRSTVWXYZ */
print Base32::RFC4648; /* ABCDEFGHIJKLMNOPQRSTUVWXYZ234567 */
print Base32::ZBASE32; /* ybndrfg8ejkmcpqxot1uwisza345h769 */
print Base32::GMP; /* 0123456789ABCDEFGHIJKLMNOPQRSTUV */
print Base32::HEX; /* 0123456789ABCDEFGHIJKLMNOPQRSTUV */

$default = new Base32(["characters" => Base32::RFC4648]);
$crockford = new Base32(["characters" => Base32::CROCKFORD]);
print $default->encode("Hello world!"); /* JBSWY3DPEB3W64TMMQQQ==== */
// Assuming $inverted is meant to be $crockford based on context
print $crockford->encode("Hello world!"); /* 91JPRV3F41VPYWKCCGGG==== */
```

--------------------------------

### Difference Between Integer and String Encoding

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Illustrates that encoding an integer directly versus encoding its string representation results in different Base32 outputs. This highlights the importance of using the correct encoding method for the data type.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32;

$integerEncoded = $base32->encodeInteger(987654321); /* 5N42FR== */
$stringEncoded = $base32->encode("987654321"); /* FHE4DONRVGQZTEMI= */

print "Encoded Integer: " . $integerEncoded . "\n";
print "Encoded String: " . $stringEncoded . "\n";
```

--------------------------------

### Static Base32 Proxy Interface in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Provides a static proxy interface for Base32 operations, allowing encoding and decoding without explicit object instantiation. Global options can be configured using `Base32::$options`. Supports static methods for encoding, decoding, integer encoding, and integer decoding.

```php
<?php

use Tuupola\Base32Proxy as Base32;

// Encode using static methods
$encoded = Base32::encode(random_bytes(128));

// Decode using static methods
$decoded = Base32::decode($encoded);

// Integer encoding/decoding
$encodedInt = Base32::encodeInteger(987654321);
// Output: 5N42FR==
$decodedInt = Base32::decodeInteger("5N42FR==");
// Output: 987654321

// Configure options globally
Base32::$options = [
    "characters" => Base32::CROCKFORD,
    "padding" => false,
    "crockford" => true,
];

$encoded = Base32::encode("Hello world!");
// Uses Crockford character set

```

--------------------------------

### Encode and Decode Integers with Base32

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Shows how to use the `encodeInteger` and `decodeInteger` methods for converting integers to and from their Base32 string representation. This is distinct from encoding the string representation of an integer.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32;

$integer = $base32->encodeInteger(987654321); /* 5N42FR== */
print $base32->decodeInteger("5N42FR=="); /* 987654321 */
```

--------------------------------

### Base32 Error Handling with PHP Exceptions

Source: https://context7.com/tuupola/base32/llms.txt

Demonstrates error handling for invalid Base32 input using `InvalidArgumentException`. This includes catching errors for invalid characters during decoding, attempting to decode an empty string as an integer, and providing invalid character sets (less than or more than 32 characters, or duplicate characters).

```php
<?php

use Tuupola\Base32;
use InvalidArgumentException;

$base32 = new Base32();

// Invalid characters in decoding
try {
    $decoded = $base32->decode("invalid~data-%@#!@*#-foo");
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    // Output: Data contains invalid characters "~-%@#!*"
}

// Empty string integer decoding
try {
    $decoded = $base32->decodeInteger("");
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    // Output: Cannot decode empty string as integer
}

// Invalid character set (not 32 characters)
try {
    $invalid = new Base32([
        "characters" => "123456789ABCDEFGHIJKLMNOPQRSTUV"  // Only 31 chars
    ]);
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    // Output: Character set must 32 unique characters
}

// Duplicate characters in set
try {
    $invalid = new Base32([
        "characters" => "00123456789ABCDEFGHIJKLMNOPQRSTUV"  // Duplicate '0'
    ]);
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    // Output: Character set must 32 unique characters
}

```

--------------------------------

### GMP Base32 Encoding (No Padding)

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Illustrates the configuration for GMP-based Base32 encoding, using the GMP character set and disabling padding. This method relies on the GMP extension being available.

```php
<?php

use Tuupola\Base32;

$gmp = new Base32([
    "characters" => Base32::GMP,
    "padding" => false
]);

print $gmp->encode("Hello world!"); /* 91IMOR3F41RMUSJCCGGG */
```

--------------------------------

### Crockford's Base32 Encoding and Decoding with PHP

Source: https://context7.com/tuupola/base32/llms.txt

Utilizes Crockford's Base32 character set for encoding and decoding. Supports case-insensitive decoding, character substitutions (i→1, l→1, o→0), and ignoring hyphens. The `padding` option can be set to `false` to disable padding.

```php
<?php

use Tuupola\Base32;

$crockford = new Base32([
    "characters" => Base32::CROCKFORD,
    "padding" => false,
    "crockford" => true,
]);

// Encode (always uppercase)
$encoded = $crockford->encode("Hello world!");
// Output: 91JPRV3F41VPYWKCCGGG

// Decode - uppercase
$decoded = $crockford->decode("91JPRV3F41VPYWKCCGGG");
// Output: Hello world!

// Decode - lowercase (case insensitive)
$decoded = $crockford->decode("91jprv3f41vpywkccggg");
// Output: Hello world!

// Decode with i→1, l→1, o→0 substitutions
$decoded = $crockford->decode("9ljprv3f4lvpywkccggg");
// Output: Hello world!

// Decode with hyphens (ignored)
$decoded = $crockford->decode("91jpr-v3f41-vpywk-ccggg");
// Output: Hello world!

// Full example with hyphens and substitutions
$encoded = "91JPRV3F41VPYWKCCGGJ0Y3R";
$withSubstitutions = "9ljp-rv3f4-1vpyw-kccgg-joy3r";
$decoded1 = $crockford->decode($encoded);
$decoded2 = $crockford->decode($withSubstitutions);
// Both output: Hello world! xx
// $decoded1 === $decoded2

```

--------------------------------

### Explicit Base32 Encoder Selection in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Allows direct instantiation of GMP or PHP encoders for specific Base32 implementations. The `GmpEncoder` requires the GMP extension to be enabled, while the `PhpEncoder` is a pure PHP implementation. Both encoders can be configured with custom character sets and padding.

```php
<?php

use Tuupola\Base32\GmpEncoder;
use Tuupola\Base32\PhpEncoder;

// Force GMP encoder (requires GMP extension)
$gmpEncoder = new GmpEncoder([
    "characters" => "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
    "padding" => "="
]);

$encoded = $gmpEncoder->encode("foobar");
// Output: MZXW6YTBOI======

// Force pure PHP encoder
$phpEncoder = new PhpEncoder([
    "characters" => "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
    "padding" => "="
]);

$encoded = $phpEncoder->encode("foobar");
// Output: MZXW6YTBOI======

// Both produce identical results
$data = random_bytes(128);
$gmpResult = $gmpEncoder->encode($data);
$phpResult = $phpEncoder->encode($data);
// $gmpResult === $phpResult

```

--------------------------------

### Encode and Decode Arbitrary Data with Base32

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Demonstrates the basic usage of the Base32 library to encode arbitrary byte data and then decode the resulting Base32 string back to its original form. It utilizes the default RFC4648 encoding.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32;

$encoded = $base32->encode(random_bytes(128));
$decoded = $base32->decode($encoded);

var_dump($decoded === random_bytes(128)); // true
```

--------------------------------

### RFC4648 Base32 Encoding

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Demonstrates how to explicitly configure the Base32 encoder to use the RFC4648 standard character set and padding. This is the default behavior but can be explicitly set.

```php
<?php

use Tuupola\Base32;

$base32 = new Base32([
    "characters" => Base32::RFC4648,
    "padding" => "="
]);

print $base32->encode("Hello world!"); /* JBSWY3DPEB3W64TMMQQQ==== */
```

--------------------------------

### RFC4648 Base32hex Encoding

Source: https://github.com/tuupola/base32/blob/2.x/README.md

Shows how to configure the Base32 encoder for the RFC4648 base32hex standard, which uses a different character set making the output lexically sortable. Padding is also explicitly set.

```php
<?php

use Tuupola\Base32;

$base32hex = new Base32([
    "characters" => Base32::HEX,
    "padding" => "="
]);

print $base32hex->encode("Hello world!"); /* 91IMOR3F41RMUSJCCGGG==== */
```

--------------------------------

### Custom Base32 Character Set Definition in PHP

Source: https://context7.com/tuupola/base32/llms.txt

Allows defining custom 32-character sets for Base32 encoding and decoding. The `characters` option must be set to a string containing exactly 32 unique characters. Several predefined character sets are available, including Crockford, RFC4648, ZBASE32, GMP, and HEX.

```php
<?php

use Tuupola\Base32;

// Custom character set (must be exactly 32 unique characters)
$custom = new Base32([
    "characters" => "ABCDEFGHIJKLMNOPQRSTUV0123456789",
    "padding" => false
]);

$encoded = $custom->encode("Custom encoding");
$decoded = $custom->decode($encoded);
// $decoded === "Custom encoding"

// Available predefined character sets
$charsets = [
    Base32::CROCKFORD,  // 0123456789ABCDEFGHJKMNPQRSTVWXYZ
    Base32::RFC4648,    // ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
    Base32::ZBASE32,    // ybndrfg8ejkmcpqxot1uwisza345h769
    Base32::GMP,        // 0123456789ABCDEFGHIJKLMNOPQRSTUV
    Base32::HEX,        // 0123456789ABCDEFGHIJKLMNOPQRSTUV
];

// Print available character sets
echo Base32::CROCKFORD . "\n";  // 0123456789ABCDEFGHJKMNPQRSTVWXYZ
echo Base32::RFC4648 . "\n";    // ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
echo Base32::ZBASE32 . "\n";    // ybndrfg8ejkmcpqxot1uwisza345h769

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.