Getting Started

Requirements

Suspend requires PHP 8.4+ and Laravel 11+.

Installation

Install Suspend with composer:

composer require cline/suspend

Run Migrations

First publish the migrations:

php artisan vendor:publish --tag="suspend-migrations"

Then run the migrations:

php artisan migrate

Add the Trait (Optional)

For eager loading suspensions, add the trait to your models:

use Cline\Suspend\Concerns\HasSuspensions;

class User extends Model
{
    use HasSuspensions;
}

This provides the suspensions relationship for eager loading:

$users = User::with('suspensions')->get();

Using the Facade

Import the facade in your files:

use Cline\Suspend\Facades\Suspend;

Quick Start

Entity-Based Suspensions

Suspend specific users, accounts, or any Eloquent model:

// Suspend a user
Suspend::for($user)->suspend('Terms of Service violation');

// Suspend with expiration
Suspend::for($user)->suspend('Temporary ban', now()->addDays(7));

// Check if suspended
if (Suspend::for($user)->isSuspended()) {
    // Handle suspended user
}

// Lift all suspensions
Suspend::for($user)->lift();

Context-Based Suspensions

Suspend by email, IP address, phone number, or any pattern:

// Block an email domain
Suspend::match('email', '*@spam.com')->suspend('Spam domain');

// Block an IP range
Suspend::match('ip', '192.168.1.0/24')->suspend('Network abuse');

// Block a phone number pattern
Suspend::match('phone', '+1555*')->suspend('Fraud prevention');

Checking Multiple Contexts

Check if any context matches active suspensions:

$isSuspended = Suspend::check()
    ->email($request->input('email'))
    ->ip($request->ip())
    ->phone($request->input('phone'))
    ->matches();

if ($isSuspended) {
    abort(403, 'Access denied');
}

Middleware

Suspend registers a middleware alias automatically. Use it to protect routes:

// In routes/web.php
Route::middleware(['auth', 'suspended'])->group(function () {
    Route::get('/dashboard', DashboardController::class);
});

The middleware checks if the authenticated user is suspended and returns a 403 response if so.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="suspend-config"

This creates config/suspend.php where you can customize:

• Primary key type (id, uuid, ulid)
• IP resolution strategy
• Geo-location resolver
• Custom table names
• Middleware behavior

Next Steps

• Entity Suspensions - Deep dive into model-based suspensions
• Context Matching - Pattern-based suspension with matchers
• Strategies - Conditional suspension strategies
• Middleware - Protecting routes and handling suspended users
• Events - Reacting to suspension lifecycle events
• Querying - Finding and filtering suspensions
• Configuration - Full configuration reference