Base58

https://github.com/tuupola/base58
Admin
Base58 is a PHP library that implements Base58 encoding and decoding for integers and arbitrary...
Tokens:33,115
Snippets:224
Trust Score:9.4
License:MIT
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install with Composer

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

Install the package using Composer. Requires PHP 7.1 or up for the current branch.

```bash
$ composer require tuupola/base58
```

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

### Install older 1.x branch for PHP 5.6/7.0

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

Install the 1.x branch if you need support for PHP 5.6 or 7.0.

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

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

### Install entr and run tests automatically

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

Install `entr` via Homebrew and run tests automatically on every code change with `make watch`.

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

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

### Example Git commit message format

Source: https://github.com/tuupola/base58/blob/2.x/CONTRIBUTING.md

Shows the recommended structure for a commit message: a capitalized summary line of 50 characters or less, followed by a blank line and a detailed body wrapped at about 72 characters. The blank line is critical unless the body is omitted, as tools like rebase can get confused if the summary and body are run together.

```text
Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
```

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

### Basic construction example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Shows default construction with GMP characters and no checksum, plus a Bitcoin-configured instance with checksum and version 0x00.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

/* Default options: GMP characters, no checksum. */
$base58 = new Base58();

/* Constructor argument overrides. */
$bitcoin = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);
```

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

### Basic round trip example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Shows a basic decode call with the default character set. The comment indicates the expected decoded output is "Hello world!".

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;
$decoded = $base58->decode("1LDlk6QWOejX6rPrJ"); /* "Hello world!" */
```

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

### Decode with error handling example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Example usage of GmpEncoder::decode() with Bitcoin characters, checksum verification, and version byte. Demonstrates successful decoding of 'Hello world!' and catching a RuntimeException on checksum mismatch.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;
use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

print $gmp->decode("19wWTEnNTWna86WmtFsTAr5"); /* "Hello world!" */

try {
    $gmp->decode("19wWTEnNTWna86WmtFsTArX");
} catch (RuntimeException $exception) {
    /* Checksum "84fec52c" does not match the expected "84fec512" */
    print $exception->getMessage();
}
```

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

### Static proxy configuration via Base58Proxy::$options

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/configuration.md

Configures the static proxy by assigning to the public static property before use. The change applies immediately because each proxy method constructs a fresh Base58 instance with the current options.

```php
<?php

use Tuupola\Base58;
use Tuupola\Base58Proxy;

/* Configure before use. */
Base58Proxy::$options = [
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
];

$encoded = Base58Proxy::encode("Hello world!");
$decoded = Base58Proxy::decode($encoded);
```

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

### Default options and constructor merging in Base58

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/configuration.md

Shows the default options array and how the constructor merges user-provided options with defaults. The constructor accepts an array and merges it over the defaults; the same pattern is used by BaseEncoder and GmpEncoder.

```php
private $options = [
    "characters" => Base58::GMP,
    "check" => false,
    "version" => 0x00,
];

public function __construct(array $options = [])
{
    $this->options = array_merge($this->options, (array) $options);
    ...
}
```

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

### decode usage example with BcmathEncoder

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BaseEncoder.md

Example of decoding a Base58 string to "Hello world!" using the BcmathEncoder class. Requires Composer's autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\BcmathEncoder;

$encoder = new BcmathEncoder;
$decoded = $encoder->decode("1LDlk6QWOejX6rPrJ"); /* "Hello world!" */
```

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

### Basic GmpEncoder encode example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Shows how to instantiate GmpEncoder and encode random bytes. Requires the Composer autoloader and the Tuupola\Base58\GmpEncoder class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder;
$encoded = $gmp->encode(random_bytes(128));
```

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

### Base58Proxy::decodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Example of decoding the Base58 string `1TFvCj`, which outputs `987654321`. Requires `vendor/autoload.php` and imports `Tuupola\Base58Proxy`.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58Proxy as Base58;

print Base58::decodeInteger("1TFvCj"); /* 987654321 */
```

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

### BaseEncoder usage example with PhpEncoder and BcmathEncoder

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BaseEncoder.md

