Filament Oidc Laravel Package

Technical Evaluation

What this release is. filament-oidc 3.1.0 is a refactor release, not a feature release. The OIDC identity model (OidcIdentity) and the HasOidcIdentities trait have been extracted out of the Filament plugin and into a new shared core package, jeffersongoncalves/laravel-oidc v1.3.0. The Filament plugin becomes a thin UI/panel-integration layer over a framework-agnostic OIDC persistence layer. That is a sound architectural direction — identity persistence does not belong in a Filament plugin — but it introduces a new hard runtime dependency and a set of namespace/config/migration-tag renames that our code and deployment tooling must absorb.

Architecture fit. Reasonable. Identity records (issuer, subject, user linkage) are now shared across any Laravel surface, not just Filament panels, which is what we would want if we later add OIDC login to a separate API or a non-Filament admin surface. The trade-off is that we now depend on two packages from the same single maintainer instead of one, with the version compatibility matrix between them (filament-oidc 3.1.x ↔ laravel-oidc ~1.3) maintained by hand. There is no evidence in the release notes of a formal compatibility constraint mechanism beyond Composer requires.

Breaking surface, precisely. Four renames, all mechanical:

• JeffersonGoncalves\Filament\Oidc\Models\OidcIdentity → JeffersonGoncalves\LaravelOidc\Models\OidcIdentity
• JeffersonGoncalves\Filament\Oidc\Concerns\HasOidcIdentities → JeffersonGoncalves\LaravelOidc\Concerns\HasOidcIdentities
• Config key filament-oidc.identities_table → oidc.identities_table
• Migration tag filament-oidc-migrations → oidc-migrations

Crucially, the release states the table name and schema are unchanged, and previously published migrations continue to work. That materially de-risks the upgrade: there is no data migration, no backfill, no column changes. The blast radius is limited to (a) PHP use statements in our code, (b) any config reads using the old key, and (c) deployment scripts or runbooks that reference the old vendor:publish tag. Any of our own code reading config('filament-oidc.identities_table') will silently return null after upgrade rather than erroring — that is the highest-risk item because it fails quietly.

Technical risk. Three concerns worth flagging to the review board:

1. Semantic versioning trust. This is a breaking change shipped in a minor bump (3.0.0 → 3.1.0). For a 3.x package that is a contract violation. Operationally we should treat any release from this maintainer as potentially breaking and pin exact versions rather than using caret ranges.
2. Supply chain / bus factor. Both packages are single-maintainer. Extracting persistence into a second package doubles the surface area we depend on, and v1.3.0 is the first release of that package in this role — i.e. we are adopting a freshly-extracted dependency as the load-bearing layer for authentication identity records.
3. Authentication blast radius. This plugin gates admin panel access. A defect here is not a cosmetic bug; it is either a lockout (availability) or an auth bypass (security). Upgrades should be treated as security-relevant changes requiring staged rollout, not routine dependency bumps.

Key questions for the maintainer / our own team:

• Does laravel-oidc 1.3.0 publish its own config file and migration tag (oidc.*, oidc-migrations)? Must both packages' migrations be published and run, or does the Filament plugin's migration now live solely in the core package? The notes imply the latter but do not say it explicitly.
• What is the declared Composer constraint on laravel-oidc — ^1.3, ~1.3.0, or exact? This determines our exposure to the same minor-bump-breaking pattern one level down.
• Are OidcIdentity and HasOidcIdentities API-compatible with their predecessors (same methods, same relations, same fillable fields)? The namespace moved; the notes do not assert behavioural equivalence.
• Does v1.3.0 of the core package require a different minimum Laravel/PHP than filament-oidc 3.0.0? If it pulls in Laravel 10→11 or PHP 8.2→8.3 expectations, this is no longer a drop-in.
• Is there a documented deprecation path — i.e. does 3.1.0 ship class aliases for the old namespaces so a two-step upgrade is possible? Nothing in the notes suggests it does.

Integration Approach

Stack fit. If we are on filament-oidc 3.0.0 today, we are already committed to a Filament panel, an OIDC provider, and the oidc_identities table. This release changes where that code lives, not what it does. There is no new infrastructure, no new service, no protocol change. Fit is therefore high — the concern is upgrade mechanics, not architecture.

Migration path. The absence of a schema change is what makes this tractable. Recommended sequence:

