andrecorugda/ai-openrouter-gateway
A Laravel package that integrates the OpenRouter AI gateway, giving PHP applications a simple, unified way to send prompts and manage models, API keys, and responses through OpenRouter's multi-model API.
Architecture fit. The package is a Laravel package that fronts an AI gateway and ships two consumer surfaces: a standalone Scalar-rendered reference at {prefix}/docs and a panel-embedded "API docs" iframe inside Filament. v1.3.2 is a presentation-layer change — dark-mode theming for both surfaces — driven by a single config flag (ai-gateway.api.docs.dark_mode / AI_GATEWAY_API_DOCS_DARK). Architecturally this is low-coupling: it touches view/asset rendering and config resolution only, with no changes to routing, auth, persistence, or the gateway proxy path. For a TPM this reads as a low-blast-radius release that does not alter the package's integration contract.
Integration feasibility. Trivial. The default is true (dark), so existing installs pick up the change with zero code edits; teams wanting the prior light rendering set the env var to false or publish/override the config. There is no migration, no schema change, no new service dependency, and no new credential. The only integration work is a config publish/verify step if the consuming app has a cached config (php artisan config:cache must be re-run in deploy).
Technical risk. Low for the feature itself, moderate for the version-line signal. The release note explicitly states this is the Filament 3 line and directs Filament 4/5 consumers to ^2.0 (currently v2.0.2). That is the material risk: the package has forked into two maintained majors aligned to Filament's major, which means our Filament upgrade path is now gated on a corresponding ai-gateway major upgrade. Cosmetic regressions are plausible but cheap to detect — dark-mode contrast in an embedded iframe can break against host-panel theming, particularly if the parent panel uses a custom theme or a light-only design system.
Key questions.
^1.3 or ^2.0?dark_mode read at render time or baked into published assets? (Determines whether a config flip requires an asset rebuild.)^2.0 carry breaking config/route changes?Stack fit. Fits a standard Laravel + Filament admin stack. The config-key-plus-env-var pattern is idiomatic Laravel and matches how the rest of the package is presumably configured (config/ai-gateway.php with AI_GATEWAY_* env overrides). The Scalar dependency is a documentation-rendering concern only — it does not sit on the request path for gateway traffic, so it introduces no runtime coupling to the AI provider calls themselves.
Migration path. Effectively a no-op upgrade within the Filament 3 line: bump the constraint, re-run config:cache in each environment, and visually verify both /docs and the panel iframe. If our brand or accessibility requirements mandate light rendering, add AI_GATEWAY_API_DOCS_DARK=false to the environment matrix before rollout rather than patching views. Teams on Filament 4/5 must not take this release — they should be tracking ^2.0 and should treat v1.3.2 as out of scope entirely.
Compatibility. Primary compatibility axis is the Filament major, and the release note draws that line explicitly. Secondary axes: PHP and Laravel version support (unstated here — must be confirmed against the ^1.3 and ^2.0 composer constraints), and the Scalar version bundled for docs rendering. The dark-mode default flip is a behavior change in appearance only, not a breaking change in the semver sense.
Sequencing. Recommended order: (1) confirm our Filament major and pin the correct ai-gateway line in composer.json; (2) determine the desired docs theme per environment (prod may want light for brand consistency, internal/staging dark); (3) upgrade in staging with config cache cleared and both docs surfaces screenshot-tested; (4) promote to production, then (5) open a separate track to evaluate the Filament 4/5 migration and the corresponding ^2.0 ai-gateway upgrade as a single coupled work item. Do not let the Filament major upgrade and the ai-gateway major upgrade be scheduled independently — they are now a single dependency decision.
Maintenance. Near zero incremental cost for this release. The real maintenance burden is the two-major support matrix: we are now maintaining a version constraint that is coupled to Filament's release cadence, and every Filament major will require a coordinated ai-gateway major. Budget for that as recurring, not one-off.
Support. Dark mode is a visible, user-facing surface with a config toggle. Expect a small tail of support tickets along the lines of "docs page is unreadable," "iframe looks wrong in our custom theme," and "we set the env var but nothing changed" (config cache). Publish a one-line runbook entry: which env var, which default, and the config:cache requirement. Also document the Filament-version-to-package-version mapping in our internal dependency register — that mapping is the single most useful operational artifact this release gives us.
Scaling. Not a scaling concern. Both docs surfaces are static rendering; the embedded iframe adds one same-origin request per page view. No impact on gateway throughput, queue depth, or provider rate limits. If the iframe is served to external end-users at high volume, ensure it is cached at the edge like any static doc asset.
Failure modes.
^2.0 unintentionally via a loose constraint such as * or >=1.0. This is the highest-severity failure mode here and is entirely preventable with an explicit, bounded constraint.^2.0, Filament 3 consumers accrue quiet security and compatibility debt.Ramp-up. Minimal for developers — one config key, one env var, one default. The non-obvious knowledge to transfer is the version-line split and why it exists. Capture it in the dependency register and in the upgrade runbook, not in tribal memory, because the person who performs our eventual Filament 4/5 migration may not be the person reading this release note today.
How can I help you explore Laravel packages today?