README

Multi-channel application context management for Laravel (JWT + API key auth) with channel detection, context-aware rate limiting, and audit logging.

• Documentation: documentation/index.md

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x
• php-open-source-saver/jwt-auth 2.x

Installation

composer require ronu/laravel-app-context

Publish config:

php artisan vendor:publish --tag=app-context-config

Quickstart

1. Configure a channel in config/app-context.php:

'channels' => [
    'site' => [
        'subdomains' => ['www', null],
        'path_prefixes' => ['/site'],
        'auth_mode' => 'jwt_or_anonymous',
        'jwt_audience' => 'site',
        'allowed_scopes' => ['site:*', 'catalog:browse'],
        'public_scopes' => ['catalog:browse'],
        'rate_limit_profile' => 'site',
        'tenant_mode' => 'single',
        'features' => [
            'allow_anonymous' => true,
        ],
    ],
],

1. Apply the middleware group:

use Illuminate\Support\Facades\Route;
use Ronu\AppContext\Facades\AppContext;

Route::middleware(['app-context'])->group(function () {
    Route::get('/site/profile', function () {
        return response()->json([
            'channel' => AppContext::getAppId(),
            'auth_mode' => AppContext::getAuthMode(),
            'scopes' => AppContext::getScopes(),
        ]);
    });
});

Configuration

• Config lives in config/app-context.php (publish tag: app-context-config).
• Environment variable reference: documentation/02-configuration/01-env-vars.md
• Full config reference: documentation/02-configuration/00-configuration-reference.md

Common scenarios

1) Mobile app with JWT scopes

Route::middleware(['app-context', 'app.requires:mobile:orders:read'])->group(function () {
    Route::get('/mobile/orders', fn () => ['ok' => true]);
});

2) Partner API with API keys

Route::middleware(['app-context', 'app.requires:partner:orders:read'])->group(function () {
    Route::get('/partner/orders', fn () => ['ok' => true]);
});

3) Admin dashboard (subdomain detection)

Route::middleware(['app-context', 'app.scope:admin:*'])->group(function () {
    Route::get('/api/admin/metrics', fn () => ['ok' => true]);
});

More scenarios: documentation/03-usage/02-scenarios.md

Edge scenarios

Common edge cases include config caching, queue workers, burst traffic, tenant mismatches, and JWT blacklist races.

See: documentation/03-usage/03-edge-and-extreme-scenarios.md

API reference

• Public API
• Middleware
• Artisan commands

Troubleshooting

Start here: documentation/05-quality/02-troubleshooting.md

Contributing / Security

• Security
• Testing

Start here: documentation/index.md