Ai Openrouter Gateway Laravel Package

Getting Started

The package is a Filament integration for an AI gateway: it gives you a unified AI endpoint plus a generated API reference. v1.3.2 is a small feature release in the Filament 3 line (^1.3); if you are on Filament 4/5 you need ^2.0 instead — do not mix the constraints.

Minimal setup:

1. Require the package with the Filament 3 constraint: composer require <vendor>/ai-gateway:^1.3.
2. Publish the config (config/ai-gateway.php) and set your provider credentials / gateway options via env.
3. Register the plugin (or the docs page) in your panel provider if you want the embedded "API docs" screen.
4. Visit {prefix}/docs for the standalone Scalar reference, or open the "API docs" page in the panel.

Where to look first: the api.docs block in config/ai-gateway.php (prefix, middleware, and now dark_mode), then the generated /docs route. The first real use case is turning the gateway into something your frontend/mobile team can consume: they read /docs, you keep the config as the contract.

Implementation Patterns

• Environment-driven theming. v1.3.2 adds ai-gateway.api.docs.dark_mode / AI_GATEWAY_API_DOCS_DARK, default true. Set AI_GATEWAY_API_DOCS_DARK=false in .env when you want the light Scalar theme, e.g. to match a light Filament admin panel. Since it is a normal config value, it can differ per environment (true locally, false in production, or vice versa).
• Panel-embedded docs. The "API docs" Filament page renders the standalone docs in an iframe, so both surfaces share the same dark-mode setting. Configure the standalone route once (prefix, middleware, auth) and the panel page inherits it.
• Auth in front of docs. If the docs are internal, put the same auth middleware on the docs route that the panel uses. Because the iframe is same-origin, the panel session cookie is sent — but if you attach a different guard to the docs route, the iframe will render a login page or 401 inside the panel. Keep guards aligned.
• Version pinning. Pin ^1.3 explicitly on Filament 3 projects and document the ^2.0 line for Filament 4/5 in your upgrade notes. Composer will happily resolve the wrong major if your Filament constraint is loose.
• Docs as a smoke test. Hit /{prefix}/docs in CI or a post-deploy check to catch route-prefix regressions, missing config, or middleware changes before consumers notice.

Gotchas and Tips

• Dark mode is on by default. Upgrading to v1.3.2 flips existing installs to the dark Scalar theme. Not breaking, but it is a visible change — if your panel is light, set AI_GATEWAY_API_DOCS_DARK=false to avoid a dark docs iframe inside a light admin.
• Config cache. AI_GATEWAY_API_DOCS_DARK must be present when php artisan config:cache runs. After changing it, run php artisan config:clear (or rebuild the cache) or the old value persists.
• Iframe vs. panel theme. The embedded docs do not automatically follow Filament's light/dark toggle; they follow this config. Treat panel theme and docs theme as two separate decisions.
• Published views win. If you have published/overridden the docs view, the new dark-mode rendering may live in the package's view. Re-publish or diff the view after upgrading, otherwise the config flag can appear to do nothing.
• Prefix and route caching. Changing the docs prefix requires clearing/rebuilding the route cache (php artisan route:cache); stale cached routes are a common "why is /docs 404?" cause.
• Framing and CSP. If the iframe is blank behind a reverse proxy or strict CSP, check X-Frame-Options / frame-ancestors. Same-origin defaults usually work; custom domains and proxies are where it breaks.
• Extension points. The config file is the primary knob (prefix, middleware, dark mode); for deeper changes, override the registered docs page/view rather than editing vendor files, and keep the override in sync with the ^1.3 line.