Merge pull request #30 from nicobleiler/dev

Release: Promote dev to alpha

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

README.md

@@ -5,7 +5,8 @@
 [![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)
+[![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)
 
 A Bitwarden-inspired passphrase generator for PHP with first-class Laravel integration.
 
@@ -111,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. |

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,

src/PassphraseGenerator.php

@@ -11,16 +11,48 @@
 
 class PassphraseGenerator
 {
+    /**
+     * Minimum allowed number of words in a generated passphrase.
+     *
+     * @internal
+     */
     public const MINIMUM_NUM_WORDS = 3;
 
+    /**
+     * Maximum allowed number of words in a generated passphrase.
+     *
+     * @internal
+     *
+     * @deprecated This constant is planned for removal in the next major version. Do not rely on a fixed maximum word count.
+     */
     public const MAXIMUM_NUM_WORDS = 20;
 
+    /**
+     * Default number of words used when no explicit value is provided.
+     *
+     * @internal
+     */
     public const DEFAULT_NUM_WORDS = 3;
 
+    /**
+     * Default separator used between words in generated passphrases.
+     *
+     * @internal
+     */
     public const DEFAULT_WORD_SEPARATOR = '-';
 
+    /**
+     * Default capitalization setting for generated passphrases.
+     *
+     * @internal
+     */
     public const DEFAULT_CAPITALIZE = false;
 
+    /**
+     * Default setting for appending a random digit to a generated passphrase.
+     *
+     * @internal
+     */
     public const DEFAULT_INCLUDE_NUMBER = false;
 
     private WordList $wordList;
@@ -71,10 +103,10 @@ public function setDefaults(
      * Parameters default to the instance defaults set via setDefaults().
      * In Laravel, these come from config/passphrase.php.
      *
-     * @param  ?int  $numWords  Number of words (MINIMUM_NUM_WORDS-MAXIMUM_NUM_WORDS), null to use instance default
+     * @param  ?int  $numWords  Number of words (minimum 3), null to use instance default
      * @param  ?string  $wordSeparator  Character(s) to separate words, null to use instance default
      * @param  ?bool  $capitalize  Capitalize first letter of each word, null to use instance default
-     * @param  ?bool  $includeNumber  Append a random digit to a random word, null to use instance default
+     * @param  ?bool  $includeNumber  Append a random digit (0-9) to a random word, null to use instance default
      * @param  ?int  $targetEntropyBits  Optional. If set, adjusts numWords to meet or exceed this target entropy.
      *                                   Entropy is calculated conservatively only based on the number of words in the word list, ignoring the additional entropy from numbers.
      */

tests/LaravelIntegrationTest.php

@@ -211,4 +211,24 @@ public function test_config_include_number_is_applied(): void
         $result = Passphrase::generate();
         $this->assertMatchesRegularExpression('/\d/', $result, 'Expected passphrase to contain a digit');
     }
+
+    public function test_target_entropy_bits_with_excluded_words_config(): void
+    {
+        $words = ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel'];
+        $excluded = ['echo', 'foxtrot', 'golf', 'hotel'];
+        $diff = array_diff($words, $excluded);
+        $targetEntropyBits = 10;
+        $entropyPerWord = log(count($diff), 2);
+        $expectedNumWords = (int) ceil($targetEntropyBits / $entropyPerWord);
+
+        config([
+            'passphrase.word_list' => $words,
+            'passphrase.excluded_words' => $excluded,
+        ]);
+
+        $this->refreshServiceProvider();
+
+        $result = Passphrase::generate(wordSeparator: '-', targetEntropyBits: $targetEntropyBits);
+        $this->assertCount($expectedNumWords, explode('-', $result));
+    }
 }

tests/PassphraseGeneratorTest.php

@@ -452,6 +452,26 @@ public function test_target_entropy_bits_overrides_num_words_param(): void
         $this->assertCount($expectedNumWords, explode('-', $result));
     }
 
+    public function test_target_entropy_bits_with_excluded_words_increases_word_count(): void
+    {
+        $words = ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel'];
+        $wordList = WordList::fromArray($words);
+        $targetEntropyBits = 10;
+
+        $generator = new PassphraseGenerator($wordList);
+
+        $expectedNumWords = (int) ceil($targetEntropyBits / $wordList->entropyPerWord());
+        $result = $generator->generate(wordSeparator: '|', targetEntropyBits: $targetEntropyBits);
+        $this->assertCount($expectedNumWords, explode('|', $result));
+
+        $filteredWordList = $wordList->excludeWords(['echo', 'foxtrot', 'golf', 'hotel']);
+        $generatorWithExcluded = new PassphraseGenerator($filteredWordList);
+
+        $expectedNumWordsWithExcluded = (int) ceil($targetEntropyBits / $filteredWordList->entropyPerWord());
+        $resultWithExcluded = $generatorWithExcluded->generate(wordSeparator: '|', targetEntropyBits: $targetEntropyBits);
+        $this->assertCount($expectedNumWordsWithExcluded, explode('|', $resultWithExcluded));
+    }
+
     // -------------------------------------------------------
     // EFF word list tests
     // -------------------------------------------------------