Fb User Laravel Package

Getting Started

Install and confirm discovery

composer require mortezamasumi/fb-user

The package ships a Laravel service provider and configuration support, so on Laravel 5.5+ it should register via package auto-discovery. Confirm this immediately after install:

php artisan package:discover
composer show mortezamasumi/fb-user

If the provider does not appear in bootstrap/cache/packages.php, register it manually in config/app.php under providers (and the accompanying alias/facade if one is exposed).

Publish the config first

php artisan vendor:publish --provider="MortezaMasumi\FbUser\FbUserServiceProvider"

The exact provider namespace is the first thing to verify in vendor/mortezamasumi/fb-user/composer.json (extra.laravel.providers). Publishing gives you the config file that holds whatever credentials/options the package expects. Commit the published config; keep secrets in .env.

Where to look first

Because the README is thin, treat the source as the documentation. Read in this order:

1. composer.json — namespace, Laravel/PHP constraints, autoload map.
2. src/*ServiceProvider.php — what is bound into the container, what is publishable, whether a facade or helper file is registered.
3. config/*.php — the actual knobs (credentials, table/model names, Facebook API version if configurable).
4. Any model, trait, or contract under src/ — what shape the Facebook user data takes and how it attaches to your User.
5. The OperatedBy helper (the subject of the v5.3.1 fix) — this is the one feature with an explicit release note, so it is the highest-signal entry point.

First use case

The realistic first slice is: a user authenticates via Facebook (using whatever you already have — Socialite or otherwise), and you persist/resolve their Facebook profile through this package against your users table, then use OperatedBy to stamp who performed an action. Start with a single feature test that takes a raw Facebook profile payload and asserts a local user record, before wiring anything into a controller.

Implementation Patterns

Wrap the package behind your own interface. Given the single-maintainer risk and sparse docs, do not let FbUser types bleed into controllers, jobs, or domain services. Define a narrow contract in your app:

interface FacebookIdentityResolver
{
    public function resolve(array $facebookProfile): User;
    public function operatedBy(User $actor): mixed;
}

Implement it once, delegating to the package. Swapping the dependency later becomes a one-file change.

Normalise payloads at the boundary. Facebook profile payloads are irregular (missing fields, nested picture objects, locale-dependent data). Convert the raw payload into your own DTO or array shape before handing it to the package, and convert the package's output into your User model immediately. This keeps schema assumptions in one place and makes the package's data model an implementation detail.

Use OperatedBy as the attribution primitive. The v5.3.1 patch was a formatting fix to this helper, which tells you it is actively used and intended for display/audit. Typical pattern:

• Persist the operator at write time (a column or an audit row), not at render time.
• Treat the helper as a presenter/formatter — call it in resources, Blade components, or API transformers.
• Do not rely on it for authorisation decisions; it answers "who", not "may they".
• If you adopt it, add a snapshot test pinning the formatted output, since formatting was the thing that changed in a patch release.

Keep the integration in one layer. A workable layout:

app/Integrations/Facebook/
├── FacebookIdentityResolver.php      // your contract
├── PackageFacebookIdentityResolver.php // delegates to fb-user
├── FacebookProfileData.php           // your DTO
└── FacebookUserSynchronizer.php      // create-or-update logic

Then the package appears in exactly one or two classes, plus config.

Version-pin and schedule upgrades. Patch releases here are routine maintenance (format OperatedBy helper, minor updates). Pin an exact version in composer.json or use a tight constraint, and put the package on a quarterly review rather than letting composer update move it silently. Run your formatter/attribution snapshot tests after every bump.

Test against fakes, not Facebook. Bind your resolver contract to an in-memory implementation in tests. Add one integration test that exercises the real package against a recorded JSON fixture of a Facebook profile, so an upgrade that changes parsing behaviour fails loudly.

Handle credentials via config only. Read tokens/app IDs from config('fb-user.*') (or whatever the published key is) mapped from .env. Never construct the package's client with inline secrets, and never log the raw payloads — they contain profile data and potentially tokens.

Gotchas and Tips

Auto-discovery and namespace assumptions. Verify the provider class name from composer.json rather than guessing from the repo name. Single-maintainer packages frequently change PSR-4 namespaces between majors; a copy-pasted vendor:publish --provider= string from an old blog post will silently fail.

Config caching bites. After changing anything in the published config or .env, run php artisan config:clear locally. In production, config:cache freezes config at deploy time — a config file published but not cached will behave differently between environments.

The docs are the source. There is no meaningful external documentation and no community to search. Budget an hour to read src/ end-to-end before adopting, and write down the internal API surface you actually depend on. That note is your upgrade guide.

Treat Facebook API version as your problem. Social APIs deprecate on a schedule. If the package hardcodes a Graph API version, check it as part of every upgrade and be ready to override it in config or patch it locally. Token expiry and refresh are almost certainly outside this package's scope — own that logic yourself.

Beware schema assumptions. The package will have opinions about user tables, columns, or model classes. If your users table is non-standard (UUIDs, multi-tenant, soft-deleted social links), you will either configure around it or write an adapter. Decide before, not during, the sprint.

Patch releases are not always cosmetic. "minor updates" in v5.3.1 plus a formatting fix means the diff is small but the changelog is not exhaustive. Diff the tag before upgrading in production:

git diff v5.3.0..v5.3.1 -- vendor/mortezamasumi/fb-user

(Or clone the repo and diff there.) Do not trust the changelog alone.

Debugging the helper. If OperatedBy output looks wrong after an upgrade, isolate it: instantiate the helper directly with a known user and dump the result, rather than debugging through a controller. Formatting helpers fail in ways that are invisible until rendered.

Extension points to check for, in order of usefulness: container bindings in the service provider (usually swappable via $this->app->bind() in your own provider), publishable config, publishable migrations, and any contracts under src/Contracts. If none exist beyond config, subclassing is your fallback — which couples you tightly, so prefer the wrapper approach.

Have an exit plan. This is a zero-star, single-maintainer dependency in the authentication/identity path. Write down the two files your app would need to change to remove it, and keep them free of package-specific types. That is the cheapest insurance you can buy here.

Do not put it in the critical auth path where a mature package fits. If the requirement grows to multi-provider login, MFA, or compliance, migrate to a widely adopted identity package or managed provider. This package is glue, not an identity platform.