Fb Auth Laravel Package

Product Decisions This Supports

• Feature scope: An authenticated Filament v5 admin/backoffice surface delivered as a drop-in plugin, with four configurable flows selected via config('fb-auth.auth_type') — link (magic link), code (email OTP), mobile (SMS OTP), and user (credential-based). This is a launch-acceleration feature, not a differentiator; the differentiation stays in your product surface.
• Roadmap sequencing: Enables committing to "authenticated admin panel" as an early milestone without committing to a permanent auth strategy, because the flow is a config swap rather than a rewrite. Supports A/B or phased rollout across login methods (e.g., start with code, add mobile for mobile-first cohorts).
• Build vs. buy: Buy the plumbing — OTP generation/caching, verification rate limiting (2/min), notification delivery, and Filament page substitution. Own the policy layer: which flows are enabled per cohort, branding, session lifetime, lockout rules, and compliance statements. This is a classic "buy the adapter, own the policy" split.
• Use cases that fit: Persian-first (bilingual fa/en) backoffices, mobile-first products where SMS OTP is the default expectation, internal tools built on Filament where passwordless reduces support tickets, and regional SaaS needing Jalali date handling alongside auth.
• Credibility caveat for the roadmap: The public package description marketing it as "Facebook OAuth" contradicts the repository itself (a Filament multi-flow auth plugin, no Facebook flow in the agent docs, no Firebase stack in the architecture notes). Treat any external copy — and by extension the earlier technical evaluation — as unreliable until verified against src/. This is a documentation-integrity risk that should be resolved before quoting the package in a roadmap or vendor review.

When to Consider This Package

Adopt when all of these hold:

• The product is a Filament v5 / Laravel 12 / PHP 8.5 application; the package's value is almost entirely in its Filament page substitution (FbAuthPlugin overriding login/register/password-reset/email-verification defaults).
• You need passwordless or OTP-based login and would otherwise spend 2–4 engineer-weeks building rate-limited OTP, notification delivery, and guard wiring.
• Bilingual Persian/English is a requirement — translations are maintained in both locales, which is real, ongoing work you avoid owning.
• You can accept sibling-package coupling: fb-essentials (runtime toEN() macro), fb-sms (SMS gateway, requires fb-sms.operator config), and ariaieboy/filament-jalali. The mobile flow is not viable without all three.
• You will pin the version, wrap it behind an application-level auth abstraction, and own a runbook for credential rotation, SMS provider outages, and rollback.
• Your team already understands Filament page overriding and service providers; ramp-up is moderate, not trivial, because failures land on a user-critical path.

Look elsewhere when any of these hold:

• The app is not Filament-based. You are then paying the plugin's dependency weight for very little.
• You need enterprise identity: SAML/OIDC, SCIM provisioning, WebAuthn/passkeys, hardware MFA, or vendor security attestations and SLAs.
• You require a documented compatibility matrix, security policy, or responsive maintainer — the repo has 0 stars, a single maintainer, and no stated security process.
• You need Facebook/social OAuth specifically (as the public description claims). Verify first; the repository evidence says this is not that package.
• You cannot tolerate abandonment risk on a security-sensitive dependency, or your procurement process requires community scale.

How to Pitch It (Stakeholders)

For executives (30 seconds): This package lets us ship an authenticated admin panel — with magic-link, email-code, SMS-code, or password login — in days instead of weeks, with Persian and English out of the box, under an MIT license at zero license cost. The trade-off is dependency risk: it is a young, single-maintainer project with a small community. We mitigate that by pinning the version, isolating it behind our own auth interface so it can be swapped, and adding our own regression tests around password reset and login. Recommendation: proceed to a short, time-boxed spike before we commit it to a release.

For engineering leadership: The plugin's actual mechanism is FbAuthPlugin, which substitutes Filament's default login, registration, password-reset, and email-verification pages based on an AuthType enum — it only fills defaults the panel hasn't overridden, so it composes rather than fights your configuration. OTP codes are generated and cached under otp-{identifier} by the FbAuth service (facade-accessible), with send and verify both rate-limited at 2/min. Delivery goes through Laravel notifications: email inline, mobile via fb-sms. Email verification replaces Filament's signed-link flow only when the panel calls ->emailVerification() and the user model implements MustVerifyEmail.

Quality signals are better than the 0-star count suggests: CI gates on pint --test → phpstan analyse (level 8) → pest --ci, semantic-release drives versioning from Conventional Commits, and the test suite is organized by flow (Link*, Code*, Mobile*, User*, PluginFlowTest, FbAuthServiceTest). That is a disciplined small project, not an abandoned one.

Known friction to budget for: mobile flow is unusable without fb-sms operator configuration and filament-jalali; resources/dist/ is committed and must be rebuilt via npm run build after any CSS/JS change; toEN() is a runtime macro injected by fb-essentials and is PHPStan-suppressed — do not "clean it up." The most recent patch (v5.2.1) is a one-line type fix to password-reset notification arguments, which is exactly the kind of change that warrants targeted tests rather than a routine bump.

The ask: one spike (non-production branch), a compatibility check against our exact Laravel/PHP patch levels, regression tests covering login, verification, password reset request, and notification argument construction, and a written runbook — before this appears in a customer-facing release plan.