Download the PHP package nicobleiler/php-passphrase without Composer

PHP Passphrase Generator

A Bitwarden-inspired passphrase generator for PHP with first-class Laravel integration.

Generates secure, memorable passphrases using the EFF long word list (7,776 words) by default, with full support for custom word lists.

Installation

Laravel will auto-discover the service provider. For other frameworks, see Standalone Usage.

Quick Start

Laravel (Facade)

Laravel (Dependency Injection)

Standalone Usage

You can set instance-level defaults that apply whenever generate() is called without explicit parameters:

Custom Randomizer

By default, PassphraseGenerator uses PHP's cryptographically secure Random\Engine\Secure. You can inject a custom Random\Randomizer for deterministic output (e.g. testing, demos, reproducible benchmarks):

Security note: Only use non-secure engines for testing or demos. For real passphrase generation, always use the default Secure engine.

Options

All generate() parameters are nullable. For numWords, wordSeparator, capitalize, and includeNumber, passing null (or omitting them) uses defaults set via setDefaults() or config/passphrase.php in Laravel.

targetEntropyBits is evaluated per-call by generate() and is not loaded from setDefaults() (there is currently no target_entropy_bits config key).

When calling generate(), providing targetEntropyBits takes precedence over numWords.

These match Bitwarden's passphrase generator options exactly.

Configuration

Publish the config file:

This creates config/passphrase.php:

These config values are wired into PassphraseGenerator::setDefaults() and are automatically used as defaults when calling Passphrase::generate() without explicit parameters.

targetEntropyBits is not part of setDefaults() and therefore has no target_entropy_bits config key; pass it directly to generate() when you want entropy-targeted generation.

Word Lists

Note: All word lists (bundled or custom) must contain at least 2 words. This validation also applies after exclusions.

Via Config (Laravel)

Provide word_list as a PHP array of strings:

Or load it from a dedicated PHP file:

Programmatically

You can also publish the bundled EFF word list to your resources folder:

This is optional and mainly useful if you want a local copy to inspect or customize. By default, the package reads the bundled EFF list directly.

How It Works

The generation algorithm mirrors Bitwarden's Rust implementation:

Sequence diagram

Testing

Or directly:

The test suite includes tests modeled after Bitwarden's own test cases:

• Validation (word count bounds)
• Deterministic generation with seeded Xoshiro256StarStar engine
• Capitalize behavior (including Unicode)
• Number inclusion
• Separator handling (including multi-byte emoji)
• EFF word list integrity
• Laravel integration (service provider, facade, config defaults)

Performance (2026-02-16)

These benchmarks were run on a local Ryzen 9 5950X machine running Windows 11 with PHP 8.5.0.

In this run the available benchmark providers were: php-passphrase, genphrase/genphrase, martbock/laravel-diceware, random_bytes, Illuminate\\Support\\Str::random, and Illuminate\\Support\\Str::password (providers are included automatically when their packages are installed).

Note on cold runs: benchGenerateCold includes setup and first-use initialization (autoloading, object construction, and initial word-list work). Cold-run rstdev is therefore expected to be higher and should be interpreted as startup-cost signal, not steady-state throughput.

Relative comparisons (mean times):

• Cold run: php-passphrase (504 μs) is ~7.5× faster than genphrase (3.788 ms) and ~9.4× faster than martbock/laravel-diceware (4.745 ms).
• Warm run: php-passphrase (1.406 μs) is ~4.9× faster than genphrase (6.829 μs) and ~1,475× faster than martbock/laravel-diceware (2.073 ms).

These values are environment-dependent; run composer bench locally if you need numbers for a different machine or PHP version.

Benchmarking

Run the benchmark suite with:

The benchmark suite uses PHPBench and compares providers with near-matched entropy targets.

Each provider is measured in two scenarios:

• benchGenerateCold — includes provider setup + first generation (cold start)
• benchGenerateWarm — measures steady-state generation after setup warmup

Default stability settings (configured in phpbench.json):

• iterations: 20
• revolutions: 1 (cold subject), 100 (warm subject)
• warmup: 2 (warm subject only)

You can override scale from CLI when needed, for example:

Compared providers:

• php-passphrase with EFF 5 words (~64.6 bits)
• random_bytes(8) (~64 bits)
• Illuminate\\Support\\Str::random(11) (~65.5 bits)
• Illuminate\\Support\\Str::password(10) with default options (~64.6 bits)

Optional providers can be added composer require --dev genphrase/genphrase martbock/laravel-diceware and will be included in the benchmark suite if present:

• genphrase/genphrase with a 65-bit target on diceware mode
• martbock/laravel-diceware with EFF 5 words (~64.6 bits)

The eurosat7/random package cannot currently be required directly via Composer VCS because its upstream composer.json has no valid package name.

Use a local package-repository override in your composer.json instead:

Then run:

When installed, the benchmark also includes:

• eurosat7/random via Eurosat7\Random\Generator::password(10) (~64+ bits)

Baseline and comparison runs:

Requirements

• PHP 8.2+
• ext-mbstring (for multibyte/Unicode capitalization support)
• Laravel 11+ (optional, for Laravel integration)

License

MIT — see LICENSE.

Credits

• Passphrase generation logic inspired by Bitwarden
• Word list from the Electronic Frontier Foundation, licensed under CC-BY 4.0