Shows how to instantiate PhpEncoder with a custom character set and BcmathEncoder with defaults. Requires vendor/autoload.php.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;
use Tuupola\Base58\BcmathEncoder;

$encoder = new PhpEncoder(["characters" => Tuupola\Base58\Base58::BITCOIN]);
$another = new BcmathEncoder(); /* defaults */
```

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

### Partial option arrays with defaults

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/configuration.md

Shows that unspecified options keep their defaults. The first instance is equivalent to new Base58() with no overrides; the second only changes the character set while check stays false and version stays 0x00.

```php
<?php

use Tuupola\Base58;

/* Same as new Base58() — no overrides. */
$a = new Base58;

/* Only the character set changes; check stays false, version stays 0x00. */
$bitcoin = new Base58(["characters" => Base58::BITCOIN]);
```

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

### Base58Proxy::encodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Example of encoding the integer 987654321, which outputs `1TFvCj`. Requires `vendor/autoload.php` and imports `Tuupola\Base58Proxy`.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58Proxy as Base58;

print Base58::encodeInteger(987654321); /* 1TFvCj */
```

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

### Base58Proxy::encode usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Example of using the Base58Proxy to encode random bytes and then decode them back. Requires the Composer autoloader and imports the proxy class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58Proxy as Base58;

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

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

### decodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Example usage of decodeInteger() with Base58 string '1TFvCj', outputting 987654321. Requires Composer autoload and the Tuupola\Base58 class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;
print $base58->decodeInteger("1TFvCj"); /* 987654321 */
```

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

### encodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Example usage of encodeInteger() with integer 987654321, outputting '1TFvCj'. Requires Composer autoload and the Tuupola\Base58 class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;
print $base58->encodeInteger(987654321); /* 1TFvCj */
```

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

### Encode with Base58Check using GmpEncoder

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Configures GmpEncoder with Bitcoin characters, checksum enabled, and version byte 0x00. The example encodes "Hello world!" and prints the Base58Check result.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;
use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

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

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

### encode usage example with PhpEncoder

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BaseEncoder.md

Example of encoding 128 random bytes using the PhpEncoder class. Requires Composer's autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder;
$encoded = $php->encode(random_bytes(128));
```

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

### Error handling on checksum mismatch

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Demonstrates decoding with check mode enabled and a version byte. The example alters the last character to cause a checksum mismatch, catching the RuntimeException and printing the message.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

try {
    /* Last character altered — checksum no longer matches. */
    $base58check->decode("19wWTEnNTWna86WmtFsTArX");
} catch (RuntimeException $exception) {
    /* Checksum "84fec52c" does not match the expected "84fec512" */
    print $exception->getMessage();
}
```

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

### Constructor error handling example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Catches InvalidArgumentException when the character set has duplicate characters (only 57 unique). The error message is 'Character set must contain 58 unique characters'.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

try {
    /* Duplicate '0' character — the set has only 57 unique characters. */
    $base58 = new Base58([
        "characters" => "0023456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv",
    ]);
} catch (InvalidArgumentException $exception) {
    echo $exception->getMessage(); /* Character set must contain 58 unique characters */
}
```

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

### Encode and decode integers

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

Use encodeInteger() and decodeInteger() for integer conversions. The example shows encoding 987654321 to '1TFvCj' and decoding it back.

```php
$integer = $base58->encodeInteger(987654321); /* 1TFvCj */
print $base58->decodeInteger("1TFvCj", true); /* 987654321 */
```

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

### GmpEncoder::encodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Example of encoding the integer 987654321 to Base58, outputting '1TFvCj'. Requires vendor/autoload.php and the Tuupola\Base58\GmpEncoder class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder;
print $gmp->encodeInteger(987654321); /* 1TFvCj */
```

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

### Base58Proxy::decode checksum error example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Example of catching a checksum error when decoding through the proxy. Configures the proxy with Bitcoin characters, check mode enabled, and a version byte of 0x00, then attempts to decode an invalid string and catches the resulting `RuntimeException`.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;
use Tuupola\Base58Proxy as Base58;

Base58Proxy::$options = [
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
];

