Laravel Diceware Laravel Package

Getting Started

martbock/laravel-diceware generates diceware-style passphrases — memorable multi-word passwords built from a word list. Install it with Composer:

composer require martbock/laravel-diceware

The package auto-registers its service provider. Publish the config file to control defaults:

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

Look first at config/diceware.php (word count, separator, word list path) and the package README for the facade/service entry point. The canonical first use case is generating a human-friendly password at account creation, e.g. in a registration controller or an onboarding flow — a six-word passphrase is easy to read out loud and far stronger than a short random string.

Note: v2.1.0 adds Laravel 10 support. If you are on Laravel 10, you can use this package on the latest framework; if you are pinned to Laravel 9 or below, v2.0.0 remains available.

Implementation Patterns

Facade in controllers / actions. The idiomatic usage is a single call from the facade or injected service:

use Martbock\Diceware\Facades\Diceware;

$passphrase = Diceware::generate();       // uses configured word count
$short      = Diceware::generate(4);      // override word count

Dependency injection for testability. Rather than calling the facade directly inside business logic, inject the underlying generator so you can fake it in tests:

public function __construct(private DicewareGenerator $diceware) {}

public function createUser(array $data)
{
    $data['password'] = Hash::make($this->diceware->generate(6));
    return User::create($data);
}

Model factories and seeders. Generate deterministic-ish test data by calling the generator in a factory state, or use a fixed word list in tests so assertions are stable.

Admin / service-account provisioning. Combine the generated passphrase with a forced reset on first login. This is where diceware shines: the passphrase can be emailed or read over the phone without being a security liability, and you keep the "human transferable" property that random base64 strings lose.

Custom word lists. Publish or override the word list in config to use a language-specific list, a shorter list (more entropy per word but shorter words), or a domain-specific vocabulary. Keep the list large enough — 7,776 words (the classic diceware list) gives ~12.9 bits per word.

Validation / policy integration. Wrap generation in a small PassphraseService if you need to enforce a minimum word count across the app, and reuse it in a custom Laravel validation rule when you want to verify a user-entered passphrase meets your entropy bar.

Chaining with Laravel's own APIs. If you only need random strings, Str::password() is fine; reach for diceware specifically when memorability matters (credentials a human will type, quote, or dictate).

Gotchas and Tips

• Config caching. Run php artisan config:cache after changing word count or separator in production. Forgetting this is the most common "why is it still 5 words?" bug.
• Entropy maths. Word count dominates security. Four words ≈ 51 bits, six ≈ 77 bits, seven ≈ 90 bits. Pick based on threat model rather than copying a default; document the choice.
• Separator quirks. A hyphen or space separator is friendlier for reading aloud but may collide with password-policy rules that reject spaces. Check your validation rules and the generator's separator config together.
• Word list packaging. Verify the word list ships with the package or that you've published it; a missing/misconfigured path can silently fall back or throw at generation time.
• Laravel 10 dependency constraints. v2.1.0 widens framework support to Laravel 10. If you're upgrading a project, confirm your illuminate/* constraints and PHP version satisfy the new composer.json before bumping — run composer why-not martbock/laravel-diceware 2.1.0 if in doubt.
• Testing. Don't assert on exact generated words; assert on word count and separator shape, or bind a fake generator. If the package exposes a seedable RNG, use it — otherwise treat output as non-deterministic.
• Don't store the plaintext. Log/email the passphrase once, force rotation on first login, and never persist it unhashed. The generator is only as safe as the handling around it.
• Extension points. If the package doesn't cover a requirement (custom entropy source, different separator logic), subclass or decorate the generator service and rebind it in a service provider rather than forking.
• Laravel version support is the only change in v2.1.0 — no new API, no deprecations. Existing v2.0.0 usage is unaffected; the bump is purely an upgrade-path win for Laravel 10 users.