README

Resolve a "platform" (tenant, site, or API client) on every request — by hostname, token, context string, or session — and make it available everywhere via platform().

Installation

composer require mindtwo/laravel-platform-manager

Publish config

php artisan vendor:publish --provider="mindtwo\LaravelPlatformManager\LaravelPlatformManagerProvider" --tag=config

This publishes config/platform.php.

Publish and run migrations

php artisan vendor:publish --provider="mindtwo\LaravelPlatformManager\LaravelPlatformManagerProvider" --tag=migrations
php artisan migrate

Configuration

// config/platform.php

return [
    // Eloquent model used as the platform. Swap this for your own model that extends Platform.
    'model' => \mindtwo\LaravelPlatformManager\Models\Platform::class,

    // HTTP headers used for M2M token auth.
    'header_names' => [
        'token' => 'X-Platform-Token',

        // Legacy header accepted during a grace period. Set to null to disable.
        'token_legacy' => 'X-Context-Platform-Public-Auth-Token',
    ],

    // Session key used by the session resolver.
    'session_key' => 'platform_id',
];

Middleware

Register the middleware alias in your application's middleware stack or use it inline on routes:

// routes/api.php
Route::middleware('resolve-platform:token')->group(function () {
    // platform() is available here
});

The resolve-platform alias is registered automatically by the service provider.

Resolver strategies

Pass one or more strategies separated by |. The first one that returns a match wins.

// Try token first, fall back to hostname
Route::middleware('resolve-platform:token|host')->group(function () { ... });

If no strategy resolves a platform the middleware aborts with a 404.

The platform() helper

The global platform() function returns the singleton Platform context object.

// Check whether a platform has been resolved
platform()->isResolved(); // bool

// Get the underlying Eloquent model
platform()->get(); // ?PlatformModel

// Read any model attribute directly
platform()->hostname;
platform()->uuid;

// Read platform settings (dot notation)
platform()->setting('mail.from');
platform()->setting('billing.plan', 'free');

// Which resolver matched
platform()->resolver(); // 'token' | 'host' | 'context' | 'session' | ...

Scopes

Scopes control what operations a resolved platform is allowed to perform. There are two layers:

1. Platform baseline scopes — stored on the platforms row itself, always active regardless of how the platform was resolved.
2. Token scopes — carried by an auth_tokens record, merged on top of the baseline when the platform is resolved via the token strategy.

The effective scope set is platform.scopes ∪ token.scopes.

Platform baseline scopes

$platform->update(['scopes' => ['read']]);

These scopes apply for every resolver (host, session, context, token).

M2M token auth & scopes

Auth tokens are M2M (machine-to-machine) credentials stored in the auth_tokens table. Token scopes widen the platform's baseline — they cannot narrow it.

Creating a token

$platform->authTokens()->create([
    'scopes' => ['read', 'write'],
]);

Checking scopes in application code

platform()->can() returns true when the scope is present in the effective set (platform baseline + token scopes).

// In a controller, middleware, policy, etc.
if (! platform()->can('write')) {
    abort(403);
}

Token model helpers

$token->hasScope('admin');           // bool
$token->scopes;                      // array<string>
$token->isExpired();                 // bool

AuthToken::withScope('read')->get(); // query scope

Expiry

Set expired_at to limit a token's lifetime. Expired tokens are ignored by the middleware resolver automatically.

$platform->authTokens()->create([
    'scopes'     => ['read'],
    'expired_at' => now()->addDays(30),
]);

Session-based resolution

// Store the current platform in the session (e.g. after an admin selects a platform)
platform()->saveToSession($platformModel);

// Or if it's already set:
platform()->set($model, 'admin');
platform()->saveToSession();

// Clear on logout / platform switch
platform()->clearFromSession();

Temporary platform context (use())

Switch platform for the duration of a callback, then restore the previous context automatically — even if the callback throws.

platform()->use($otherPlatform, function () {
    // platform() resolves $otherPlatform here
    Mail::send(...);
});

// platform() is restored here

Queue jobs

Use the HasPlatformContext trait to capture and restore platform context across queue boundaries.

use mindtwo\LaravelPlatformManager\Jobs\Concerns\HasPlatformContext;

class ProcessOrder implements ShouldQueue
{
    use HasPlatformContext;

    public function __construct(private Order $order)
    {
        $this->capturePlatformContext(); // call at end of constructor
    }

    public function handle(): void
    {
        $this->restorePlatformContext(); // call at start of handle
        // platform() is now resolved
    }
}

