README

Big Numbers Base Convert

Safe number conversion between arbitrary bases.

Contents

About
Getting Started
- Installation
- Usage
Roadmap
Contributing
Authorship
License

About Base Convert

Base Convert performs safe number conversion between arbitrary bases. The conversion is performed with a custom implementation to avoid native PHP base_convert function float precision problem.

The implementation used is extracted from the Symfony UID component. The class BinaryUtil implements the necessary fromBase and toBase methods. These methods have been extracted to ensure compatibility (it is an internal class) and to reduce the minimum PHP version requirement.

Getting Started

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

$ composer require ocubom/base-convert

Usage

Just use like the native base_convert. Although the implementation is compatible with native conversion it provides some improvements:

Bases can be between 2 and 62. The native version only supports bases between 2 and 36.

The conversion uses Base62 in the same manner as the GMP extension. The conversions are compatible.
"Named bases" are supported.
The special base bin can be used to convert from/to binary strings. This can be used to directly convert binary outputs of some functions.
```
use function \Ocubom\Math\base_convert;

$hex = base_convert(random_bytes(32), 'bin', 'hex');
```
Warning

Do not confuse a binary encoding (bin) with the Base2 encoding (a text string with the characters 0 and 1).

In PHP there are several functions:
- bin2hex/hex2bin that convert between hexadecimal and binary.
- bindec/decbin that convert between Base2 and Base10.
In this library the string bin has been considered to be equivalent to the first set of functions.
New bases can be used by implementing the base interface.

Includes bases for Douglas Crockford Base32 and Satoshi Nakamoto Base58 encodings. The implementations are examples of how to customize your own encoding.

Douglas Crockford Base 32 encoding

A secure version of the Base 32 encoding proposed by Douglas Crockford.

Note

The encoding scheme is required to

Be human-readable and machine-readable.

Be compact. Humans have difficulty in manipulating long strings of arbitrary symbols.

Be error resistant. Entering the symbols must not require keyboarding gymnastics.

Be pronounceable. Humans should be able to accurately transmit the symbols to other humans using a telephone.

-- Douglas Crockford. Base 32

This encoding is accessible:

By passing a Crockford object as any of the base arguments of the base_convert function.

use Ocubom\Math\Base\Crockford;
use function Ocubom\Math\base_convert;

// Encoding
$crockford = base_convert(random_bytes(32), 'bin', new Crockford());

// Decoding
$hex = base_convert($crockford, new Crockford(), 'hex');

Using the encode and decode methods of the Crockford class.

use Ocubom\Math\Crockford;

// Encoding
$crockford = Crockford::encode(random_bytes(32), 'bin');

// Decoding
$hex = Crockford::decode($crockford, 'hex');

Using the crockford_encode and crockford_decode functions.

use function \Ocubom\Math\crockford_decode;
use function \Ocubom\Math\crockford_encode;

// Encoding
$crockford = crockford_encode(random_bytes(32), 'bin');

// Decoding
$hex = crockford_decode($crockford, 'hex');

An additional parameter can be added to include a checksum for error detection.

Satoshi Nakamoto Base 58 encoding

Bitcoin addresses use a variant of Base 64 that omits characters that can lead to confusion. The result is a Base 58 encoding.

Note

Why base-58 instead of standard base-64 encoding?

Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking data.

A string with non-alphanumeric characters is not as easily accepted as input.

E-mail usually won't line-break if there's no punctuation to break at.

Double-clicking selects the whole string as one word if it's all alphanumeric.

-- Satoshi Nakamoto. Bitcoin source code

This encoding is accessible by passing a Base58 object as any of the base arguments of the base_convert function.

use Ocubom\Math\Base\Base58;
use function Ocubom\Math\base_convert;

// Encoding
$base58 = base_convert(random_bytes(32), 'bin', new Base58());

// Decoding
$hex = base_convert($base58, new Base58(), 'hex');

Roadmap

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Fork the Project.
Create your Feature Branch (git checkout -b feature/your-feature).
Commit your Changes (git commit -m 'Add your-feature').
Push to the Branch (git push origin feature/your-feature).
Open a Pull Request.

Authorship

Oscar Cubo Medina — https://ocubom.github.io

See also the list of contributors who participated in this project.

License

Distributed under the MIT License. See LICENSE for more information.

ocubom / base-convert

Maintainers

Details