PHPackages vpapaloukas/dice-passphrase - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. vpapaloukas/dice-passphrase ActiveLibrary[Utility & Helpers](/categories/utility) vpapaloukas/dice-passphrase =========================== Dice Passphrase Generator 1.0.0(7mo ago)11MITPHPPHP >=8.0 Since Oct 4Pushed 7mo agoCompare [ Source](https://github.com/vpapaloukas/dice-passphrase)[ Packagist](https://packagist.org/packages/vpapaloukas/dice-passphrase)[ RSS](/packages/vpapaloukas-dice-passphrase/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (1)Versions (2)Used By (0) Dice Passphrase Generator ========================= [](#dice-passphrase-generator) A PHP library for generating secure, memorable passphrases based on [EFF Dice-Generated Passphrases](https://www.eff.org/dice). Features -------- [](#features) - **Secure Random Generation**: Uses PHP's `random_int()` for cryptographically secure randomness - **Multiple Word Lists**: Support for embedded English word list and custom file-based word lists - **Flexible Output**: Generate passphrases as arrays or formatted strings - **Easy Integration**: Simple factory methods and static convenience functions - **Full Validation**: Comprehensive word list validation and error handling - **PHP 8.0+ Compatible**: Modern PHP with strict typing and best practices Installation ------------ [](#installation) Install via Composer: ``` composer require vpapaloukas/dice-passphrase ``` Quick Start ----------- [](#quick-start) ### Basic Usage [](#basic-usage) ``` use Vpap\DicePassphrase\PassphraseGenerator; // Generate a 6-word passphrase (default) $passphrase = PassphraseGenerator::quickString(); echo $passphrase; // "correct horse battery staple example word" // Generate a 4-word passphrase $passphrase = PassphraseGenerator::quickString(4); echo $passphrase; // "secure random example phrase" // Generate as array $words = PassphraseGenerator::quick(5); print_r($words); // ["secure", "random", "example", "phrase", "generator"] ``` ### Using the Factory [](#using-the-factory) ``` use Vpap\DicePassphrase\PassphraseGeneratorFactory; // Create generator with default English word list $generator = PassphraseGeneratorFactory::createWithDefaultEnglishWordList(); // Generate passphrases $passphrase = $generator->generateString(6); $words = $generator->generate(4); ``` Advanced Usage -------------- [](#advanced-usage) ### Custom Separators [](#custom-separators) ``` use Vpap\DicePassphrase\PassphraseGenerator; // Use custom separator $passphrase = PassphraseGenerator::quickString(4, '-'); echo $passphrase; // "correct-horse-battery-staple" // No separator (concatenated) $passphrase = PassphraseGenerator::quickString(3, ''); echo $passphrase; // "correcthorsebattery" ``` ### File-Based Word Lists [](#file-based-word-lists) ``` use Vpap\DicePassphrase\PassphraseGenerator; use Vpap\DicePassphrase\PassphraseGeneratorFactory; // Using static methods $passphrase = PassphraseGenerator::quickStringFromFile('/path/to/wordlist.txt', 5); // Using factory $generator = PassphraseGeneratorFactory::createWithFileWordList('/path/to/wordlist.txt'); $passphrase = $generator->generateString(6); ``` ### Custom Word Lists [](#custom-word-lists) ``` use Vpap\DicePassphrase\PassphraseGeneratorFactory; // Create custom word list (must have exactly 7776 entries) $customWords = [ '11111' => 'apple', '11112' => 'banana', // ... all combinations from 11111 to 66666 '66666' => 'zebra' ]; $generator = PassphraseGeneratorFactory::createWithEmbeddedWordList($customWords); $passphrase = $generator->generateString(4); ``` ### Manual Component Wiring [](#manual-component-wiring) ``` use Vpap\DicePassphrase\PassphraseGenerator; use Vpap\DicePassphrase\WordList\EmbeddedWordList; use Vpap\DicePassphrase\Random\SecureRandomGenerator; // Manual dependency injection $wordList = new EmbeddedWordList(); $randomGenerator = new SecureRandomGenerator(); $generator = new PassphraseGenerator($wordList, $randomGenerator); $passphrase = $generator->generateString(5); ``` Word List Format ---------------- [](#word-list-format) Word lists must follow the standard Diceware format: ``` 11111 word1 11112 word2 11113 word3 ... 66666 word7776 ``` ### Requirements [](#requirements) - Exactly 7776 entries (6^5 possible dice roll combinations) - Each line: five digits (1-6) + space + word - All dice roll combinations from 11111 to 66666 must be present - Empty lines and comments (starting with #) are ignored ### Example Word List File [](#example-word-list-file) ``` # English Diceware Word List # Comments are ignored 11111 abacus 11112 abdomen 11113 abdominal # ... more entries 66664 zoom 66665 zoology 66666 zucchini ``` API Reference ------------- [](#api-reference) ### PassphraseGenerator [](#passphrasegenerator) #### Constructor [](#constructor) ``` public function __construct( WordListInterface $wordList, SecureRandomGenerator $randomGenerator ) ``` #### Methods [](#methods) ``` // Generate passphrase as array public function generate(int $wordCount = 6): array // Generate passphrase as string public function generateString(int $wordCount = 6, string $separator = ' '): string // Static convenience methods public static function quick(int $wordCount = 6): array public static function quickString(int $wordCount = 6, string $separator = ' '): string public static function quickFromFile(string $filePath, int $wordCount = 6): array public static function quickStringFromFile(string $filePath, int $wordCount = 6, string $separator = ' '): string ``` ### PassphraseGeneratorFactory [](#passphrasegeneratorfactory) ``` // Create with default English word list public static function createWithDefaultEnglishWordList(): PassphraseGenerator // Create with custom embedded word list public static function createWithEmbeddedWordList(array $wordList): PassphraseGenerator // Create with file-based word list public static function createWithFileWordList(string $filePath): PassphraseGenerator // Create with custom dependencies public static function createWithCustomDependencies( WordListInterface $wordList, ?SecureRandomGenerator $randomGenerator = null ): PassphraseGenerator ``` Error Handling -------------- [](#error-handling) The library throws specific exceptions for different error conditions: ``` use Vpap\DicePassphrase\Exception\InvalidWordCountException; use Vpap\DicePassphrase\Exception\InvalidWordListException; use Vpap\DicePassphrase\Exception\WordListNotFoundException; try { $generator = PassphraseGeneratorFactory::createWithDefaultEnglishWordList(); $passphrase = $generator->generate(0); // Invalid word count } catch (InvalidWordCountException $e) { echo "Invalid word count: " . $e->getMessage(); } catch (InvalidWordListException $e) { echo "Invalid word list: " . $e->getMessage(); } catch (WordListNotFoundException $e) { echo "Word list file not found: " . $e->getMessage(); } ``` Security Considerations ----------------------- [](#security-considerations) - Uses `random_int()` for cryptographically secure random number generation - Each dice roll is equivalent to rolling five physical dice - Word selection is truly random and unpredictable - No entropy is lost in the generation process - Suitable for generating passwords and security tokens Performance ----------- [](#performance) - **Memory Efficient**: Word lists are loaded once and cached - **Fast Lookup**: O(1) word lookup using associative arrays - **Minimal Overhead**: No unnecessary object creation during generation - **Scalable**: Can generate thousands of passphrases efficiently Requirements ------------ [](#requirements-1) - PHP 8.0 or higher - No external dependencies for core functionality - PHPUnit 10+ for development and testing Testing ------- [](#testing) Run the test suite: ``` composer test ``` Run with coverage: ``` composer test-coverage ``` Contributing ------------ [](#contributing) 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass 5. Submit a pull request License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. Acknowledgments --------------- [](#acknowledgments) - Based on the Diceware method created by Arnold Reinhold - Uses the standard English Diceware word list - Inspired by the need for secure, memorable passphrases Examples -------- [](#examples) ### Generate Multiple Passphrases [](#generate-multiple-passphrases) ``` use Vpap\DicePassphrase\PassphraseGeneratorFactory; $generator = PassphraseGeneratorFactory::createWithDefaultEnglishWordList(); // Generate 10 different passphrases for ($i = 0; $i < 10; $i++) { echo $generator->generateString(5) . "\n"; } ``` ### Password Strength Comparison [](#password-strength-comparison) ``` use Vpap\DicePassphrase\PassphraseGenerator; // Different security levels $weak = PassphraseGenerator::quickString(3); // ~77 bits of entropy $strong = PassphraseGenerator::quickString(5); // ~129 bits of entropy $very_strong = PassphraseGenerator::quickString(7); // ~180 bits of entropy echo "Weak (3 words): $weak\n"; echo "Strong (5 words): $strong\n"; echo "Very Strong (7 words): $very_strong\n"; ``` ### Integration with Authentication Systems [](#integration-with-authentication-systems) ``` use Vpap\DicePassphrase\PassphraseGenerator; class UserRegistration { public function generateTemporaryPassword(): string { // Generate a secure temporary password return PassphraseGenerator::quickString(4, '-'); } public function generateRecoveryCode(): string { // Generate a recovery code without spaces return PassphraseGenerator::quickString(6, ''); } } ``` ### Health Score 31 — LowBetter than 68% of packages Maintenance68 Regular maintenance activity Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity40 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 217d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7260b69b27e9e1df7294d459133451c30dab2967b6b4757a3d64058357ef18cf?d=identicon)[vpap](/maintainers/vpap) --- Top Contributors [![vpapaloukas](https://avatars.githubusercontent.com/u/29273535?v=4)](https://github.com/vpapaloukas "vpapaloukas (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/vpapaloukas-dice-passphrase/health.svg) ``` [![Health](https://phpackages.com/badges/vpapaloukas-dice-passphrase/health.svg)](https://phpackages.com/packages/vpapaloukas-dice-passphrase) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)