Extending the Platform model

Publish the config and point platform.model at your own model:

// app/Models/Platform.php
use mindtwo\LaravelPlatformManager\Models\Platform as BasePlatform;

class Platform extends BasePlatform
{
    // add columns, relationships, scopes ...
}

// config/platform.php
'model' => \App\Models\Platform::class,

BelongsToPlatform trait

Add the trait to any Eloquent model that belongs to a platform. It auto-fills platform_id on create and provides two query scopes.

use mindtwo\LaravelPlatformManager\Traits\BelongsToPlatform;

class Article extends Model
{
    use BelongsToPlatform;
}

// Scopes
Article::forCurrentPlatform()->get();
Article::forPlatform($platform)->get();
Article::forPlatform(42)->get();

Scope middleware

The platform-scope middleware aborts with 403 if the resolved platform does not hold the required scope(s). Apply it after resolve-platform.

Route::middleware(['resolve-platform:token', 'platform-scope:write'])->group(function () {
    // platform must have the 'write' scope
});

// Multiple scopes — all must be present
Route::middleware(['resolve-platform:token', 'platform-scope:read,write'])->group(function () {
    // ...
});

BelongsToManyPlatforms trait

For models that belong to multiple platforms via a pivot table. Provides the same scopes as BelongsToPlatform but uses whereHas under the hood.

use mindtwo\LaravelPlatformManager\Traits\BelongsToManyPlatforms;

class Article extends Model
{
    use BelongsToManyPlatforms;
}

// Scopes
Article::forCurrentPlatform()->get();
Article::forPlatform($platform)->get();
Article::forPlatform(42)->get();

// Relationship
$article->platforms; // Collection of Platform models

The pivot table is derived automatically as platform_{models} (e.g. platform_articles). Override getPlatformPivotTable() on the model to use a different name:

public function getPlatformPivotTable(): string
{
    return 'article_platform';
}

Typed platform settings

Platform settings are stored as JSON in the settings column and hydrated into a PlatformSettings DTO. Declare known properties as typed public fields and list any that should be encrypted at rest in $encrypted.

Extending PlatformSettings

// app/Settings/PlatformSettings.php
use mindtwo\LaravelPlatformManager\Settings\PlatformSettings as BaseSettings;

class PlatformSettings extends BaseSettings
{
    protected array $encrypted = ['apiSecret', 'smtpPassword'];

    public ?string $appName = null;
    public ?string $apiSecret = null;   // encrypted at rest
    public ?string $smtpPassword = null; // encrypted at rest
    public ?string $billingPlan = null;
}

Point the config at your class:

// config/platform.php
'settings' => \App\Settings\PlatformSettings::class,

Reading settings

// Via the helper (dot notation, works for any depth)
platform()->setting('appName');
platform()->setting('mail.host', 'localhost'); // nested via overflow

// Via the model directly
$platform->settings->appName;
$platform->setting('appName');

Writing settings

// Assign properties directly
$platform->settings->appName = 'My App';
$platform->settings->apiSecret = 's3cr3t'; // stored encrypted
$platform->save();

// Or replace the whole DTO
$platform->update(['settings' => ['appName' => 'My App', 'apiSecret' => 's3cr3t']]);

Unknown keys (no matching declared property) are stored transparently in an overflow bag so existing data and config overrides continue to work without any changes.

Config overrides

A platform can override arbitrary Laravel config values by storing them under settings.config:

$platform->update([
    'settings' => [
        'config' => [
            'mail.default' => 'ses',
            'app.name'     => 'My Platform',
        ],
    ],
]);

These overrides are applied automatically whenever the platform is resolved.

PlatformRepository

All platform lookups go through PlatformRepository, which extends chiiya/laravel-utilities's AbstractRepository. The middleware resolves it automatically, but you can also inject it directly.

use mindtwo\LaravelPlatformManager\Repositories\PlatformRepository;

class PlatformController extends Controller
{
    public function __construct(protected PlatformRepository $platforms) {}
}

Request-aware resolvers

These map directly to the middleware strategies and read from the incoming request:

$repository->resolveByToken($request);    // ?array{PlatformModel, array<string>}
$repository->resolveByHostname($request); // ?PlatformModel
$repository->resolveByContext($request);  // ?PlatformModel
$repository->resolveBySession($request);  // ?PlatformModel

resolveByToken returns a tuple of [PlatformModel, effectiveScopes] where scopes are the platform baseline merged with the token's scopes.

Value-based finders

