Merge pull request #31 from nicobleiler/alpha

Promote alpha to beta

Author: nicobleiler

.coderabbit.yaml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+early_access: true
+
+reviews:
+  profile: "assertive"
+  high_level_summary: true
+  collapse_walkthrough: false
+  review_status: false
+
+  auto_review:
+    enabled: true
+    drafts: false
+    ignore_title_keywords:
+      - "WIP"
+    base_branches:
+      - dev
+      - alpha

.gitattributes

@@ -0,0 +1,21 @@
+* text=auto
+
+*.md diff=markdown
+*.php diff=php
+
+/.github export-ignore
+/tests export-ignore
+/benchmarks export-ignore
+/scripts export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.coderabbit.yaml export-ignore
+AGENTS.md export-ignore
+CONTRIBUTING.md export-ignore
+phpbench.json export-ignore
+phpstan.neon export-ignore
+phpunit.xml export-ignore
+pint.json export-ignore
+rector.php export-ignore
+renovate.json export-ignore
+.releaserc export-ignore

AGENTS.md

@@ -58,6 +58,7 @@ Agents should run tests after meaningful changes, especially for behavior update
 
 - Default behavior relies on the bundled EFF long list.
 - Custom word lists are provided as PHP arrays (config `word_list` or `WordList::fromArray()`).
+- Optional exclusion of words is provided via config `excluded_words` and `$wordlist->excludeWords()`.
 - Do not add logging/output that could leak generated passphrases.
 
 ## Laravel Integration Notes

README.md

