Fb Suite Laravel Package

Getting Started

First, resolve what you're actually installing. The package metadata is contradictory: the repo description says "Meta-package bundling all fb-* Filament packages," the long description claims a Facebook Graph API client with OAuth helpers and webhook handling, and the release notes are about fb-auth password reset and OTP. Before you write a line of code, open vendor/mortezamasumi/fb-suite/composer.json — for a meta-package that file is the authoritative spec, more so than any README. Whatever it requires is what you're really adopting.

Install

composer require mortezamasumi/fb-suite:^5.0.3
composer show mortezamasumi/fb-suite --tree   # what did the umbrella actually pull in?
composer show mortezamasumi/fb-auth           # confirm >= 5.1.5

That last check is not optional. v5.0.3 is a dependency-floor bump (fb-auth ^5.1.5) to pick up a reset-password null-OTP fix. If the lock file doesn't re-resolve, you have the new fb-suite constraint and the old, affected fb-auth simultaneously.

Publish and boot

php artisan vendor:publish          # interactive list — note the actual tags
php artisan migrate
php artisan route:list | grep -i -E 'auth|otp|reset'

Publish from the child packages, not the umbrella; a meta-package typically ships no config, migrations, or views of its own.

Where to look first

1. vendor/mortezamasumi/fb-suite/composer.json — the real dependency manifest.
2. vendor/mortezamasumi/fb-auth/ — service provider, routes, config.
3. vendor/mortezamasumi/fb-auth/CHANGELOG.md across the range you skipped (5.1.0 → 5.1.5), not just the head entry.

First use case: the password reset flow with OTP enforcement. It's the one path the release notes explicitly touch, so it's simultaneously the best-characterized and the highest-risk thing in the package. Wire it up, then break it deliberately.

Implementation Patterns

Write against the child packages, never the umbrella. fb-suite should appear in exactly one place in your codebase — composer.json. Every use statement, facade, contract, and config key in your application points at fb-auth (or whichever sibling you actually need). This keeps your surface honest and makes the eventual "drop the umbrella, depend directly" migration a one-line change.

Pin the floor, track the rest. Use ^5.0.3 and let Renovate/Dependabot propose bumps, but disable auto-merge for mortezamasumi/*:

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^mortezamasumi/"],
      "automerge": false,
      "labels": ["dependency", "auth-path"]
    }
  ]
}

The upgrade ritual (every fb-* release, not just majors):

git checkout -b chore/fb-suite-bump
# edit constraint in composer.json
composer update mortezamasumi/fb-suite mortezamasumi/fb-auth --with-dependencies
git diff composer.lock          # did fb-auth actually move? did a sibling get downgraded?

Read the lock diff before reading the changelog. The diff tells you what happened; the changelog tells you what was intended.

Bind and override, don't fork. If you need to change behavior, resolve the child package's contract in your own service provider rather than editing vendor/. Because the suite owns the dependency graph, a path repository override is your escape hatch if you ever need to patch upstream:

"repositories": [{ "type": "path", "url": "packages/fb-auth" }]

Regression-test the reset flow yourself. This is the durable protection and it survives any upstream decision:

it('rejects password reset with a null OTP', function () {
    $user = User::factory()->create();
    $this->post('/password/reset', [
        'email' => $user->email,
        'token' => 'valid-token',
        'otp'   => null,
    ])->assertSessionHasErrors('otp');
});

it('rejects password reset with an empty OTP', fn () => /* ... */);
it('rejects password reset with an expired OTP', fn () => /* ... */);

Add a fourth that asserts the password did not change — an error bag is not proof of rejection.

Guard the endpoints regardless of what the package does. Rate-limit reset and OTP-issue routes in your own middleware group; enumeration and OTP-spraying are your problem even if the package is silent on them. Emit a counter on reset attempts and OTP failures so "reset emails aren't arriving" pages the right person.

Keep app code on interfaces. If the package exposes a facade or contract for the reset/OTP service, inject it rather than using the facade directly. You will want to swap or wrap it, and a constructor typehint is cheaper to satisfy than a facade root.

Gotchas and Tips

The description conflict is the headline risk. A "Facebook Graph API + webhook" toolkit and a "Filament package bundle with OTP auth" have nothing in common. Until you've read vendor/mortezamasumi/fb-suite/composer.json with your own eyes, assume neither description is accurate and build nothing. If it turns out to be the auth bundle, the Graph API/OAuth/webhook material is aspirational documentation and you should not design against it.

Lock-file non-resolution is the specific trap of this release. A floor bump that isn't re-resolved is invisible: composer.json looks correct, CI passes, and fb-auth is still 5.1.4 at runtime. Assert the installed version in CI:

composer show mortezamasumi/fb-auth | grep -q '5\.1\.[5-9]'

Treat the null-OTP defect as an authentication bypass until proven otherwise. "Null OTP" could be an unhandled TypeError (a 500 — annoying) or a comparison that treats null as a match (a bypass — an incident). The failure mode determines whether this is a maintenance bump or a disclosure-adjacent remediation. Get a straight answer before you close the ticket.

Meta-package version churn is structural, not incidental. The suite's version moves whenever any child moves, so you get a steady trickle of patch releases that are individually trivial and occasionally security-bearing. Group them into a maintenance window with a changelog-review step; don't ad-hoc merge them, and don't let a "it's just a patch" reflex skip the diff.

Composer conflict soup. Every fb-* sibling pins fb-auth somewhere. Raising the floor can deadlock resolution if another sibling still constrains below 5.1.5. This surfaces as a blocked build, not a production incident — annoying but safe. If it deadlocks, stop and evaluate depending on fb-auth directly rather than forcing the umbrella.

Zero stars and a single maintainer in the auth path. Confirm you can build and test the package locally before you need to. A fork-and-patch posture is a multi-day exercise discovered under pressure; discovering it during a Laravel upgrade window is the bad version.

OTP store backend. If OTPs live in cache, check your cache driver and eviction policy. Redis under allkeys-lru will drop an OTP under memory pressure, which presents as a support ticket ("the code doesn't work") rather than an alert. Prefer a durable store with explicit TTL for one-time codes.

After publishing, clear the boot cache. A stale bootstrap/cache/config.php or a cached services.json is the classic reason a freshly published config appears to be ignored:

php artisan optimize:clear
php artisan about   # confirm the provider registered

Extension points, in order of preference: config publish → contract binding in your own provider → path repository override → fork. Never hand-edit vendor/; the next composer update silently reverts it and you'll debug a fix that isn't there.