try {
    Base58::decode("19wWTEnNTWna86WmtFsTArX");
} catch (RuntimeException $exception) {
    /* Checksum "84fec52c" does not match the expected "84fec512" */
    print $exception->getMessage();
}
```

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

### Direct base conversion example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BcmathEncoder.md

Shows how to use baseConvert directly to convert byte digits [65, 66, 67] ("ABC") from base 256 to base 58. The returned digits are decimal strings valid in the 58-character alphabet. Requires the BCMath extension.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\BcmathEncoder;

$bcmath = new BcmathEncoder;

/* Convert byte digits [65, 66, 67] ("ABC") from base 256 to base 58. */
$digits = $bcmath->baseConvert([65, 66, 67], 256, 58);
print_r($digits); /* decimal string digits valid in the 58-character alphabet */
```

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

### GmpEncoder::decodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Example of decoding the Base58 string '1TFvCj' back to the integer 987654321. Requires vendor/autoload.php and the Tuupola\Base58\GmpEncoder class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder;
print $gmp->decodeInteger("1TFvCj"); /* 987654321 */
```

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

### Direct base conversion example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/PhpEncoder.md

Shows how to call baseConvert directly to convert byte digits [65, 66, 67] ("ABC") from base 256 to base 58. Requires Composer's autoloader and uses the PhpEncoder class.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder;

/* Convert byte digits [65, 66, 67] ("ABC") from base 256 to base 58. */
$digits = $php->baseConvert([65, 66, 67], 256, 58);
print_r($digits); /* digits valid in the configured 58-character alphabet */
```

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

### Typical encode/decode round trip

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/PhpEncoder.md

Demonstrates encoding and decoding a string with a custom character set. The example uses the Bitcoin alphabet and verifies that decoding returns the original string.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder(["characters" => "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"]);

$encoded = $php->encode("Hello world!");
$decoded = $php->decode($encoded);

var_dump($decoded === "Hello world!"); /* true */
```

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

### decodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BaseEncoder.md

Shows how to instantiate PhpEncoder and decode the Base58 string '1TFvCj', which outputs 987654321. Requires the Composer autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder;
print $php->decodeInteger("1TFvCj"); /* 987654321 */
```

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

### encodeInteger usage example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BaseEncoder.md

Shows how to instantiate PhpEncoder and encode the integer 987654321, which outputs '1TFvCj'. Requires the Composer autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder;
print $php->encodeInteger(987654321); /* 1TFvCj */
```

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

### Invalid character set constructor option example

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/errors.md

Triggers InvalidArgumentException because the 'characters' option contains a duplicate '0', resulting in only 57 unique characters instead of the required 58. This exception is thrown by all encoder constructors (BaseEncoder, GmpEncoder, and indirectly Base58).

```php
new Tuupola\Base58([
    "characters" => "0023456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv", /* '0' twice: only 57 unique */
]);
```

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

### Run tests manually

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

Run the test suite manually with `make test`.

```bash
$ make test
```

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

### Constructor signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Declares the Base58 constructor that accepts an optional options array. Defaults are ["characters" => Base58::GMP, "check" => false, "version" => 0x00].

```php
public function __construct(array $options = [])
```

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

### Configuring the proxy with Base58Proxy::$options

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Shows how to set the static $options property to use Bitcoin characters with checksum enabled, then encode and decode a string via the proxy's static methods.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;
use Tuupola\Base58Proxy as Base58;

Base58Proxy::$options = [
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
];

$encoded = Base58::encode("Hello world!");
$decoded = Base58::decode($encoded);
```

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

### Basic encode() usage

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Shows how to instantiate Base58 and encode random bytes, then decode the result. Requires Composer's autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;

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

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

### Base58::__construct

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Creates a new Base58 encoder instance. Merges provided options with defaults and selects the appropriate encoder implementation based on available PHP extensions.

