README

Sneeze

Sneeze is a modern, token-based authentication starter kit for Laravel using Sanctum. Inspired by Breeze, it's designed for API-first apps that need clean, flexible auth, with no frontend assumptions and no reliance on cookies or CSRF.

Use it with any frontend: mobile, SPA, desktop, TUI. If it can send headers, it works.

💡 Why Laravel Sneeze?

Breeze is great for traditional Laravel apps, but it's tightly coupled to session cookies, CSRF protection, and frontend-specific flows like email verification links.

Sneeze takes a different approach:

Clients only need to POST data. No clickable links or cookie handling required.
No CSRF middleware, no session storage, no need to hit the /csrf-token endpoint.
Auth uses Bearer tokens, not cookies, so your frontend can be on the same domain or any other.

You're not locked into a browser SPA. Whether you're building a mobile app, CLI, TUI, or remote dashboard, Sneeze is designed to get out of your way and let you build.

🔥 Features

🧪 API-first authentication using Laravel Sanctum
🔁 Register/Login issues a Sanctum token
🔐 8-digit verification codes for:
- Email verification
- Password resets
🧼 No CSRF. No session cookies. Just clean Bearer token auth
🧽 Automatic cleanup of expired or used verification codes
🧱 All key files (routes, controllers, traits, notifications) copied into your app so you can customize freely
✅ Implements Laravel’s CanResetPassword and MustVerifyEmail interfaces
🧪 Tested with both PHPUnit and Pest

🚀 Installation

Laravel Sneeze is intended for new Laravel projects.
It scaffolds routes, controllers, traits, notifications, and test files directly into your app.

Install the package via Composer:

composer require boilingsoup/sneeze

Then run the install command:

php artisan sneeze:install         # Installs with PHPUnit tests
php artisan sneeze:install --pest  # Installs with Pest tests

The sneeze:install command will:

Copy controllers, routes, notifications, traits, etc. into your app/ and routes/ directories
Publish config/sneeze.php with all settings

🧬 Authentication Flow

All actions are done via API. No frontend coupling, no session redirects, no need for custom URLs.

Action	Endpoint	Method	Description
Register	`/api/register`	POST	Create a new user
Login	`/api/login`	POST	Returns Sanctum token
Logout	`/api/logout`	POST	Revokes token
Request password reset	`/api/forgot-password`	POST	Sends 8-digit code
Reset password	`/api/reset-password`	POST	Verifies code + sets new password
Request email verification code	`/api/email/verification-notification`	POST	Sends 8-digit code
Verify email	`/api/verify-email`	POST	Verifies 8-digit code

⚙️ Configuration

Sneeze uses a simple config file to define expiration times for tokens and codes. These are set using CarbonInterval, which gives you expressive, readable control over durations.

File: config/sneeze.php

use Carbon\CarbonInterval;

return [

    // Set how long Sanctum auth tokens are valid after login or registration
    'sanctum_auth_token_expiration' => CarbonInterval::months(1),

    // Set how long email verification codes are valid
    'email_verification_expiration' => CarbonInterval::minutes(15),

    // Set how long password reset codes are valid
    'password_reset_expiration' => CarbonInterval::minutes(15),

];

You can customize these values using any CarbonInterval expression.

Example: To make reset codes expire in 30 minutes, change:

'password_reset_expiration' => CarbonInterval::minutes(30),

CarbonInterval supports durations like minutes(), hours(), days(), weeks(), months(), and more. These intervals are applied at the time the token or code is created, ensuring consistent and timezone-aware expiration.

⏱ Scheduled Tasks

Sneeze registers two scheduled tasks in routes/console.php to keep your auth tables clean:

// Prune expired Sanctum tokens (every minute)
Schedule::command('sanctum:prune-expired --hours=0')->everyMinute();

// Prune used or expired verification codes (every minute)
Schedule::command('sneeze:prune-stale')->everyMinute();

These tasks are added automatically when you install Sneeze.

In development, you can run: php artisan schedule:work
In production, set up a cron job to run php artisan schedule:run every minute

More info: Laravel Scheduler Documentation

🔐 Security Notes

Verification codes are generated using random_int(10000000, 99999999) — cryptographically secure.
Codes are hashed before being stored in the database (like passwords.)
Verification codes can only be used once.
Expired or used codes are automatically cleaned up via scheduled task.
Auth token expiration is enforced via Laravel Sanctum.
No CSRF is needed. All clients authenticate via Bearer token header.

🧱 Customization

All important logic is published into your app for easy modification:

app/Http/Controllers/Auth/...
app/Models/Traits/HasVerificationCodes.php
app/Notifications/Auth/...

📦 Credits

Created by Boiling Soup

Inspired by Laravel Breeze

boilingsoup / sneeze

Maintainers

Details