README

RouterSoup for Laravel

Your self-hosted, free alternative to OpenRouter. Store multiple API keys per provider, rotate between them automatically, and monitor everything from a built-in dashboard.

Requires PHP 8.3+, Laravel 11+, and Laravel AI

Table of Contents

• Installation
• Usage
• Rotation Strategies
• Dashboard
• Authorization
• Pruning Old Events
• Configuration
• Development

Installation

⚡️ Get started by requiring the package using Composer:

composer require heybardi/routersoup

Then run the install command — it publishes the config, migrations, and a service provider stub:

php artisan routersoup:install
php artisan migrate

Usage

Open your AppServiceProvider and call RouterSoup::enable():

use HeyBardi\RouterSoup\RouterSoup;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        RouterSoup::enable();
    }
}

That's it. RouterSoup now intercepts all Laravel AI calls and rotates your provider keys automatically.

Head to /routersoup in your browser, add a few API keys, and you're good to go.

Rotation Strategies

RouterSoup supports two strategies for picking which API key to use:

Set it in config/routersoup.php:

use HeyBardi\RouterSoup\Enums\RouterSoupRotation;

'rotation' => RouterSoupRotation::LeastUsed,

Dashboard

Visit /routersoup (or whatever you set path to) to access the admin panel:

• Dashboard — Provider usage analytics over the last 30 days.
• Providers — Add, edit, enable/disable, and delete API keys.
• Monitoring — Browse every Laravel AI event with full payloads.
• Exceptions — Failed provider calls with error details and traces.

No frontend build step needed — it's all Livewire.

Authorization

In local environments, the dashboard is open to everyone. In production, access is controlled by a viewRouterSoup gate.

The install command publishes a RouterSoupServiceProvider where you define who gets in:

// app/Providers/RouterSoupServiceProvider.php

protected function gate(): void
{
    Gate::define('viewRouterSoup', function ($user) {
        return in_array($user->email, [
            'you@example.com',
        ]);
    });
}

Pruning Old Events

Events pile up. Schedule the prune command to keep things clean:

$schedule->command('routersoup:prune')->daily();

By default it keeps the last 24 hours. Need more? Pass --hours:

php artisan routersoup:prune --hours=72

Configuration

After installing, you'll find config/routersoup.php in your app:

return [
    // URI prefix for the admin panel. Set to null to disable it.
    'path' => env('ROUTERSOUP_PATH', 'routersoup'),

    // Middleware applied to admin panel routes.
    'middleware' => ['web', 'routersoup.auth'],

    // Use a separate DB connection. null = app default.
    'database_connection' => env('ROUTERSOUP_DB', null),

    // Rotation strategy: Random or LeastUsed.
    'rotation' => RouterSoupRotation::Random,

    // Toggle provider usage tracking.
    'analytics' => [
        'enabled' => env('ROUTERSOUP_ANALYTICS', true),
    ],

    // Toggle Laravel AI event monitoring.
    'monitoring' => [
        'enabled' => env('ROUTERSOUP_MONITORING', true),
    ],
];

Development

🧹 Keep a modern codebase with Pint:

composer lint

✅ Run refactors using Rector:

composer refactor

⚗️ Run static analysis using PHPStan:

composer test:types

✅ Run unit tests using Pest:

composer test:unit

🚀 Run the entire test suite:

composer test

License

RouterSoup was created by Bardi under the MIT license.