```APIDOC
## Base58::__construct

### Description
Creates a new Base58 encoder instance. Merges provided options with defaults and selects the appropriate encoder implementation based on available PHP extensions.

### Method
Constructor

### Signature
```php
public function __construct(array $options = [])
```

### Parameters
- `$options` (array) - Optional - Option array merged over the defaults `["characters" => Base58::GMP, "check" => false, "version" => 0x00]`.

### Behavior
Merges `$options` into the default options, then instantiates the encoder:
```php
if (function_exists("gmp_init")) {
    $this->encoder = new Base58\GmpEncoder($this->options);
} else {
    $this->encoder = new Base58\PhpEncoder($this->options);
}
```

### Throws
- `InvalidArgumentException` - When `options["characters"]` does not contain exactly 58 unique characters (thrown by the selected encoder's constructor).

### Example: basic construction
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

/* Default options: GMP characters, no checksum. */
$base58 = new Base58();

/* Constructor argument overrides. */
$bitcoin = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);
```

### Example: constructor error handling
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

try {
    /* Duplicate '0' character — the set has only 57 unique characters. */
    $base58 = new Base58([
        "characters" => "0023456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv",
    ]);
} catch (InvalidArgumentException $exception) {
    echo $exception->getMessage(); /* Character set must contain 58 unique characters */
}
```
```

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

### new Base58(options)

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

Creates a new Base58 instance with optional character set and Base58Check settings.

```APIDOC
## new Base58(options)

### Description
Creates a new Base58 instance with optional character set and Base58Check settings.

### Method
Constructor

### Endpoint
`new Base58(options)`

### Parameters
#### Options
- **characters** (string) - Optional - The character set to use. Defaults to `Base58::GMP`. Can be one of the predefined constants or a custom 58-character string.
- **check** (boolean) - Optional - Enables Base58Check encoding/decoding. Defaults to `false`.
- **version** (integer) - Optional - The version byte used in Base58Check. Required if `check` is `true`.

### Request Example
```php
$default = new Base58(["characters" => Base58::GMP]);
$bitcoin = new Base58(["characters" => Base58::BITCOIN]);
$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00
]);
```
```

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

### String vs integer encoding difference

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

Shows that encoding a string and an integer yields different results.

```php
$string = $base58->encode("987654321"); /* gE62MGeOBMPt */
$integer = $base58->encodeInteger(987654321); /* 1TFvCj */
```

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

### Benchmark results for Base58 encoders

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

Output of running `vendor/bin/phpbench run benchmarks/ --report=default` on encoding `random_bytes(128)` data. Shows GMP encoder is fastest, BCMatch is too slow to be usable.

```text
$ vendor/bin/phpbench run benchmarks/ --report=default

+-----------------------+------------------+--------------+
| subject               | mean             | diff         |
+-----------------------+------------------+--------------+
| benchGmpEncoder       | 101,832.994ops/s | 0.00%        |
| benchGmpEncoderCustom | 97,656.250ops/s  | +4.28%       |
| benchPhpEncoder       | 305.913ops/s     | +33,188.19%  |
| benchBcmathEncoder    | 32.457ops/s      | +313,643.79% |
+-----------------------+------------------+--------------+
```

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

### Static proxy usage with Base58Proxy

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

Use the provided static proxy to encode and decode data with static syntax. Requires `use Tuupola\Base58Proxy as Base58;`.

```php
use Tuupola\Base58Proxy as Base58;

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

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

### Encoder selection logic in constructor

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Chooses GmpEncoder when gmp_init exists, otherwise falls back to PhpEncoder. The selected encoder's constructor throws InvalidArgumentException if options["characters"] does not contain exactly 58 unique characters.

```php
if (function_exists("gmp_init")) {
    $this->encoder = new Base58\GmpEncoder($this->options);
} else {
    $this->encoder = new Base58\PhpEncoder($this->options);
}
```

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

### Instantiate GmpEncoder with default and Bitcoin character sets

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Creates a GmpEncoder instance using the default GMP character set and another using the Bitcoin character set. Requires the GMP extension and the Composer autoloader.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder;
$bitcoin = new GmpEncoder(["characters" => Tuupola\Base58\Base58::BITCOIN]);
```

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

### Static $options property declaration

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Declares the mutable static configuration array used by all proxy calls. Defaults to GMP characters, no checksum, and version 0x00; assign a new array to change behavior globally.