1. Inventory before touching Composer. Grep the codebase for the four old symbols: the two fully-qualified class names, filament-oidc.identities_table, and filament-oidc-migrations. Also grep for filament-oidc. generally, in case other config keys are being read that we have not accounted for. Include Blade templates, queued jobs, seeders, and test fixtures — not just app/.
2. Check for a shim first. Attempt the upgrade on a branch without code changes and see whether the old class names still resolve (aliases). If they do, we get a two-phase migration: upgrade, then clean up namespaces separately. If they do not, code changes and the dependency bump must land in the same commit — a single atomic PR, never split across deploys.
3. Publish and diff config. Run vendor:publish for whatever tags the new core package exposes and diff the resulting config/oidc.php against our current config/filament-oidc.php. Carry over any customisations (table name if we renamed it, provider settings). Do not blindly overwrite a published config in a running environment.
4. Validate migration state. Confirm php artisan migrate:status shows no pending migration from the new oidc-migrations tag on a database that already has oidc_identities populated. If the core package ships the same migration under a new tag, we need to be certain it is guarded by Schema::hasTable() or that we skip it. This is the one place where "schema unchanged" could still bite us as a duplicate-table error.
5. Verify auth end-to-end in staging against a real IdP, not a mock: fresh login creates an identity row, an existing user with a pre-existing identity row logs in without creating a duplicate, and logout/session behaviour is unchanged. Then verify that a user with no identity row is still denied, i.e. no auth bypass from the trait rewrite.
6. Roll forward, not back. Because the schema is unchanged, a code-level rollback to 3.0.0 is safe (old code reads the same table). Keep that option explicit in the change record.

Compatibility and sequencing. Treat this as a coordinated two-package bump: laravel-oidc must be installed at a version satisfying the Filament plugin's constraint, and composer.lock must be committed. Sequence within a sprint: inventory → branch upgrade with shim check → config diff → migration status check → staging IdP login test → production. Do not bundle this with a Laravel or Filament major upgrade; if one is already in flight, land that first or defer this, because debugging an auth failure across two simultaneous major variables is expensive.

Operational Impact

Maintenance. Steady-state maintenance is modest — this is a config-and-model package, not a service. The real cost is upgrade tax: we now track two packages, both single-maintainer, both prone to breaking changes in minor versions. Recommend pinning exact versions (3.1.0, not ^3.1) for both, with upgrades driven by a deliberate review rather than composer update. Budget a small recurring allowance for reading release notes on both packages before any dependency refresh.

Support and ownership. Assign a named owner — realistically the platform/backend engineer who owns admin authentication. This cannot sit in an unowned dependency backlog: an unreviewed bump here can lock every administrator out of the panel. Document the IdP configuration, the callback URL, and the identity table in the runbook, since the code that implements them has just moved to a package we did not previously operate.

Scaling. No change. Identity lookup is a single indexed query per login; OIDC flows are per-authentication, not per-request. Volume scales with login frequency, not traffic. No action needed.

Failure modes to plan for.

• Silent config failure — code reading filament-oidc.identities_table after upgrade returns null; queries may then target an empty table name or throw an opaque error. This is the most likely post-upgrade incident. Mitigate by grepping exhaustively and asserting the resolved config in a smoke test.
• Class not found — a missed use statement in an untested code path (queue job, scheduled command, Blade component) fatal-errors at runtime, potentially only on the login path. Mitigate by running the full test suite and a static-analysis pass across the whole repo, not just app/.
• Duplicate migration — if the core package re-ships the identities migration under the oidc-migrations tag and it is not idempotent, migrate fails on an existing database. Mitigate by checking migrate:status in staging against a production-like snapshot.
• Lockout — worst case, admins cannot authenticate to the panel. Mitigate by keeping a break-glass path (e.g. an existing local admin account or CLI access) available and tested during the rollout window, and deploy in a low-traffic period with the previous release artefact retained.
• Ecosystem drift — the core package is at 1.3.0 and may itself break in a minor bump, silently pulling the plugin out of compatibility. Mitigate with lockfile discipline and a periodic composer outdated review.

Ramp-up. Low. The change is four renames and a config-key move; an engineer familiar with Laravel service providers and Composer can execute it in half a day, with most of that time in verification rather than editing. The genuinely new knowledge is operational, not code: understanding that identity persistence now lives in a separate package, that migrations may now be published under two tags, and that this maintainer's minor releases should be treated as potentially breaking. Capture that in the runbook so the next engineer does not rediscover it during an incident.

Recommendation. Adopt 3.1.0 — the architectural direction is right and the unchanged schema makes it a controlled, low-data-risk change. But gate it on the four key questions above (especially config/migration ownership and the laravel-oidc Composer constraint), ship it as a single atomic PR with exhaustive symbol grep, and pin exact versions on both packages going forward.