README

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

composer require nicobleiler/php-passphrase

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

Quick Start

Laravel (Facade)

use NicoBleiler\Passphrase\Facades\Passphrase;

// Default: 3 words, hyphen separator, no capitalize, no number
Passphrase::generate();
// "candle-rubber-glimpse"

// Customize everything
Passphrase::generate(
    numWords: 5,
    wordSeparator: '.',
    capitalize: true,
    includeNumber: true,
);
// "Candle.Rubber3.Glimpse.Obtain.Willow"

Laravel (Dependency Injection)

use NicoBleiler\Passphrase\PassphraseGenerator;

class AuthController
{
    public function __construct(
        private PassphraseGenerator $passphrase,
    ) {}

    public function temporaryPassword(): string
    {
        return $this->passphrase->generate(
            numWords: 4,
            capitalize: true,
            includeNumber: true,
        );
    }
}

Standalone Usage

use NicoBleiler\Passphrase\PassphraseGenerator;

$generator = new PassphraseGenerator();
echo $generator->generate(); // "candle-rubber-glimpse"

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

$generator = new PassphraseGenerator();
$generator->setDefaults(
    numWords: 5,
    wordSeparator: '.',
    capitalize: true,
    includeNumber: true,
);

echo $generator->generate(); // "Candle.Rubber3.Glimpse.Obtain.Willow"

// Explicit params still override defaults
echo $generator->generate(numWords: 3, wordSeparator: '-');

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):

use NicoBleiler\Passphrase\PassphraseGenerator;
use Random\Engine\Xoshiro256StarStar;
use Random\Randomizer;

$generator = new PassphraseGenerator(
    randomizer: new Randomizer(new Xoshiro256StarStar(12345)),
);

// Same seed always produces the same passphrase
echo $generator->generate(); // deterministic output

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

Options

Parameter	Type	Default	Description
`numWords`	`?int`	`3`	Number of words (minimum of 3). `null` uses instance/config default.
`wordSeparator`	`?string`	`'-'`	Character(s) between words. `null` uses instance/config default.
`capitalize`	`?bool`	`false`	Capitalize the first letter of each word. `null` uses instance/config default.
`includeNumber`	`?bool`	`false`	Append a random digit (0–9) to one random word. `null` uses instance/config default.
`targetEntropyBits`	`?int`	`null`	Optional. Adjusts word count to meet or exceed this entropy target (in bits). Overrides `numWords` when set.

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.

$generator = new PassphraseGenerator();

// Entropy-based generation: numWords is calculated to reach at least 60 bits
echo $generator->generate(targetEntropyBits: 60);

These match Bitwarden's passphrase generator options exactly.

Configuration

Publish the config file:

php artisan vendor:publish --tag=passphrase-config

This creates config/passphrase.php:

return [
    'num_words'      => 3,
    'word_separator'  => '-',
    'capitalize'      => false,
    'include_number'  => false,

    // No 'target_entropy_bits' key: targetEntropyBits is a per-call generate() override

    // null = bundled EFF long word list (7,776 words)
    // Or provide your own word list as a PHP array of strings
    'word_list'       => null,

    // Optional words to remove from the active word list
    // Works with both bundled EFF and custom word_list values
    'excluded_words'      => [],
];

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:

// config/passphrase.php
'word_list' => ['correct', 'horse', 'battery', 'staple'],

// Optionally remove specific words from the active list
'excluded_words' => ['horse'],

Or load it from a dedicated PHP file:

// config/passphrase.php
'word_list' => require base_path('config/custom_word_list.php'),

// config/custom_word_list.php
<?php

return [
    'correct',
    'horse',
    'battery',
    'staple',
];

Programmatically

use NicoBleiler\Passphrase\WordList;
use NicoBleiler\Passphrase\PassphraseGenerator;

// From an array
$wordList = WordList::fromArray(['correct', 'horse', 'battery', 'staple']);

$generator = new PassphraseGenerator($wordList);
echo $generator->generate(numWords: 4);

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

php artisan vendor:publish --tag=passphrase-wordlists

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