```php
/**
 * @var mixed[]
 */
public static $options = [
    "characters" => Base58::GMP,
    "check" => false,
    "version" => 0x00,
];
```

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

### Base58Proxy::$options

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static property that configures all subsequent proxy calls. Assign a new array to change encoding behavior globally; each call creates a fresh Base58 instance using the current value.

```APIDOC
## Base58Proxy::$options

### Description
Static property that configures all subsequent proxy calls. Assign a new array to change encoding behavior globally; each call creates a fresh Base58 instance using the current value.

### Property
`public static $options`

### Type
`mixed[]`

### Default Value
```php
[
    "characters" => Base58::GMP,
    "check" => false,
    "version" => 0x00,
]
```

### Usage
```php
Base58Proxy::$options = [
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
];
```

### Notes
- Mutable: can be read and written from anywhere.
- Each call reflects the current value at call time.
- See configuration.md for full options documentation.
```

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

### Trigger InvalidArgumentException with custom character set missing 'T'

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/errors.md

When a custom character set omits a character (here 'T'), decoding a string that is valid under the default GMP set but uses the missing character throws InvalidArgumentException. The example configures a custom alphabet without 'T' and decodes 'T8dgcjRGuYUueWht'.

```php
<?php

use Tuupola\Base58;

$base58 = new Base58([
    "characters" => "9876543210ABCDEFGHIJKLMNOPQRS-UVWXYZabcdefghijklmnopqrstuv", /* no 'T' */
]);
$base58->decode("T8dgcjRGuYUueWht"); /* InvalidArgumentException */
```

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

### Base58Check encode() with version and checksum

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Configures Base58 with Bitcoin characters, check mode enabled, and version 0x00. The output includes a version byte and a 4-byte double-SHA256 checksum.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

print $base58check->encode("Hello world!"); /* 19wWTEnNTWna86WmtFsTAr5 */
```

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

### Trigger InvalidArgumentException with invalid characters in decode input

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/errors.md

Decoding a string containing characters outside the configured Base58 alphabet throws InvalidArgumentException with message 'Data contains invalid characters "..."'. The example uses the default character set and input 'invalid~data-%@#!@*#-foo', producing the exception with offending characters '~%@#!*'.

```php
<?php

use Tuupola\Base58;

$base58 = new Base58;
$base58->decode("invalid~data-%@#!@*#-foo");
/* InvalidArgumentException: Data contains invalid characters "~%@#!*" */
```

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

### Base58 Character Sets and Encoding

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

Shows the predefined character set constants (GMP, BITCOIN, FLICKR, RIPPLE, IPFS) and how to instantiate Base58 with a custom character set. The default uses GMP; the Bitcoin set produces a different encoded output for the same input.

```php
use Tuupola\Base58;

print Base58::GMP /* 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv */
print Base58::BITCOIN /* 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz */
print Base58::FLICKR /* 123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ */
print Base58::RIPPLE /* rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz */
print Base58::IPFS /* 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz */

$default = new Base58(["characters" => Base58::GMP]);
$bitcoin = new Base58(["characters" => Base58::BITCOIN]);
print $default->encode("Hello world!"); /* 1LDlk6QWOejX6rPrJ */
print $bitcoin->encode("Hello world!"); /* 2NEpo7TZRhna7vSvL */
```

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

### Base58Proxy::encode method signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static method that encodes binary string data to a Base58 string. Equivalent to `(new Base58(self::$options))->encode($data)`. Returns the Base58 representation of the input data.

```php
/**
 * Encode given data to a base58 string
 */
public static function encode(string $data): string
```

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

### encode(string $data): string

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Encodes given binary string data to a Base58 string. Supports optional check mode for Base58Check encoding with version and checksum.

```APIDOC
## encode(string $data): string

### Description
Encodes given binary string data to a Base58 string. Supports optional check mode for Base58Check encoding with version and checksum.

### Method
N/A (PHP method)

### Endpoint
N/A (PHP method)

### Parameters
#### Method Parameters
- `$data` (string) - Required - Binary string data to encode.

### Request Example
```php
$base58 = new Base58;
$encoded = $base58->encode(random_bytes(128));
```

