Security Token Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config/security-token.php. Before you invest time, accept the reality: if your app is Laravel, you are either (a) running this inside a Symfony sidecar/service, (b) manually instantiating the bundle's core services outside the Symfony kernel, or (c) reading it as a reference implementation and rebuilding the same pattern with Laravel primitives. Do not expect composer require to "just work."

Minimal steps to evaluate it:

composer require yokai/security-token-bundle

Then look, in this order:

1. README.md — the only reliable source of truth for this package. With 7 stars and 0 dependents, docs and tests are your contract; treat everything else as implementation detail.
2. The bundle's DI extension / Configuration.php — this tells you the actual config tree (token types, storage, TTLs). This is what you need to translate into a Laravel config file if you go the manual route.
3. The token manager/generator services — the public API you will actually call: generate a token for a purpose, persist it, validate/consume it, revoke it.
4. The storage layer — usually a Doctrine ORM/ODM repository. This is the biggest coupling point. In Laravel you will be swapping this for Eloquent or a cache/DB table.

First use case to target: password reset / email confirmation tokens. It is the canonical reason this bundle exists, it exercises generation → storage → expiry → single-use consumption, and it is small enough to validate whether the package is worth adapting.

If you are staying in Laravel, the pragmatic first move is a thin wrapper service:

// app/Services/SecurityTokenService.php
// Wrap whatever the bundle exposes so the rest of your app
// never touches Symfony-specific classes directly.

If you are evaluating for a Symfony app that happens to have a Laravel developer maintaining it, start by registering the bundle in config/bundles.php and defining one token configuration before writing any application code.

Implementation Patterns

One token configuration per purpose. Model email verification, password reset, invitation, and API tokens as separate token "types" with their own TTL and usage policy. Do not reuse a single generic token table/key with a type column you filter by hand — the bundle's configuration model is built around per-purpose definitions, and matching that in Laravel will save you bugs.

Generate → deliver → consume is a three-step lifecycle. Keep them separate:

$token = $this->tokens->generate('password_reset', $user); // returns plaintext once
Mail::to($user)->send(new PasswordResetMail($token));      // deliver
// later...
$this->tokens->consume('password_reset', $request->token); // validates + invalidates

Never store the plaintext token. The bundle's design assumes the persisted value is a hash or an opaque identifier; the plaintext leaves the system exactly once.

Single-use semantics belong in a transaction. When you consume a token, the check-then-delete must be atomic (DB transaction or SELECT ... FOR UPDATE equivalent), otherwise two concurrent requests can both pass validation. If the bundle's consumer does not do this for you, wrap it.

Laravel integration pattern — bind, don't scatter. If you manually wire the bundle's services, do it once in a service provider and inject an interface everywhere else:

$this->app->singleton(TokenManagerInterface::class, function ($app) {
    return new TokenManager(/* bundle's generator + your Eloquent storage */);
});

Scheduler integration. Tokens expire; expired rows accumulate. The Symfony bundle expects a console command or cron to purge them. In Laravel, mirror this with a scheduled command ($schedule->command('tokens:purge')->daily()). Do not rely on lazy deletion during lookup — you will still accumulate garbage.

Storage adapter strategy. The package's storage is the seam to exploit. Implement the bundle's storage interface (or your own) against Eloquent, Redis, or the database cache driver depending on the token class: password resets can live in Redis with TTL; audit-relevant tokens (invitations) belong in a table with timestamps and used_at/revoked_at columns.

Revocation as a first-class operation. Build revoke($user, $purpose) into your wrapper from day one. "Invalidate all outstanding password-reset tokens when the password changes" is a requirement you will hit within a month.

Gotchas and Tips

• Symfony bundle registration will fail outside a Symfony kernel. Yokai\SecurityTokenBundle extends Bundle; Laravel's container knows nothing about config/bundles.php, Extension, or compiler passes. You must instantiate services manually. Budget for this — it is the single biggest cost of adoption.
• Doctrine coupling is likely. Most bundles of this shape ship an ORM/ODM token entity. If you are not on Doctrine, you are replacing the persistence layer, not configuring it. Read the storage interface before you commit.
• Config keys are not documented as Laravel config. The bundle's Configuration tree uses Symfony's TreeBuilder. Map each node to a config/security_tokens.php entry yourself; the names will not match Laravel conventions (snake_case scalars under a vendor-prefixed root).
• Timing-safe comparison. If you implement validation yourself against the stored hash, use hash_equals. The bundle should do this, but verify — do not assume.
• Expiry is not a security boundary by itself. An expired token must also be rejected, not merely ignored; and a consumed token must be deleted or marked, not left valid. Test both paths explicitly.
• Clock and timezone. TTLs computed with DateTime/DateTimeImmutable versus stored UTC timestamps are a classic source of "token expires 2 hours early/late." Normalize to UTC at the boundary.
• Maintenance risk. 7 stars, 0 dependents, and a single maintainer mean no ecosystem safety net. Pin the version in composer.json, read the changelog on every bump, and keep your wrapper thin so a swap is cheap.
• Extension points worth knowing. The storage/repository interface, the token generator, and any event dispatcher hooks are the three places you can customize without forking. If a need does not fit one of those, fork deliberately rather than monkey-patching.
• Debugging tip. When a token "doesn't work," check in this order: was the plaintext hashed before storage, is the lookup scoped to the correct purpose, has TTL already elapsed, and was the row already consumed. Nine out of ten failures are one of those four.
• License is MIT, so vendoring or adapting the core logic into a Laravel-native package is legally clean and often the sanest outcome given the integration cost.