Fb Auth Laravel Package

Getting Started

Confirm the constraints before anything else: this package targets PHP 8.5 / Laravel 12 / Filament 5 (per agents/AGENTS.md), which is a narrow window. Read composer.json first — if your app is on Laravel 11 or PHP 8.3, stop here.

Then:

1. composer require mortezamasumi/fb-auth
2. Publish config and translations: php artisan vendor:publish and select the fb-auth tags. The only knob most teams touch is fb-auth.auth_type, which accepts link, code, mobile, or user.
3. Register the plugin in your panel provider: ->plugin(FbAuthPlugin::make()).
4. Pick your flow and satisfy its dependencies — code needs working mail; mobile needs the sibling packages mortezamasumi/fb-sms (with fb-sms.operator configured) and ariaieboy/filament-jalali.

Where to look first, in order: src/FbAuthPlugin.php (the wiring point — it substitutes Filament's login/register/password-reset/email-verification pages based on Enums/AuthType), config/fb-auth.php, src/FbAuth.php (OTP generation/caching), then src/Pages/ for the flow you're enabling.

First use case: swap Filament's password login for emailed one-time codes. Set auth_type to code, ensure the panel user model implements MustVerifyEmail if you also want the verification flow, and click through login. That single change is the fastest way to see the plugin's whole personality.

Implementation Patterns

Let the plugin fill defaults, override deliberately. FbAuthPlugin only replaces Filament pages the panel hasn't already customized. The idiomatic pattern is to accept the plugin's pages for flows you don't care about and pin your own class for the one you do:

->plugin(FbAuthPlugin::make())
->login(App\Filament\Pages\Auth\MyCodeLogin::class)

Subclass the package page rather than forking it — that keeps you on the upgrade path.

Two ways to consume the OTP logic. Inside Filament you get it for free; outside (API endpoints, custom Livewire components, artisan tooling) resolve the FbAuth facade. Codes are cached under otp-{identifier}, where the identifier is mobile for the mobile flow and email otherwise. Both send and verify are rate-limited at 2 requests/minute, so design your UX around that ceiling rather than discovering it in production.

Keep notification delivery swappable. Email codes go through Laravel notifications (src/Notifications/); mobile codes route through fb-sms. If your team has an existing transactional email provider, wrap or replace those notification classes instead of letting two mail paths diverge.

Email verification is opt-in on both sides. It only replaces Filament's signed-link flow when the panel calls ->emailVerification() and the user model implements MustVerifyEmail. Enable the panel flag without the interface and nothing happens — silently.

Testing pattern worth copying. The package tests with Orchestra Testbench + Pest, building the entire environment inline in tests/TestCase.php: it creates users and password_reset_tokens, registers an admin panel at / with every feature plus the plugin, and loads provider lists for Filament/Livewire/fb-essentials/fb-sms. If you write your own integration tests (you should), mirror that structure — it's the only honest documentation of how the pieces fit. Note AUTH_MODEL in phpunit.xml.dist points at tests/Services/User.php, and the DB is SQLite :memory: with RefreshDatabase.

Match their CI before you push a PR: vendor/bin/pint --test → phpstan analyse (level 8 via Larastan) → pest --ci, in that order.

Gotchas and Tips

• The package description is wrong. The registry blurb calls this "Facebook OAuth authentication." It is not. It's a Filament v5 auth-flow plugin (email link, email code, mobile OTP, user/password). If you were planning social login, you have the wrong package — read agents/AGENTS.md and trust it over the description.
• toEN() is not a method. It's a runtime macro registered by the sibling mortezamasumi/fb-essentials package; PHPStan ignores it via phpstan.neon.dist. Don't "fix" it away, and don't assume it exists unless fb-essentials is installed — otherwise TextInput fields blow up at runtime, not at static-analysis time.
• resources/dist/ is committed. Assets are served from there via FbAuthServiceProvider::getAssets(). If you touch resources/css/index.css or resources/js/index.js, run npm run build and commit the output — otherwise Filament serves stale CSS/JS and you'll debug a phantom caching problem.
• Bilingual strings are a hard contract. Every UI string exists in resources/lang/en/fb-auth.php and resources/lang/fa/fb-auth.php. Changing one without the other is a bug, and the Persian side carries RTL + Jalali date concerns that tests won't catch for you.
• OTP cache key namespacing. otp-{identifier} is a bare key. On shared cache stores or multi-tenant deployments, prefix it or you'll see cross-tenant collisions. Also verify your cache driver in each environment — array in tests, and a misconfigured production store means codes simply never land.
• Queued notifications need a worker. The email/mobile code notifications may queue; if codes "aren't arriving" locally, check the queue before the mailer.
• v5.2.1 is a one-line type fix on the password-reset notification arguments. That's the only published note, and it touches a security-sensitive recovery path. Treat password reset as untested until you've written a regression test asserting the notification argument types and the delivery path.
• Conventional Commits are enforced (feat:, fix:, chore:) because semantic-release auto-publishes from pushes to main/next. Don't hand-edit CHANGELOG or version numbers in a fork.
• Dependency risk is real. Zero stars, single maintainer, and hard coupling to two other packages by the same author (fb-sms, fb-essentials). Pin the version, keep the panel plugin registration in one place, and be prepared to fall back to Filament's native pages if maintenance lapses.
• Debugging order for "code not working": cache store reachable → notification actually dispatched (Horizon/queue logs) → fb-sms.operator set for mobile → rate limit not already exhausted (2/min) → identifier matches exactly what the user typed (email vs mobile).