### Response
#### Success Response
Returns: `string` — the Base58 representation of `$data`.

#### Response Example
```php
$encoded = $base58->encode(random_bytes(128));
```

### Behavior Notes
- An empty string encodes to `""` unless check mode is enabled.
- In check mode (`"check" => true`), a version byte (`chr(options["version"])`) is prepended and a 4-byte double-SHA256 checksum is appended before encoding.
- Leading zero bytes are preserved and represented as repeated leading zero characters.

### Throws/Rejects
None. (A `TypeError` is raised by PHP if a non-string argument is passed.)

### Example: basic use
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;

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

### Example: check mode (Base58Check)
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

print $base58check->encode("Hello world!"); /* 19wWTEnNTWna86WmtFsTAr5 */
```
```

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

### decode(string $data): string

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Decodes a given base58 string back to binary data. Throws exceptions on invalid characters or checksum/version mismatches when check mode is enabled.

```APIDOC
## decode(string $data): string

### Description
Decodes a given base58 string back to binary data. Throws exceptions on invalid characters or checksum/version mismatches when check mode is enabled.

### Method
`decode`

### Signature
`public function decode(string $data): string`

### Parameters
- `$data` (string) - Required - Base58 string to decode.

### Returns
- `string` - The decoded binary data.

### Throws
- `InvalidArgumentException` - If `$data` contains any character not present in the configured character set. Message: `Data contains invalid characters "..."`.
- `RuntimeException` - If check mode is enabled and the decoded checksum does not match the recomputed double-SHA256 checksum. Message: `Checksum "..." does not match the expected "..."`. Checked before the version.
- `RuntimeException` - If check mode is enabled and the decoded version byte does not equal `options["version"]`. Message: `Version "..." does not match the expected "..."`.

### Example: basic round trip
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;
$decoded = $base58->decode("1LDlk6QWOejX6rPrJ"); /* "Hello world!" */
```

### Example: error handling on checksum mismatch
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00,
]);

try {
    /* Last character altered — checksum no longer matches. */
    $base58check->decode("19wWTEnNTWna86WmtFsTArX");
} catch (RuntimeException $exception) {
    /* Checksum "84fec52c" does not match the expected "84fec512" */
    print $exception->getMessage();
}
```
```

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

### __construct(array $options = [])

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/PhpEncoder.md

Constructor for the PhpEncoder class. Inherited from BaseEncoder and available on PhpEncoder instances.

```APIDOC
## __construct(array $options = [])

### Description
Constructor for the PhpEncoder class. Inherited from BaseEncoder and available on PhpEncoder instances.

### Method
__construct

### Signature
public function __construct(array $options = [])

### Parameters
- **$options** (array) - Optional - Configuration options, e.g., 'characters' for the character set.

### Throws
- **InvalidArgumentException** - When the character set option is not exactly 58 unique characters.

### Example
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\PhpEncoder;

$php = new PhpEncoder(["characters" => "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"]);
```
```

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

### RuntimeException - version byte mismatch in Base58Check mode

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/errors.md

Thrown when decoding in Base58Check mode and the decoded version byte does not equal the configured `version`. This exception is raised by `decode()` in check mode.

```APIDOC
## RuntimeException

### Description
Thrown when decoding in Base58Check mode and the decoded version byte does not equal the configured `version`. This exception is raised by `decode()` in check mode.

### Trigger Condition
Base58Check mode: decoded version byte does not equal the configured `version`.

### Thrown By
- `decode()` in check mode
```

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

### Base58Check Encoding and Decoding with Version and Checksum

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

Configures Base58 with the Bitcoin character set, checksum validation, and a version byte (0x00). Encoding produces a Base58Check string; decoding throws a RuntimeException if the checksum or version is invalid, as shown with a tampered input.

```php
use Tuupola\Base58;

$base58check = new Base58([
    "characters" => Base58::BITCOIN,
    "check" => true,
    "version" => 0x00
]);

print $base58check->encode("Hello world!"); /* 19wWTEnNTWna86WmtFsTAr5 */

