README

Mnemonic BIP39 implementation in PHP

Installation

Prerequisite

• PHP ^8.2
• ext-mbstring (MultiByte string PHP ext. for non-english wordlist)

Composer

composer require sakoora0x/bip39-mnemonic-php

Generating a Secure Mnemonic

Generate a mnemonic using a secure PRNG implementation.

BIP39::fromRandom

Returns instance of Mnemonic class.

Example:

// Generate entropy using PRNG
$mnemonic = \sakoora0x\BIP39\BIP39::fromRandom(
    \sakoora0x\BIP39\Language\English::getInstance(),
    wordCount: 12
);

# array(12) { [0]=> string(4) "tape" [1]=> string(8) "solution" ... [10]=> string(6) "border" [11]=> string(6) "sample" }
var_dump($mnemonic->words);
# string(32) "ddd9dbcd1b07a09c16f080637818675f"
var_dump($mnemonic->entropy);

Entropy to Mnemonic

Generate mnemonic codes from given entropy

BIP39::fromEntropy

Returns instance of Mnemonic class.

Example:

$mnemonic = \sakoora0x\BIP39\BIP39::fromEntropy(
    hex2bin("ddd9dbcd1b07a09c16f080637818675f"),
    \sakoora0x\BIP39\Language\English::getInstance()
);

# array(12) { [0]=> string(4) "tape" [1]=> string(8) "solution" ... [10]=> string(6) "border" [11]=> string(6) "sample" }
var_dump($mnemonic->words);

Mnemonic sentence/Words to Mnemonic

Generate entropy from mnemonic codes

BIP39::fromWords

Returns instance of Mnemonic class.

Example:

$mnemonic = \sakoora0x\BIP39\BIP39::fromWords(
    ["tape", "solution", "viable", "current", "key",
        "evoke", "forward", "avoid", "gloom", "school", "border", "sample"],
    \sakoora0x\BIP39\Language\English::getInstance()
);

#string(32) "ddd9dbcd1b07a09c16f080637818675f"
var_dump($mnemonic->entropy);

Mnemonic Class

readonly class Mnemonic

This lib will create this Mnemonic object as a result:

Generating Seed with Passphrase

Mnemonic->generateSeed

Generates seed from a mnemonic as per BIP39 specifications.

Returns:

Generate non-english mnemonic codes

Check AbstractLanguage and AbstractLanguageFile classes. English class has all 2048 words pre-loaded instead of reading from a local file every time. To implement other languages or custom set of 2048 words, check ChineseWords.php file in tests directory for example of implementation.

class CustomWords extends \sakoora0x\BIP39\Language\AbstractLanguageFile
{
    /**
     * @return static
     */
    protected static function constructor(): static
    {
        return new static(
            language: "some_language",
            words: static::wordsFromFile(
                pathToFile: "/path/to/wordlist.txt",
                eolChar: PHP_EOL
            ),
            mbEncoding: "UTF-8"
        );
    }
}

and then use in place of AbstractLanguage where required:

CustomWords::getInstance()

Test Vectors

Include PHPUnit tests for all test vectors mentioned in official BIP-0039 specification.

Running Tests

Install dependencies:

composer install

Run tests:

./vendor/bin/phpunit

Run tests with verbose output:

./vendor/bin/phpunit --testdox