sequenceDiagram
    participant Client
    participant ServiceProvider
    participant PassphraseGenerator
    participant Randomizer
    participant WordList

    Client->>ServiceProvider: Boot (Laravel)
    ServiceProvider->>WordList: Create (singleton)
    ServiceProvider->>PassphraseGenerator: Create with Randomizer(Secure)
    ServiceProvider->>PassphraseGenerator: setDefaults(config values)
    activate PassphraseGenerator
    PassphraseGenerator-->>ServiceProvider: self (fluent)
    deactivate PassphraseGenerator

    Client->>PassphraseGenerator: generate() [no params]
    activate PassphraseGenerator
    PassphraseGenerator->>PassphraseGenerator: Use instance defaults
    PassphraseGenerator->>Randomizer: getInt() [select words]
    activate Randomizer
    Randomizer-->>PassphraseGenerator: random indices
    deactivate Randomizer
    PassphraseGenerator->>WordList: wordAt(index)
    activate WordList
    WordList-->>PassphraseGenerator: word string
    deactivate WordList
    PassphraseGenerator->>Randomizer: getInt() [digit if needed]
    activate Randomizer
    Randomizer-->>PassphraseGenerator: random digit
    deactivate Randomizer
    PassphraseGenerator-->>Client: passphrase string
    deactivate PassphraseGenerator

Testing

composer test

Or directly:

vendor/bin/phpunit

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.

benchGenerateCold
+----------------+--------------------------------------------------------------------+------+-----+-----------+-----------+----------+----------+
| benchmark      | set                                                                | revs | its | mem_peak  | mode      | mean     | rstdev   |
+----------------+--------------------------------------------------------------------+------+-----+-----------+-----------+----------+----------+
| ProvidersBench | php-passphrase (EFF 5 words, ~64.6 bits)                           | 1    | 20  | 1.612mb   | 331.431μs | 504μs    | ±141.06% |
| ProvidersBench | genphrase/genphrase (65-bit target, diceware)                      | 1    | 20  | 1.366mb   | 1.662ms   | 3.788ms  | ±240.86% |
| ProvidersBench | martbock/laravel-diceware (EFF 5 words, ~64.6 bits)                | 1    | 20  | 958.76kb  | 3.68ms    | 4.745ms  | ±82.04%  |
| ProvidersBench | random_bytes(8) hex (~64 bits)                                     | 1    | 20  | 494.856kb | 9.818μs   | 11.6μs   | ±35.59%  |
| ProvidersBench | Illuminate\Support\Str::random(11) (~65.5 bits)                    | 1    | 20  | 494.872kb | 182.63μs  | 245.95μs | ±77.25%  |
| ProvidersBench | Illuminate\Support\Str::password(10) (default options, ~64.6 bits) | 1    | 20  | 1.143mb   | 921.507μs | 1.371ms  | ±132.20% |
+----------------+--------------------------------------------------------------------+------+-----+-----------+-----------+----------+----------+

benchGenerateWarm
+----------------+--------------------------------------------------------------------+------+-----+-----------+---------+----------+---------+
| benchmark      | set                                                                | revs | its | mem_peak  | mode    | mean     | rstdev  |
+----------------+--------------------------------------------------------------------+------+-----+-----------+---------+----------+---------+
| ProvidersBench | php-passphrase (EFF 5 words, ~64.6 bits)                           | 100  | 20  | 495.12kb  | 1.353μs | 1.406μs  | ±14.18% |
| ProvidersBench | genphrase/genphrase (65-bit target, diceware)                      | 100  | 20  | 1.364mb   | 6.715μs | 6.829μs  | ±3.74%  |
| ProvidersBench | martbock/laravel-diceware (EFF 5 words, ~64.6 bits)                | 100  | 20  | 510.016kb | 2.099ms | 2.073ms  | ±2.68%  |
| ProvidersBench | random_bytes(8) hex (~64 bits)                                     | 100  | 20  | 495.112kb | 0.125μs | 0.132μs  | ±24.62% |
| ProvidersBench | Illuminate\Support\Str::random(11) (~65.5 bits)                    | 100  | 20  | 495.128kb | 0.532μs | 0.563μs  | ±16.54% |
| ProvidersBench | Illuminate\Support\Str::password(10) (default options, ~64.6 bits) | 100  | 20  | 587.672kb | 11.86μs | 11.927μs | ±2.81%  |
+----------------+--------------------------------------------------------------------+------+-----+-----------+---------+----------+---------+

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:

composer bench

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:

vendor/bin/phpbench run --report=providers --iterations=40 --revs=5 --retry-threshold=5

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:

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "eurosat7/random",
                "version": "dev-main",
                "source": {
                    "type": "git",
                    "url": "https://github.com/eurosat7/random.git",
                    "reference": "main"
                },
                "autoload": {
                    "psr-4": {
                        "Eurosat7\\Random\\": "src/"
                    }
                },
                "require": {
                    "php": ">=8.2"
                }
            }
        }
    ]
}

Then run:

composer require --dev eurosat7/random:dev-main

When installed, the benchmark also includes:

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

Baseline and comparison runs:

composer bench:baseline
composer bench:compare

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

nicobleiler / php-passphrase

Maintainers

Package info

Statistics

Security