PHPackages                             nicobleiler/php-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. [Security](/categories/security)
4. /
5. nicobleiler/php-passphrase

ActiveLibrary[Security](/categories/security)

nicobleiler/php-passphrase
==========================

Passphrase generator with Laravel integration, inspired by Bitwarden. Uses the EFF long word list by default with support for custom wordlists.

v2.1.0(2mo ago)451.7k↓17%[1 PRs](https://github.com/nicobleiler/php-passphrase/pulls)MITPHPPHP ^8.2CI failing

Since Feb 13Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/nicobleiler/php-passphrase)[ Packagist](https://packagist.org/packages/nicobleiler/php-passphrase)[ RSS](/packages/nicobleiler-php-passphrase/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (12)Versions (31)Used By (0)

PHP Passphrase Generator
========================

[](#php-passphrase-generator)

[![Latest Version](https://camo.githubusercontent.com/f282e0e2859047642db89f51a97e7b4deb49c9fefa3a7448360e91c98d652256/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e69636f626c65696c65722f7068702d706173737068726173652e737667)](https://packagist.org/packages/nicobleiler/php-passphrase)[![Downloads](https://camo.githubusercontent.com/88e3692d5038d1db162973344882d69e32af5d49acc87050a46fb1e6f4f1800e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e69636f626c65696c65722f7068702d706173737068726173652e737667)](https://packagist.org/packages/nicobleiler/php-passphrase)[![PHP Version](https://camo.githubusercontent.com/1d98414db41456860ccef22a63e4c20c050ce26d9140cc67de71848f6cc228ed/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e69636f626c65696c65722f7068702d706173737068726173652e737667)](https://packagist.org/packages/nicobleiler/php-passphrase)[![Code Size](https://camo.githubusercontent.com/f5e39620e256cdcccb0e59a693366fd25090818176a20c56f1502c1d6fbc86a3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6e69636f626c65696c65722f7068702d70617373706872617365)](https://github.com/nicobleiler/php-passphrase)[![Wordlist Size](https://camo.githubusercontent.com/ea9ee6710a44c9891a6bb8e0a260e5f1da5299093627970a3f7cbeafce250f29/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73697a652f6e69636f626c65696c65722f7068702d706173737068726173652f7265736f75726365732f776f72646c697374732f6566665f6c617267655f776f72646c6973742e7068703f6c6162656c3d776f72646c697374)](https://github.com/nicobleiler/php-passphrase/blob/master/resources/wordlists/eff_large_wordlist.php)[![CI](https://github.com/nicobleiler/php-passphrase/actions/workflows/test.yml/badge.svg)](https://github.com/nicobleiler/php-passphrase/actions/workflows/test.yml)[![License](https://camo.githubusercontent.com/207dbe20b4b5385344d501287aee9bf23b99bcf66d733ec90bc0b6c2ef9b8cbc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e69636f626c65696c65722f7068702d706173737068726173652e737667)](LICENSE)

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

Generates secure, memorable passphrases using the [EFF long word list](https://www.eff.org/dice) (7,776 words) by default, with full support for custom word lists.

Installation
------------

[](#installation)

```
composer require nicobleiler/php-passphrase
```

Laravel will auto-discover the service provider. For other frameworks, see [Standalone Usage](#standalone-usage).

Quick Start
-----------

[](#quick-start)

### Laravel (Facade)

[](#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)

[](#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

[](#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

[](#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
-------

[](#options)

ParameterTypeDefaultDescription`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](https://bitwarden.com/passphrase-generator/) exactly.

Configuration
-------------

[](#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
----------

[](#word-lists)

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

### Via Config (Laravel)

[](#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