$repository->findByHostname('example.com'); // ?PlatformModel
$repository->findByContext('my-context');   // ?PlatformModel
$repository->findByUuid('uuid-string');     // ?PlatformModel
$repository->findActiveById(1);            // ?PlatformModel

// Returns [PlatformModel, effectiveScopes]|null
$repository->findByTokenWithScopes($rawToken);

Collection queries

$repository->allActive();                     // Collection<PlatformModel>
$repository->index(['is_active' => true]);    // Collection<PlatformModel>
$repository->index(['hostname' => 'app.io']); // Collection<PlatformModel>
$repository->count(['is_active' => true]);    // int
$repository->search('app', ['is_active' => true]); // LengthAwarePaginator

Supported applyFilters parameters: is_active, hostname, context.

Testing

PlatformFake

Set a fake platform on the singleton without hitting the database. Useful in any test that exercises code which calls platform().

use mindtwo\LaravelPlatformManager\Testing\PlatformFake;

PlatformFake::make(['hostname' => 'test.com']);

// With resolver and scopes
PlatformFake::make(['hostname' => 'test.com'], resolver: 'token', scopes: ['read', 'write']);

// Reset back to unresolved
PlatformFake::reset();

InteractsWithPlatform trait

Add to your test case for a cleaner API and automatic teardown helpers:

use mindtwo\LaravelPlatformManager\Testing\InteractsWithPlatform;

class MyTest extends TestCase
{
    use InteractsWithPlatform;

    protected function tearDown(): void
    {
        $this->clearPlatform();
        parent::tearDown();
    }

    public function test_something(): void
    {
        $this->setPlatform(['hostname' => 'test.com'], scopes: ['read']);

        $this->assertPlatformResolved();
        $this->assertPlatformCan('read');
        $this->assertPlatformCannot('write');
        $this->assertPlatformResolver('fake');
    }
}

Upgrade Guide

Upgrading from v2 to v4

v4 is a full rewrite. Every section below is a breaking change — work through them in order.

Step 1 — Service provider

The provider moved out of the Providers sub-namespace.

// Before (config/app.php or auto-discovery override)
mindtwo\LaravelPlatformManager\Providers\LaravelPlatformManagerProvider::class

// After
mindtwo\LaravelPlatformManager\LaravelPlatformManagerProvider::class

Step 2 — Config file rename and restructure

The config file was renamed from platform-resolver.php to platform.php, and the config key changed from platform-resolver to platform.

# Republish the config
php artisan vendor:publish --provider="mindtwo\LaravelPlatformManager\LaravelPlatformManagerProvider" --tag=config

Key mapping:

// Before (config/platform-resolver.php)
'model'       => Platform::class,
'headerNames' => [
    AuthTokenTypeEnum::Public()  => 'X-Context-Platform-Public-Auth-Token',
    AuthTokenTypeEnum::Secret()  => 'X-Context-Platform-Secret-Auth-Token',
],
'webhooks'    => [ ... ],

// After (config/platform.php)
'model'        => Platform::class,
'header_names' => [
    'token' => 'X-Platform-Token',
],
'session_key'  => 'platform_id',

Update any config('platform-resolver.*') calls in your own code to config('platform.*').

Step 3 — Platforms table migration

Several columns were removed and three were added. Create a migration in your application:

Schema::table('platforms', function (Blueprint $table) {
    // Remove v2-only columns (skip any you wish to keep in your own schema)
    $table->dropColumn([
        'owner_id',
        'is_main',
        'is_headless',
        'name',
        'default_locale',
        'available_locales',
    ]);

    // Widen hostname to 100 chars
    $table->string('hostname', 100)->nullable()->change();

    // Add new columns
    $table->string('context')->nullable()->unique()->after('additional_hostnames');
    $table->json('scopes')->nullable()->after('context');
    $table->json('settings')->nullable()->after('scopes');
});

Step 4 — Auth tokens table migration

The type column is replaced by scopes, expired_at is added, and several v2 columns are dropped:

Schema::table('auth_tokens', function (Blueprint $table) {
    // Drop v2 columns
    $table->dropForeign(['user_id']);
    $table->dropUnique(['platform_id', 'token']); // composite unique
    $table->dropColumn(['user_id', 'description']);
    $table->dropSoftDeletes();
    $table->dropColumn('type');

    // Add v4 columns
    $table->json('scopes')->default('[]')->after('platform_id');
    $table->datetime('expired_at')->nullable()->after('token');
});

Migrate existing token types to scopes before dropping type if you need to preserve access levels:

