Download the PHP package mindtwo/laravel-platform-manager without Composer

Laravel Platform Manager

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

Publish config

This publishes config/platform.php.

Publish and run migrations

Configuration

Middleware

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

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.

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.

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

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

Checking scopes in application code

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

Token model helpers

Expiry

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

Session-based resolution

Temporary platform context (use())

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

Queue jobs

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

Extending the Platform model

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

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.

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.

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.

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

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

Point the config at your class:

Reading settings

Writing settings

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:

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.

Request-aware resolvers

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

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

Value-based finders

Collection queries

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().

InteractsWithPlatform trait

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

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.

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.

Key mapping:

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:

Step 4 — Auth tokens table migration

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

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

Step 5 — Replace PlatformResolver with platform()

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

Step 6 — Replace middleware

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

Multiple strategies can be chained:

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:

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):

For existing tables, create a new migration:

Code — replace all AuthTokenTypeEnum references:

2. Header names config

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

3. Middleware resolver names

4. Platform model scopes

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:

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 [email protected] instead of using the issue tracker.

Credits

• mindtwo GmbH
• All Contributors

License

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