- How do I install nicobleiler/php-passphrase in a Laravel application?
- Install it with Composer using composer require nicobleiler/php-passphrase. The package ships a Laravel service provider that is auto-discovered, so no manual registration is needed in config/app.php. Publish the configuration file with php artisan vendor:publish to customise word counts, separators, and wordlists. There is no database, queue, or external service involved, so installation is essentially just the Composer step plus optional config publishing.
- Which Laravel and PHP versions does php-passphrase support?
- The 2.2.x line aligns with the Laravel 11 and 12 generation, and its Testbench dependency was bumped to ^11.0, which is consistent with that support range. Because the package is a small, low-coupling utility with no framework-specific persistence, it generally works across recent Laravel versions, but you should confirm the exact constraints in composer.json against your own application before adopting it. Always verify the supported PHP range there too, especially if you are still running an older PHP runtime.
- How do I configure the number of words, separator, capitalization, and numbers in a passphrase?
- The published config file exposes options including num_words, word_separator, capitalize, and include_number. Set these values to control how many words are drawn from the wordlist, what character joins them, whether each word is capitalised, and whether a digit is appended. Typical output looks like correct-horse-battery-staple, and raising num_words is the primary way to increase entropy. Keep the config in version control so passphrase strength does not drift between environments.
- Can I use a custom wordlist instead of the EFF long word list?
- Yes. The package uses the EFF long word list by default but supports custom wordlists through configuration, which is useful for policy compliance, localisation, or shorter lists for lower-security contexts. Point the wordlist config at your own list and keep it stable, because changing the list changes the entropy per word. Note that custom lists with fewer entries reduce entropy per word, so compensate by increasing num_words. From 2.2.0 onward the wordlist value is validated at runtime, so malformed or missing lists raise an exception instead of silently degrading.
- How do I generate a passphrase with the Passphrase facade?
- Resolve the Passphrase facade and call the generation method, which returns a ready-to-use string built from your configured word count, separator, and formatting options. Because it is a facade over a service provider binding, you can also inject the underlying service into your own classes for easier testing. A common pattern is to wrap the facade in your own thin service so the package API and its exceptions stay out of domain code. That wrapper also makes swapping or downgrading the package later a single-file change.
- How strong is a passphrase generated by this Diceware-style package?
- The package is inspired by Bitwarden and follows Diceware-style generation, drawing words from the EFF long word list, which contains 7776 entries and therefore provides roughly 12.9 bits of entropy per word. A six-word passphrase lands around 77 bits, which is strong for user-facing credentials, while shorter configurations drop quickly. Because words are chosen randomly rather than by pattern, the strength comes from the word count rather than from separators or capitalisation. Increase num_words if your threat model or compliance rules demand more entropy.
- Why won't Composer install version 2.2.0-beta.1 of php-passphrase?
- Version 2.2.0-beta.1 is a pre-release, so Composer will not resolve it under a default minimum-stability of stable. You must either pin the exact version, for example composer require nicobleiler/php-passphrase:2.2.0-beta.1, or add a stability flag scoped specifically to this package. Treat that as a deliberate, reviewable decision rather than a drop-in upgrade. For production workloads, staying on the latest 2.1.x stable release until 2.2.0 reaches general availability is the lower-risk path.
- What is ConfigException in php-passphrase and can it break application boot?
- ConfigException is a dedicated exception introduced in 2.2.0-beta.1 as part of a hardening release that adds runtime type validation for the word list, excluded words, num_words, word_separator, capitalize, and include_number. Configurations that previously passed silently may now fail loudly. The critical question is timing: if validation runs during the service provider register or boot phase, a misconfiguration becomes an application-boot failure rather than a runtime error at the call site, taking the whole app down. Verify on a non-production branch whether validation is eager or lazy, and review any existing try/catch blocks around passphrase generation, since catching a generic Exception or RuntimeException may not catch this new type.
- Are .env values like "true" and "5" coerced to booleans and integers automatically?
- Do not assume so. The stricter validation added in 2.2.0-beta.1 checks types for capitalize, include_number, and num_words, and values coming from env() commonly arrive as strings, which may no longer satisfy those checks. The safe approach is to cast explicitly in your config file, for example using env('PASSPHRASE_NUM_WORDS', 6) with an (int) cast, and env('PASSPHRASE_CAPITALIZE', false) with a filter_var boolean cast. Because the coercion behaviour is not clearly documented for the beta, test your actual .env-driven configuration before rolling it out.
- How do I test passphrase generation in my Laravel test suite?
- Because the package is a stateless service with no database or queue dependencies, you can call it directly in tests without any special test harness. Override the package config values with config() inside your test to pin num_words, word_separator, capitalize, and include_number, then assert on the shape of the output rather than the exact string, since generation is random. Assert structural properties such as word count and separator, and assert entropy-related expectations by testing that increasing num_words increases the number of segments. If you wrap the facade in your own service, you can mock that wrapper in tests that are not concerned with passphrase generation itself.