// Run before dropping 'type'
DB::table('auth_tokens')->where('type', 1)->update(['scopes' => '["read","write"]']); // Secret → full access
DB::table('auth_tokens')->where('type', 2)->update(['scopes' => '["read"]']);          // Public → read only

Step 5 — Replace PlatformResolver with platform()

The PlatformResolver service is gone. Replace all usages with the platform() helper or app(Platform::class).

// Before
app(PlatformResolver::class)->getCurrentPlatform()
resolve(PlatformResolver::class)->getCurrentPlatform()

// After
platform()->get()

// Before — auth check
app(PlatformResolver::class)->checkAuth(AuthTokenTypeEnum::Secret())

// After — scope check
platform()->can('write')

Step 6 — Replace middleware

The old middleware classes are removed. Replace them with the new resolve-platform middleware.

// Before
\mindtwo\LaravelPlatformManager\Middleware\PlatformSession::class

// After
'resolve-platform:session'

// Before — token-based routes
\mindtwo\LaravelPlatformManager\Middleware\ResolveBySecretToken::class
\mindtwo\LaravelPlatformManager\Middleware\ResolveByPublicToken::class

// After
'resolve-platform:token'

Multiple strategies can be chained:

Route::middleware('resolve-platform:token|host|session')->group(...);

Remove StatefulPlatformDomains — it is no longer part of this package.

Step 7 — Update API clients

Send the single X-Platform-Token header instead of the separate public/secret headers:

# Before
X-Context-Platform-Secret-Auth-Token: <token>
X-Context-Platform-Public-Auth-Token: <token>

# After
X-Platform-Token: <token>

Step 8 — Remove webhooks

The full webhook system (tables, jobs, routes, Nova resources) has been removed. If your application used webhooks:

• Drop the webhooks and webhook_requests tables
• Remove any references to PushToWebhook, WebhookController, WebhookConfiguration, WebhookRequest, EnsureWebhooksAreEnabled
• Remove the platform-resolver.webhooks config section (gone with step 2)

Step 9 — Nova resources

All built-in Nova resources have been removed. If you extended them, copy the field definitions into your own resource classes.

Upgrading to v4 (from v3)

v4 is a breaking release. The changes below are required.

1. Auth token type → scopes

The type column (Public/Secret) has been replaced with a scopes JSON array.

Migration — if you published the migration previously, update your create_auth_tokens_table migration (or create a new migration on existing tables):

// Before
$table->smallInteger('type');

// After
$table->json('scopes')->default('[]');

For existing tables, create a new migration:

Schema::table('auth_tokens', function (Blueprint $table) {
    $table->json('scopes')->default('[]')->after('platform_id');
    $table->dropColumn('type');
});

Code — replace all AuthTokenTypeEnum references:

// Before
$token->type = AuthTokenTypeEnum::Secret;
$token->type = AuthTokenTypeEnum::Public;

// After — just assign scopes
$token->scopes = ['read', 'write'];

2. Header names config

// Before
'header_names' => [
    'public' => 'X-Context-Platform-Public-Auth-Token',
    'secret' => 'X-Context-Platform-Secret-Auth-Token',
],

// After
'header_names' => [
    'token' => 'X-Platform-Token',
],

Update any API clients to send X-Platform-Token (or whatever you configure) instead of the old public/secret headers.

3. Middleware resolver names

// Before
Route::middleware('resolve-platform:public-token|secret-token|host')->group(...);

// After
Route::middleware('resolve-platform:token|host')->group(...);

4. Platform model scopes

// Before
Platform::query()->byPublicAuthToken($token)->first();
Platform::query()->bySecretAuthToken($token)->first();

// After — single scope, expiry checked automatically
Platform::query()->byToken($token)->first();

5. AuthTokenTypeEnum removed

Delete any imports or references to mindtwo\LaravelPlatformManager\Enums\AuthTokenTypeEnum. The enum no longer exists.

6. Nova resource removed

The built-in AuthToken Nova resource has been removed. If you extended it, update your subclass to work without the base class or reimplement the fields directly. The scopes field is a JSON array — a Tag or Text field works well.

7. New: platform()->can()

Scope authorization is now available for all resolvers, not just token:

if (platform()->can('write')) {
    // scope is in platform baseline or widened by the resolved token
}

Platform baseline scopes (platforms.scopes) apply for every resolver. Token scopes are additive on top.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email info@mindtwo.de instead of using the issue tracker.

Credits

• mindtwo GmbH
• All Contributors

License

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