Download the PHP package ecourty/token-bundle without Composer

Token Bundle

A Symfony bundle for managing secure, typed, and revocable tokens attached to any entity — for password resets, email verification, share links, and more.

Table of Contents

• Requirements
• Installation
• Core Features
• Configuration
• Usage
  • Making an Entity a Token Subject
  • Creating a Token
  • Retrieving a Token
  • Consuming a Token
  • Revoking Tokens
  • Finding a Valid Token
  • Resolving the Subject Entity
  • Protecting Controller Routes
• Events
• Exceptions
• Console Command
• Development

Requirements

• PHP ≥ 8.3
• Symfony ≥ 7.0
• Doctrine ORM ≥ 3.0

Installation

Register the bundle in config/bundles.php (if not using Symfony Flex):

Create the tokens table with a Doctrine migration:

The bundle automatically registers its Doctrine entity mapping — no manual configuration required.

Core Features

• Typed tokens — each token has a type (e.g. password_reset, email_verify, share)
• Any entity as subject — attach a token to any Doctrine entity via TokenSubjectInterface
• Expiration — every token requires an expiry date (no permanent tokens)
• Single-use — tokens can be flagged as single-use, automatically consumed after first use
• Max-uses — tokens can be limited to N uses, auto-consumed when the limit is reached
• JSON payload — attach arbitrary data to any token
• Revocation — revoke individual tokens or all tokens for a subject (optionally filtered by type)
• Event-driven — hook into TokenCreatedEvent, TokenConsumedEvent, TokenRevokedEvent
• Purge command — token:purge to clean up expired, consumed, and revoked tokens
• Race-safe — atomic increment for multi-use tokens prevents overconsumption

Configuration

Usage

Making an Entity a Token Subject

Any Doctrine entity can become a token subject by implementing TokenSubjectInterface:

Creating a Token

Inject TokenManager and call create():

With payload and max-uses:

Retrieving a Token

Use get() to look up a token by its string value and validate it without consuming it. This is useful to check if a token is valid before showing a form or performing an action:

get() throws the same exceptions as consume() if the token is invalid.

Consuming a Token

consume() accepts either a token string (with its type) or a Token entity directly:

Both paths validate the token before consuming it and throw the same exceptions:

Tip: All token exceptions extend AbstractTokenException (a RuntimeException), so you can catch them all at once if needed.

Revoking Tokens

Finding a Valid Token

Returns the first valid (not expired, not consumed, not revoked, not at max uses) token for the given subject and type:

Resolving the Subject Entity

After consuming or finding a token, retrieve the original subject entity directly:

Protecting Controller Routes

Use the #[RequiresToken] attribute to protect a controller action with a token check. The listener validates the token before the controller executes:

By default, the token is read from the X-Token HTTP header via the built-in HeaderTokenResolver.

The attribute accepts two parameters:

Built-in resolvers:

Custom resolver:

Implement TokenResolverInterface to extract the token from anywhere in the request (cookies, custom headers, etc.):

Resolver classes are automatically tagged and discovered when they implement TokenResolverInterface.

Handling access denied:

When a token is missing, invalid, expired, or revoked, a TokenAccessDeniedException is thrown. You can handle it globally by listening to the TokenAccessDeniedEvent:

The event provides $event->request, $event->exception (the underlying token exception), and $event->tokenType. Setting a response on the event prevents the exception from propagating.

Events

The bundle dispatches Symfony events on token lifecycle actions:

Note: revokeAll() performs a bulk SQL UPDATE for performance and does not dispatch individual TokenRevokedEvent per token.

All events carry the Token entity via $event->token.

Example listener:

Exceptions

All exceptions extend AbstractTokenException (RuntimeException):

Console Command

Development

License

This bundle is released under the MIT License.