Multimodal Php Laravel Package

Technical Evaluation

Architecture fit. betterauth/multimodal-php is a framework-agnostic authentication core, not a Laravel package. It delivers session auth, Paseto V4 token auth, OAuth social login, an OIDC server, magic links, TOTP 2FA, adaptive session-risk scoring, multi-tenancy primitives, a plugin hook system, and 20 PDO-backed repositories behind 28 interfaces. For a Laravel application, that means it would sit beside—not inside—Laravel’s native auth stack. There is no service provider, guard, middleware, facade, config publisher, migration set, or Artisan surface. Integration would require custom Laravel glue: binding interfaces to PDO repositories, writing guards and middleware, wiring routes/controllers, and adapting Laravel’s cache/session/queue abstractions.

Integration feasibility. The core is installable via Composer and requires PHP 8.2+, json, openssl, and pdo, which Laravel 11/12 already satisfy. The bundled PDO storage is documented as MySQL/MariaDB-oriented; SQLite and PostgreSQL require custom repository implementations, which is a significant hidden cost for Laravel teams standardized on PostgreSQL. The rate limiter requires a PSR-6 cache and refuses to operate without one unless explicitly opted out; Laravel’s cache contracts are PSR-16, so an adapter (e.g., Symfony Cache) or custom bridge is needed. The plugin hook system is useful for audit logging but is not Laravel’s event system, so observability and domain events would need a translation layer.

Technical risk. The dominant risk is lifecycle: the package is archived and explicitly deprecated, with direction to use betterauth/symfony-bundle v1 instead. That bundle is Symfony-specific and does not solve Laravel integration. With 1 GitHub star, 0 dependents, and an archived repository, there is effectively no community, no downstream validation, and no expectation of security patches. Authentication is security-critical; adopting an archived auth core creates an unacceptable patch-response gap unless the team forks and owns it. The 0.1.0 changelog shows material breaking changes—hashed-at-rest ephemeral tokens invalidating existing plaintext values, a required rate limiter, a changed 2FA completion signature—which signals pre-1.0 API churn. The package is technically substantive and includes a security-hardening pass, but that raises the bar for internal ownership rather than lowering adoption risk.

Key questions.

• Will the maintainer continue security releases for the core despite the archive/deprecation notice, or is the Symfony bundle the only supported path?
• Is there a Laravel bundle or roadmap? If not, are we prepared to fork and maintain the core plus Laravel glue?
• Does the Symfony bundle expose framework-agnostic services that could be reused in Laravel, or is it tightly coupled to Symfony DI/HTTP kernel?
• What is the support model and bus factor? Is commercial support available?
• Which Laravel-native capabilities already cover 80%+ of the need (Sanctum, Fortify, Socialite, Passport, pragmarx/google2fa), and is the remaining 20% (OIDC server, risk scoring, organizations) worth the ownership burden?
• Are PostgreSQL repositories required, and who would build and test all 28 interfaces against our schema?
• How do we reconcile PDO repositories with Eloquent models, transactions, read/write connections, and existing user tables?
• What is the migration/exit plan if the fork becomes untenable?

Integration Approach

Stack fit. Laravel already provides mature auth primitives: guards, session management, Sanctum for API tokens, Passport for OAuth2/OIDC, Socialite for social login, Fortify for 2FA/password reset, and robust rate limiting and cache abstractions. betterauth/multimodal-php overlaps heavily with these. Its differentiated capabilities are the OIDC server, adaptive risk scoring, organization/team/invitation multi-tenancy, and the plugin hook system. A pragmatic fit is to adopt it only for those differentiators—most likely as a bounded OIDC/SSO service—rather than replacing Laravel’s native session and guard stack. If adopted wholesale, expect to build a Laravel adapter layer that maps the library’s DTOs and repositories onto Eloquent and Laravel’s container.

Migration path. Do not migrate existing users and sessions directly into the PDO repositories without a data-mapping plan. The 0.1.0 changelog explicitly invalidates existing plaintext ephemeral tokens (magic links, password resets, email verification, OAuth codes, guest sessions), and password hashes are Argon2id via the library’s PasswordHasher; Laravel’s default hasher is bcrypt. A staged path: (1) run the library in parallel for new OIDC/SSO flows only; (2) map users by email with a verified-email requirement; (3) dual-write or lazily rehash passwords on login if the library becomes the primary authenticator; (4) keep Laravel sessions authoritative until the library’s session/risk layer is proven. If the goal is simply to replace Laravel auth, the migration cost likely exceeds the benefit.

