mortezamasumi/fb-auth
Facebook authentication for Laravel: a small package that wires up the Facebook OAuth login flow so users can sign in with their Facebook account. It provides the redirect and callback handling needed to integrate Facebook login into your app's existing authentication setup.
Architecture fit: Despite the repository description claiming "Facebook OAuth," the authoritative in-repo documentation (AGENTS.md) describes a Filament v5 panel plugin that swaps Filament's default login/register/password-reset/email-verification pages for four configurable flows (link, code, mobile, user) selected via config('fb-auth.auth_type'). Architectural fit is therefore narrow and specific: Laravel 12 + Filament 5 panels, most likely Persian-language admin or customer panels, where teams want OTP-by-email or OTP-by-SMS instead of (or alongside) password login. It is not a general-purpose social auth library, and it is a poor fit for API-only backends, non-Filament front ends, or teams expecting a Laravel guard/provider replacement.
Integration feasibility: Mechanically straightforward for a Filament team: Composer install, register FbAuthPlugin in the panel provider, publish config, choose an auth_type, and let the plugin fill only the page defaults the panel hasn't already overridden. Real effort sits in the dependency web: the mobile flow requires sibling packages mortezamasumi/fb-sms (SMS gateway, needs fb-sms.operator config) and ariaieboy/filament-jalali; the plugin also depends on a runtime macro toEN() registered by fb-essentials, which is masked from PHPStan rather than properly typed. resources/dist/ assets are committed and served directly, so any CSS/JS change requires a manual npm run build and commit — CI does not verify asset freshness.
Technical risk: High relative to a 0-star, single-maintainer package sitting on a security-sensitive path. Specific risks: (1) documentation contradiction — the public description describes Facebook OAuth, which will mislead evaluators and any future maintainer; (2) tight coupling to Filament 5 page internals, which is a fast-moving surface; (3) cross-package runtime coupling via an undeclared macro; (4) OTP codes cached under otp-{identifier} with a 2/min rate limit — correctness depends entirely on the application's cache backend being shared and durable; (5) semantic-release automation means version numbers and changelogs are machine-driven, and the single v5.2.1 note is a narrow notification-argument type fix, giving little signal on overall stability; (6) bilingual en/fa translation files must be updated in lockstep for every UI string.
Key questions:
AGENTS.md? The description should be treated as unreliable until confirmed against composer.json and src/.fb-essentials, fb-sms, filament-jalali)?mobile flow optional, or does installing the package pull the SMS gateway dependency transitively?MustVerifyEmail on the user model, and does it fully replace Filament's signed-link flow?Mobile*/Code* tests hitting a mocked SMS gateway, and is there any test for OTP expiry or rate-limit behaviour?Stack fit: Target is Laravel 12 / PHP 8.5 / Filament 5, per the repo's own toolchain. That PHP 8.5 requirement is bleeding-edge and will exclude most existing estates without an upgrade; confirm it is a floor, not a hard pin. Fit is good for greenfield Filament panels serving Persian-speaking users with SMS OTP; poor for teams that need a stable, widely-adopted auth primitive or that operate outside Filament.
Migration path: Do not replace existing auth wholesale. Spike in a disposable branch: install, register the plugin against a throwaway panel, publish config, and exercise each auth_type you intend to use. Then migrate one flow at a time — typically code (email OTP) first as the lowest-dependency path, then mobile once the fb-sms operator is provisioned and tested. Keep the existing Filament pages registered as a fallback until parity is proven, and use the plugin's "only fills defaults" behaviour deliberately: explicitly override pages you don't want the plugin touching.
Compatibility: Pin the package and all three sibling packages to exact versions; the plugin's behaviour is a function of the whole set. Validate composer.json constraints against your Laravel/Filament/PHP matrix rather than trusting the release note. Verify that resources/dist in the tagged release matches the source (or rebuild locally and diff), since asset drift is otherwise invisible. Confirm toEN() resolves at runtime — if fb-essentials is absent or its macro registration order changes, you get a runtime error that static analysis will not catch.
Sequencing:
src/ and composer.json.fb-sms operator in sandbox mode.MustVerifyEmail.Maintenance: Low day-to-day cost if pinned and confined to a single panel, but the package becomes a security-sensitive dependency with a single maintainer. Semantic-release on main/next means frequent automated patch bumps; adopt a policy of reviewing rather than auto-merging, particularly for anything touching OTP, rate limiting, or notifications. Budget for periodic rebuilds of resources/dist on any UI change, and for updating both en and fa translation files on every string change.
Support: The support burden concentrates in three places: SMS operator configuration (fb-sms.operator), OTP delivery/cache behaviour, and page-override conflicts when a panel already customises login/register. Write a runbook covering cache-store requirements (shared, persistent, non-evicting), rate-limit tuning, translation updates, asset rebuild-and-commit procedure, and rollback to Filament's native pages. Because the plugin only supplies defaults, document exactly which pages your panel overrides and why, or future maintainers will not know which behaviour is yours versus the package's.
Scaling: Filament-side load is modest, but three things scale non-linearly. First, OTP state lives in the application cache under otp-{identifier} — this must be a shared store (Redis et al.) across all nodes, and cache eviction silently invalidates in-flight codes. Second, the 2/min rate limit is keyed per identifier and may be too tight for shared-IP or kiosk scenarios and too loose for SMS-cost protection; validate against expected peak login volume. Third, SMS is a per-message cost and an external availability dependency — model gateway latency, quota, and outage behaviour, and decide whether email code flow is an acceptable degraded path. Mobile-flow users also inherit filament-jalali compatibility risk on every Filament upgrade.
Failure modes: Misconfigured or unavailable SMS operator; OTP cache eviction or a non-shared cache in a multi-node deployment producing spurious "invalid code" errors; rate limiter locking out legitimate users; toEN() macro absent at runtime if fb-essentials is missing or loaded late; committed resources/dist drifting from source after a UI change; Filament minor upgrades breaking page substitution; filament-jalali version skew; translation drift between en and fa; and abandoned-package risk given 0 stars and one maintainer. The v5.2.1 notification-argument type fix is a reminder that this class of bug reaches users as a broken password-reset path — cover it with an automated test rather than relying on release notes.
Ramp-up: A developer already fluent in Filament panel configuration and Laravel notifications will be productive within a day on the code and link flows; the mobile flow adds SMS gateway setup and a second sibling dependency, pushing realistic ramp-up to several days including test coverage. The steeper cost is organisational: someone must own the decision to depend on a low-adoption package on an authentication path, and that owner should document the exit plan — whether that is reverting to Filament defaults, forking, or replacing the plugin with in-house pages — before the first production user authenticates through it.
How can I help you explore Laravel packages today?