try {
    $base58check->decode("19wWTEnNTWna86WmtFsTArX");
} catch (RuntimeException $exception) {
    /* Checksum "84fec52c" does not match the expected "84fec512" */
    print $exception->getMessage();
}
```

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

### Base58Proxy::encodeInteger method signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static method that encodes an integer to a Base58 string. No check/version/checksum processing is applied. Equivalent to `(new Base58(self::$options))->encodeInteger($data)`.

```php
/**
 * Encode given integer to a base58 string
 */
public static function encodeInteger(int $data): string
```

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

### GmpEncoder::__construct

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Creates a new GmpEncoder instance. Accepts an optional options array to customize the character set, checksum, and version.

```APIDOC
## GmpEncoder::__construct

### Description
Creates a new GmpEncoder instance. Accepts an optional options array to customize the character set, checksum, and version.

### Method
Constructor

### Signature
```php
public function __construct(array $options = [])
```

### Parameters
- **$options** (array) - Optional - Option array merged over the defaults `["characters" => Base58::GMP, "check" => false, "version" => 0x00]`.

### Throws
- **InvalidArgumentException** - If the character set option contains anything other than 58 unique characters. Message: `Character set must contain 58 unique characters`.

### Example
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\GmpEncoder;

$gmp = new GmpEncoder;
$bitcoin = new GmpEncoder(["characters" => Tuupola\Base58\Base58::BITCOIN]);
```
```

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

### Base58 Class Constants

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Public class constants defining character sets and Base58Check parameters. GMP is the default character set; BITCOIN, FLICKR, RIPPLE, and IPFS are alternatives. VERSION_SIZE and CHECKSUM_SIZE control Base58Check mode.

```php
const GMP = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuv";
const BITCOIN = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
const FLICKR = "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ";
const RIPPLE = "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz";
const IPFS = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";

const VERSION_SIZE = 1;
const CHECKSUM_SIZE = 4;
```

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

### Base58Proxy::decode method signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static method that decodes a Base58 string back to binary data. Throws `InvalidArgumentException` if the data contains characters outside the configured character set, and `RuntimeException` if check mode is enabled and the checksum or version byte does not match.

```php
/**
 * Decode given base58 string back to data
 */
public static function decode(string $data): string
```

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

### baseConvert implementation core arithmetic

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BcmathEncoder.md

Core arithmetic used in baseConvert: repeated long division in decimal-string arithmetic. $sourceBase and $targetBase are cast to strings on each loop; bcdiv(..., 0) scale truncates to an integer quotient; leading quotient zeros are dropped and each remainder is unshifted onto the result.

```php
$accumulator = bcadd((string) $source[$i], bcmul((string)$remainder, $sourceBase));
$digit = bcdiv($accumulator, $targetBase, 0);   /* integer division */
$remainder = bcmod($accumulator, $targetBase);
```

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

### GmpEncoder::decode() method signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Public method signature for decoding a base58 string to binary data. The pipeline validates input, translates characters to the GMP set if needed, strips leading zero bytes, converts via GMP, and optionally verifies checksum and version when the 'check' option is enabled.

```php
/**
 * Decode given base58 string back to data
 */
public function decode(string $data): string
```

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

### Base58Proxy::encode()

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static method that encodes data using the current proxy options. Internally creates a new Base58 instance and calls its encode method.

```APIDOC
## Base58Proxy::encode()

### Description
Static method that encodes data using the current proxy options. Internally creates a new Base58 instance and calls its encode method.

### Method
`encode`

### Signature
```php
public static function encode(string $data): string
```

### Parameters
- **$data** (string) - Required - The data to encode.

### Return Value
- **string** - The Base58-encoded string.

### Example
```php
$encoded = Base58::encode("Hello world!");
```
```

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

### Base58::BITCOIN

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

Returns the Bitcoin character set string used for Base58 encoding.

```APIDOC
## Base58::BITCOIN

### Description
Returns the Bitcoin character set string used for Base58 encoding.

### Method
Static property access

### Endpoint
`Base58::BITCOIN`

### Parameters
None

### Response
#### Success Response
- **type** (string) - The Bitcoin character set: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`