Compatibility. PHP 8.2+ aligns with Laravel 11/12. Composer resolution should be validated early: the package brings its own Paseto, PSR-6, and PDO dependencies; conflicts with Laravel’s cache/session packages are plausible. The library is framework-agnostic, so there are no Laravel version constraints to protect against future Laravel breaking changes. The PDO storage targets MySQL/MariaDB; PostgreSQL and SQLite require custom repositories. The security-hardening changes around OIDC (mandatory S256 PKCE for public clients, client-bound refresh tokens, nonce handling, optional RS256/JWKS) are strong, but they also mean OIDC client configuration must be treated as a first-class integration task, not an afterthought.

Sequencing.

1. Discovery spike (1–2 weeks): install in a scratch Laravel app, bind the PDO repositories, implement one session flow and one OIDC authorization-code + PKCE flow, and measure the glue code required.
2. Security and lifecycle review: confirm the archive/deprecation status, determine whether the core will receive patches, and decide fork-vs-adopt.
3. Build-vs-buy decision: compare against Laravel-native (Sanctum/Fortify/Socialite/Passport) plus targeted packages for TOTP and OIDC.
4. If adopting: build a first-party Laravel adapter package—service provider, config, interface bindings, guards, middleware, routes, migrations, and PSR-6 cache bridge—and pin the dependency.
5. Pilot: run the OIDC/SSO or risk-scoring capability in front of a low-risk internal application, with shadow-mode risk decisions logged but not enforced.
6. Production rollout: enable enforcement incrementally per route group; keep Laravel session auth as fallback until the new path is stable.
7. Exit plan: document how to remove the library and return to Laravel-native auth.

Operational Impact

Maintenance. Because the repository is archived, maintenance becomes an internal responsibility. That means owning a fork of the core, tracking upstream security advisories (or the absence of them), patching Paseto/Argon2id/OIDC flaws ourselves, and maintaining the Laravel adapter. The plugin and interface architecture makes forking feasible, but it is still a security-critical codebase. Budget for a named owner, dependency scanning, and periodic security review. The alternative—using Laravel-native components—distributes maintenance across a much larger maintainer community.

Support. Community support is effectively nonexistent at 1 star and 0 dependents. Documentation is a solid README with examples, but there are no Laravel-specific guides, no Stack Overflow footprint, and no evident commercial support. The deprecation notice points to a Symfony bundle that does not serve Laravel. Internal team knowledge will be the primary support channel, so documentation of the adapter and runbooks is mandatory.

Scaling. Paseto V4 local tokens are stateless and scale horizontally well; session mode depends on the session table, which will need indexing, cleanup jobs, and connection-pool planning. Adaptive risk scoring performs per-request work involving IP, device, country, and impossible-travel signals; that implies lookup tables and possibly GeoIP, adding latency and cache dependency. The rate limiter requires shared PSR-6 cache (e.g., Redis) to work across nodes; the in-memory fallback is a per-process no-op and should be disabled in production. Multi-tenancy repositories can become hot spots under high organization/membership volume. The library does not ship Laravel queue integration, so cleanup, email sending, and audit events must be wired manually.

Failure modes.

• Archived dependency: a future PHP or Laravel upgrade breaks compatibility with no upstream fix.
• Token invalidation on deploy: the 0.1.0 hashing change invalidates existing plaintext ephemeral tokens; similar future changes could log users out or break password-reset links.
• Rate-limiter misconfiguration: without a shared PSR-6 cache, auth endpoints either fail closed (if configured strictly) or silently lose protection (if fallback is enabled).
• Cache outage: Redis unavailability can block login, 2FA verification, and risk evaluation.
• Database coupling: PDO repositories bypass Eloquent, so Laravel model events, soft deletes, and connection routing do not apply; schema drift and transaction boundary bugs are plausible.
• Risk-scoring false positives: impossible-travel and country-change signals can terminate legitimate sessions for VPN/mobile users; enforcement must be staged with logging first.
• OIDC misconfiguration: PKCE enforcement, client-secret hashing, redirect URI validation, and nonce handling are easy to get wrong; a partial integration can create account-takeover exposure.
• 2FA replay/rate-limit gaps: the library now requires a rate limiter for TOTP and enforces anti-replay, but custom integrations can bypass these if not wired carefully.

Ramp-up. The README is sufficient for a senior PHP engineer to run the standalone examples in a day. Laravel-specific ramp-up is longer: expect 2–4 weeks for a competent engineer to build a production-grade adapter (service provider, guards, middleware, PSR-6 bridge, migrations, tests) and another 1–2 weeks for security review and OIDC conformance testing. Team onboarding requires explaining both the library’s domain model and the custom Laravel glue. Given the archive status, the more defensible recommendation for a Laravel-centric organization is to use Laravel-native auth for sessions, tokens, social login, and 2FA, and to evaluate a maintained OIDC server package (or Passport) for SSO. Adopt betterauth/multimodal-php only as a time-boxed spike or as a fork with explicit ownership, not as a long-term foundational dependency.