Download the PHP package foxen/laravel-cancellation-tokens without Composer

Laravel Cancellation Tokens

A focused Laravel package that manages the full cancellation token lifecycle — generation, storage, verification, expiry, and consumption — so you never hand-roll this system again.

Provides cryptographically secure, single-use, time-limited tokens for cancellable workflows (bookings, orders, subscriptions) without requiring login. The plain-text token is returned once for embedding in a URL; only an HMAC-SHA256 hash is ever stored.

Installation

Publish the migration and config:

Add a hash key to your .env file. This key is used for HMAC-SHA256 token hashing and must be set before creating or verifying tokens:

Important: Generate a strong, random value. You can use php -r "echo base64_encode(random_bytes(32));" to generate one. This key is separate from APP_KEY and should not be shared with it.

Configuration

The published config file at config/cancellation-tokens.php:

Basic Usage

A complete booking cancellation flow using the HasCancellationTokens trait.

1. Add the trait to your cancellable model

2. Create a token and send it

When a booking is confirmed, generate a cancellation token and include it in the confirmation email:

The token is prefixed automatically (e.g. ct_a1B2c3..., 67 characters). Only the HMAC-SHA256 hash is stored in the database — the plain-text value is returned exactly once.

Note: Creating a new token for the same booking/user pair automatically removes any previous unused tokens for that pair.

3. Handle the cancellation request

consume() verifies the token and marks it as used in a single call (used_at is set). You can also call verify() to check a token without consuming it:

4. Validate tokens in form requests

For cancellation via form submission, use the ValidCancellationToken validation rule:

If validation fails, the rule stores the failure reason on itself. You can access it after validation to customise your response:

Using the Facade

When you don't want to add the trait to a model — or you need to create tokens across arbitrary model types — use the Facade directly:

The create() method accepts three arguments:

• $cancellable — the model being cancelled (e.g. Booking, Subscription, Order)
• $tokenable — the actor who may cancel (e.g. User, Customer, any model)
• $expiresAt (optional) — a Carbon instance; defaults to the configured default_expiry

Both $cancellable and $tokenable must be persisted models (they must exist in the database).

Events

The package dispatches events at key points in the token lifecycle. All events carry the CancellationToken model as a public $token property.

On failure paths (TokenExpired), the event fires before the TokenVerificationException is thrown, so your listeners always run.

Listening for events

Token Cleanup

The CancellationToken model implements Laravel's Prunable trait. Tokens are automatically pruned when they are:

• Expired — expires_at is in the past
• Consumed — used_at is not null

Schedule the prune command in your routes/console.php (or app/Console/Kernel.php for older Laravel versions):

Or prune all prunable models together:

No custom Artisan commands are needed — the package integrates with Laravel's built-in pruning system.

Testing

Unit tests with CancellationTokenFake

The fake bypasses the database entirely, making your unit tests fast:

The CancellationTokenFake also enforces token lifecycle rules — calling consume() twice on the same token throws TokenVerificationException, just like the real service.

Feature tests with CancellationTokenFactory

For tests that need real database records, use the included factory:

Note that the factory creates database records with hashed token values — the plain-text token is not available. This is by design: the factory is for setting up test state, not for simulating the full create-verify-consume lifecycle (use the service directly for that).

Security

This package follows the same token storage approach Laravel uses for password reset tokens:

• HMAC-SHA256 hashing — tokens are hashed with a dedicated hash_key before storage
• Plain-text never persisted — the raw token is returned from create() exactly once and never stored, logged, or cached
• Timing-safe comparison — hash_equals() is used for all hash comparisons
• 64 bytes of entropy — Str::random(64) backed by random_bytes()
• Single-use enforcement — used_at timestamp prevents replay
• Automatic invalidation — creating a new token for the same pair removes previous unused tokens

Credits

• mrdth
• All Contributors

License

The MIT License (MIT). Please see License File for more information.