@@ -3,6 +3,8 @@
 [![Latest Version](https://img.shields.io/packagist/v/nicobleiler/php-passphrase.svg)](https://packagist.org/packages/nicobleiler/php-passphrase)
 [![Downloads](https://img.shields.io/packagist/dt/nicobleiler/php-passphrase.svg)](https://packagist.org/packages/nicobleiler/php-passphrase)
 [![PHP Version](https://img.shields.io/packagist/php-v/nicobleiler/php-passphrase.svg)](https://packagist.org/packages/nicobleiler/php-passphrase)
+[![Code Size](https://img.shields.io/github/languages/code-size/nicobleiler/php-passphrase)](https://github.com/nicobleiler/php-passphrase)
+[![Wordlist Size](https://img.shields.io/github/size/nicobleiler/php-passphrase/resources/wordlists/eff_large_wordlist.php?label=wordlist)](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://img.shields.io/packagist/l/nicobleiler/php-passphrase.svg)](LICENSE)
 
@@ -110,7 +112,7 @@ echo $generator->generate(); // deterministic output
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
-| `numWords` | `?int` | `3` | Number of words (3–20). `null` uses instance/config default. |
+| `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. |
@@ -139,6 +141,10 @@ return [
     // 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'      => [],
 ];
 ```
 
@@ -153,6 +159,9 @@ Provide `word_list` as a PHP array of strings:
 ```php
 // 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:
@@ -193,10 +202,49 @@ 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](https://sdk-api-docs.bitwarden.com/src/bitwarden_generators/passphrase.rs.html):
 
+### Sequence diagram
+
+```mermaid
+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
 
 ```bash
@@ -219,40 +267,46 @@ The test suite includes tests modeled after Bitwarden's own test cases:
 - EFF word list integrity
 - Laravel integration (service provider, facade, config defaults)
 
-## Performance (2026-02-14 02:41:47 MEZ)
+## Performance (2026-02-16)
 
 These benchmarks were run on a local Ryzen 9 5950X machine running Windows 11 with PHP 8.5.0.
 
-In warm-run benchmarks at similar entropy targets, php-passphrase is ~4.4× faster than genphrase/genphrase and ~1333× faster than martbock/laravel-diceware (based on mean time per generation).
-
-In cold-run benchmarks (startup + first generation), php-passphrase is ~5.6× faster than genphrase/genphrase and ~12.8× faster than martbock/laravel-diceware (based on mean time per generation).
+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.
 
-```
+```text
 benchGenerateCold
-+----------------+-----------------------------------------------------+------+-----+-----------+-----------+---------+----------+
-| benchmark      | set                                                 | revs | its | mem_peak  | mode      | mean    | rstdev   |
-+----------------+-----------------------------------------------------+------+-----+-----------+-----------+---------+----------+
-| ProvidersBench | php-passphrase (EFF 5 words, ~64.6 bits)            | 1    | 20  | 1.614mb   | 127.847μs | 320.5μs | ±241.90% |
-| ProvidersBench | genphrase/genphrase (65-bit target, diceware)       | 1    | 20  | 1.364mb   | 1.654ms   | 1.806ms | ±27.58%  |
-| ProvidersBench | martbock/laravel-diceware (EFF 5 words, ~64.6 bits) | 1    | 20  | 957.688kb | 3.608ms   | 4.106ms | ±35.28%  |
-| ProvidersBench | random_bytes(8) hex (~64 bits)                      | 1    | 20  | 493.784kb | 7.74μs    | 8.8μs   | ±21.14%  |
-| ProvidersBench | Illuminate\Support\Str::random(11) (~65.5 bits)     | 1    | 20  | 493.8kb   | 175.25μs  | 241μs   | ±79.83%  |
-+----------------+-----------------------------------------------------+------+-----+-----------+-----------+---------+----------+
++----------------+--------------------------------------------------------------------+------+-----+-----------+-----------+----------+----------+
+| 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  | 494.048kb | 1.596μs | 1.612μs | ±3.79% |
-| ProvidersBench | genphrase/genphrase (65-bit target, diceware)       | 100  | 20  | 1.363mb   | 6.956μs | 7.091μs | ±6.42% |
-| ProvidersBench | martbock/laravel-diceware (EFF 5 words, ~64.6 bits) | 100  | 20  | 508.944kb | 2.161ms | 2.149ms | ±2.87% |
-| ProvidersBench | random_bytes(8) hex (~64 bits)                      | 100  | 20  | 494.04kb  | 0.125μs | 0.125μs | ±7.38% |
-| ProvidersBench | Illuminate\Support\Str::random(11) (~65.5 bits)     | 100  | 20  | 494.056kb | 0.56μs  | 0.565μs | ±3.86% |
-+----------------+-----------------------------------------------------+------+-----+-----------+---------+---------+--------+
++----------------+--------------------------------------------------------------------+------+-----+-----------+---------+----------+---------+
+| 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:
@@ -283,10 +337,55 @@ vendor/bin/phpbench run --report=providers --iterations=40 --revs=5 --retry-thre
 Compared providers:
 
 - `php-passphrase` with EFF 5 words (~64.6 bits)
-- `genphrase/genphrase` with a 65-bit target on diceware mode
-- `martbock/laravel-diceware` 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:
+
+```json
+{
+    "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:
+
+```bash
+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:
 

benchmarks/ProvidersBench.php

@@ -4,6 +4,7 @@
 
 namespace NicoBleiler\Passphrase\Benchmarks;
 
+use Eurosat7\Random\Generator as EurosatRandomGenerator;
 use GenPhrase\Password;
 use Illuminate\Container\Container;
 use Illuminate\Filesystem\Filesystem;
@@ -70,6 +71,14 @@ public function provideProviders(): iterable
             ];
         }
 
+        if (class_exists(EurosatRandomGenerator::class)) {
+            yield 'eurosat7/random Generator::password(10) (~64+ bits)' => [
+                'provider' => 'eurosat7-random-password',
+                'kind' => 'baseline',
+                'entropy_bits' => 64.0,
+            ];
+        }
+
         yield 'random_bytes(8) hex (~64 bits)' => [
             'provider' => 'random-bytes',
             'kind' => 'baseline',
@@ -98,6 +107,7 @@ private function createGenerator(string $provider): callable
             'php-passphrase' => $this->phpPassphraseGenerator(),
             'genphrase' => $this->genphraseGenerator(),
             'laravel-diceware' => $this->laravelDicewareGenerator(),
+            'eurosat7-random-password' => static fn (): string => EurosatRandomGenerator::password(10),
             'random-bytes' => static fn (): string => bin2hex(random_bytes(8)),
             'illuminate-str-random' => static fn (): string => Str::random(11),
             'illuminate-str-password' => static fn (): string => Str::password(10),

config/passphrase.php

@@ -8,7 +8,7 @@
     |--------------------------------------------------------------------------
     |
     | The default number of words to include in a generated passphrase.
-    | Must be between 3 and 20.
+    | Must be a minimum of 3.
     |
     */
     'num_words' => 3,
@@ -57,4 +57,17 @@
     */
     'word_list' => null,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Excluded Words
+    |--------------------------------------------------------------------------
+    |
+    | Words that should be removed from the configured word list.
+    |
+    | Set to an empty array to disable word exclusion.
+    | Or provide your own list, for example: ['incorrect', 'wrong', 'fail', 'error']
+    |
+    */
+    'excluded_words' => [],
+
 ];

src/Exceptions/InvalidEntropyBitsTargetException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NicoBleiler\Passphrase\Exceptions;
+
+use InvalidArgumentException;
+
+class InvalidEntropyBitsTargetException extends InvalidArgumentException
+{
+    public function __construct()
+    {
+        parent::__construct('Target entropy bits must be greater than 0');
+    }
+}

src/Exceptions/WordListException.php

@@ -27,4 +27,14 @@ public static function invalidType(): self
     {
         return new self('Word list must contain only strings');
     }
+
+    public static function invalidExcludedWordsType(): self
+    {
+        return new self('Excluded words must contain only strings');
+    }
+
+    public static function invalidExcludedWordsConfigType(): self
+    {
+        return new self('Excluded words config must be an array of strings');
+    }
 }