#### Response Example
```php
print Base58::BITCOIN; /* 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz */
```
```

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

### encode(string $data): string

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Encodes binary data to a Base58 string. This is a static method that can be called directly on the Base58Proxy class.

```APIDOC
## `encode(string $data): string`

### Description
Encodes given binary data to a Base58 string.

### Method
`encode`

### Parameters
- **$data** (string) - Required - Binary string data to encode.

### Returns
- **string** - The Base58 representation of `$data`.

### Example
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58Proxy as Base58;

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

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

### Base58Proxy::decode()

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58Proxy.md

Static method that decodes a Base58-encoded string using the current proxy options. Internally creates a new Base58 instance and calls its decode method.

```APIDOC
## Base58Proxy::decode()

### Description
Static method that decodes a Base58-encoded string using the current proxy options. Internally creates a new Base58 instance and calls its decode method.

### Method
`decode`

### Signature
```php
public static function decode(string $data): string
```

### Parameters
- **$data** (string) - Required - The Base58-encoded string to decode.

### Return Value
- **string** - The decoded data.

### Example
```php
$decoded = Base58::decode($encoded);
```
```

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

### new BcmathEncoder(array $options = [])

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BcmathEncoder.md

Constructor for the BcmathEncoder class. Accepts an optional options array, typically for configuring the character set. Throws InvalidArgumentException if the character set option is not exactly 58 unique characters.

```APIDOC
## Constructor

### Description
Initializes a new BcmathEncoder instance with optional configuration options.

### Method
Constructor

### Signature
`public function __construct(array $options = [])`

### Parameters
- **$options** (array) - Optional - Configuration options, e.g., custom character set.

### Exceptions
- **InvalidArgumentException** - If the character set option is not exactly 58 unique characters.

### Example
```php
$encoder = new BcmathEncoder();
```
```

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

### encodeInteger(int $data): string

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/Base58.md

Encodes an integer to its Base58 string representation. Operates in the integer domain, not on byte strings, and does not apply checksum or version logic.

```APIDOC
## `encodeInteger(int $data): string`

### Description
Encodes a given integer to a Base58 string. Unlike `encode()`, it operates on the integer value directly, not its byte representation, and does not apply checksum or version logic.

### Method
`encodeInteger`

### Parameters
- `$data` (int) - Required - Integer value to encode.

### Returns
- `string` - The Base58 representation of the integer.

### Behavior Notes
- Operates in the integer domain; `encode("987654321")` and `encodeInteger(987654321)` yield different outputs.
- Does not apply `check`, `version`, or checksum logic.

### Example
```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58;

$base58 = new Base58;
print $base58->encodeInteger(987654321); /* 1TFvCj */
```
```

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

### Typical encode/decode round trip

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/BcmathEncoder.md

Shows a typical encode/decode round trip using random_bytes(128). The BCMath encoder is extremely slow; the README calls it "too slow to be usable". Prefer GmpEncoder when the GMP extension is available.

```php
<?php

require "vendor/autoload.php";

use Tuupola\Base58\BcmathEncoder;

$bcmath = new BcmathEncoder;
$encoded = $bcmath->encode(random_bytes(128));
$decoded = $bcmath->decode($encoded);
```

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

### RuntimeException - checksum mismatch in Base58Check mode

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/errors.md

Thrown when decoding in Base58Check mode and the decoded checksum does not match the recomputed double-SHA256 checksum. This exception is raised by `decode()` in check mode.

```APIDOC
## RuntimeException

### Description
Thrown when decoding in Base58Check mode and the decoded checksum does not match the recomputed double-SHA256 checksum. This exception is raised by `decode()` in check mode.

### Trigger Condition
Base58Check mode: decoded checksum does not match the recomputed double-SHA256 checksum.

### Thrown By
- `decode()` in check mode
```

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

### GmpEncoder::encode() method signature

Source: https://github.com/tuupola/base58/blob/2.x/_autodocs/api-reference/GmpEncoder.md

Declares the public encode method that converts binary string data to a Base58 string. The method returns the Base58 representation of the input data.

```php
/**
 * Encode given data to a base58 string
 */
public function encode(string $data): string
```
Tokens:
Raw