Token Bundle Laravel Package

Getting Started

First, calibrate expectations: despite the Laravel framing, vouchedfor/token-bundle is a Symfony bundle — the -bundle suffix and *Bundle.php class are the tell. There is no Laravel service provider, no facade, no package auto-discovery. In a Laravel app you will not composer require your way to working tokens; you will either (a) port the token lifecycle into a Laravel-native service, or (b) if you also run a Symfony application, install it there and call it behind an interface.

Read the repository in this order:

1. composer.json — PHP and symfony/* constraints. This one file decides whether the code is installable on your stack at all. With one star and zero dependents, expect constraints pinned to an era of Symfony (2.x/3.x) that modern PHP 8.2+ will reject.
2. DependencyInjection/*Extension.php — the getAlias() return value is your real config root key, and load() shows which services actually exist. This is the map of the package.
3. The token generator/validator services — the only part with transferable value. Everything else is Symfony container glue you will discard.

Pick the smallest possible first use case: issue a token, store it, validate it once, expire it. Email verification or password reset. Do not start with API authentication — the bundle almost certainly does not do request-level auth for you anyway.

Implementation Patterns

If you are porting to Laravel (the realistic path):

• Behind an interface. Define TokenIssuer / TokenValidator and bind an implementation in a service provider. Call sites then never depend on the ported code, so swapping in Sanctum or a hand-rolled implementation later is a one-line change.
• Schema first. A tokens table with tokenable_id, tokenable_type, token_hash, purpose, expires_at, consumed_at. Store the hash, never the plaintext; return plaintext to the caller exactly once, at creation.
• Generation and comparison. bin2hex(random_bytes(32)) for the token, hash_equals($storedHash, hash('sha256', $presented)) for validation. Constant time, no early-exit comparison.
• Issue from intent-named methods, not controllers. A sendEmailVerification() or beginPasswordReset() on the model (or an observer) reads far better than TokenManager::create($user, 'reset') scattered through HTTP handlers.
• Revoke as part of issuing. One active token per (tokenable, purpose). A unique constraint on that tuple plus updateOrCreate eliminates a whole class of "which link is valid" confusion.
• Lifecycle hooks. A scheduled ->daily() prune of expired rows, and a TokenConsumed event for rate limiting or analytics.

If you genuinely have a Symfony app and can install it: register in config/bundles.php, add a YAML block under the extension alias, inject the token service into your controller or authenticator. Standard Symfony idioms apply — a service alias or compiler pass swaps the generator without editing vendor code.

Integration tip: push issuance into queued jobs or event listeners so the HTTP request does not block on token writes, and so a failed mail send does not leave an orphaned row.

Gotchas and Tips

• The framework mismatch is the headline gotcha. Every README and example you find will assume Symfony's container. Translating $container->get(...) idioms into Laravel's is manual work — budget for it up front.
• Installation may simply fail. Old Symfony component constraints against PHP 8.x produce unresolvable dependency graphs. Run composer require vouchedfor/token-bundle --dry-run before planning around it. If it fails, copy the two or three relevant classes into app/Support rather than fighting Composer.
• Audit the entropy source before trusting anything. Look for rand(), mt_rand(), uniqid(), or md5(time()). Any of these means generation is not cryptographically sound and must be replaced wholesale. In a 1-star, 0-dependent package this is the most likely defect.
• Verify expiry and single-use enforcement explicitly. Small token bundles frequently issue tokens but leave invalidation to the caller. If consumed_at-style logic is absent, add it yourself — do not assume the bundle handles replay.
• Config root key ≠ bundle name. Symfony derives it from getAlias(), often the short form (token), not vouched_for_token. If your YAML config is silently ignored, that is why.
• No community safety net. Zero dependents means no Stack Overflow answers, no issue triage, no security advisories surfaced to you. Pin the commit hash if you vendor it, and re-read the code on every PHP major upgrade.
• MIT is your escape hatch. Forking, stripping the Symfony glue, and keeping only the token logic is usually the correct move and takes an afternoon. Add a NOTICE file for attribution.
• Debugging. In Symfony, debug:container --tag=... plus the profiler's service panel show what is actually registered. In a port, log the token id and hash (never the plaintext) at issue/validate/prune so lifecycle bugs are visible.
• The extension point that matters: the generator is almost always a single injectable service. Replace it with your own implementation bound to the same interface — services.yaml alias in Symfony, $this->app->bind() in Laravel — rather than editing vendor code.