Fb Essentials Laravel Package

Getting Started

This release (v5.5.0) is a compatibility-only release: it adds Laravel 13 support. There are no new APIs, config keys, or behavioural changes, so anything you already have working on Laravel 11/12 should carry over unchanged.

Minimal path to first use:

1. composer require mortezamasumi/fb-essentials — then confirm the resolved version is ^5.5 if you are on Laravel 13. Earlier 5.x tags will not satisfy Laravel 13's framework constraints.
2. Publish the config: php artisan vendor:publish --tag=fb-essentials (verify the exact tag in the README; the config lands at config/fb-essentials.php).
3. Populate credentials in .env — at minimum the Facebook app ID/secret and whichever access token the feature you need requires. Keep these out of config/fb-essentials.php itself and reference them via env() only inside the config file.
4. php artisan config:clear after editing, then smoke-test with php artisan tinker against a single read call before wiring anything into application code.

Where to look first:

• The README's quickstart block — the package exposes a small surface area and the README is the authoritative list of entry points.
• The published config file — it is the clearest map of what the package actually supports (app credentials, API version pin, token sources, HTTP options).
• vendor/mortezamasumi/fb-essentials/src/ — the service provider bindings tell you what is container-resolvable and how to swap implementations.

First use case: a single server-side call (fetch a page's feed, or post to a page) executed from a queued job, not from a controller. That gets you a working integration plus the async boundary you will want anyway.

Implementation Patterns

Resolve from the container, never new. Inject the package's client/service class into constructors or resolve via the facade. This is what makes it fakeable in tests and swappable later.

Wrap it in your own thin service. Do not let the package's API leak across your codebase. Define an interface in your domain (e.g. FacebookPublisher) with a single implementation that delegates to the package. When the package lags a Laravel release — which is exactly the risk this v5.5.0 release exists to address — you only have one class to patch.

Queue everything that touches the network. Facebook's Graph API is rate-limited and occasionally slow. Wrap calls in a job with $tries, $backoff, and $timeout set explicitly, and put it on a dedicated queue so a stalled API call cannot starve your default worker pool.

Drive configuration per-tenant, not per-app. If you post to multiple pages or apps, do not rely on the global config alone. Pass credentials/identifiers into your service layer per call (or resolve a named config profile) so a single queue worker can serve multiple accounts.

Test with Http::fake(). Laravel's HTTP client fakes are the cheapest way to cover this integration. Record one real response per endpoint into a fixture, then assert on your own service's return types rather than on the package's internals. Add a single opt-in integration test (gated by an env flag) that hits the real API to catch drift.

Blade/middleware integration is a last resort. If the package offers view helpers for embedding widgets or meta tags, prefer generating markup in your own component so output stays under your control and CSP policy.

Version-pin the framework contract. In composer.json, constrain the package to ^5.5 and let Composer's platform check do the rest. Do not use * — this package has shipped multiple majors, and a silent major jump is the most likely way to break a working integration.

Gotchas and Tips

A minor bump that adds framework support is not always a free upgrade. Adding Laravel 13 usually means the package's illuminate/* constraint widened. If your lockfile also pins Laravel 12, composer update may resolve an older package version than you expect. Run composer why-not mortezamasumi/fb-essentials 5.5.0 when resolution looks wrong.

Check the constraint direction. Confirm from composer.json whether v5.5.0 supports 13 alongside 11/12, or requires it. If the latter, you cannot stage the package upgrade ahead of the framework upgrade.

Config caching silently drops env() calls. Any env() outside config/ returns null under config:cache. This is the number one cause of "it worked in dev" for packages configured this way.

Access tokens expire. Short-lived user tokens last about an hour; page tokens derived from them are longer-lived but still expire. Store tokens with their expiry, refresh proactively, and fail with a loud, typed exception rather than surfacing Facebook's opaque error payload to users.

Pin the Graph API version explicitly. Facebook deprecates Graph versions on a rolling schedule that has nothing to do with this package's release cadence. Keep the version string in your config so a deprecation is a config change, not a package upgrade.

Log the raw error payload once. Facebook returns HTTP 200 with an error body in some cases. Assert on the body, not just the status code, and log the full response at debug level — the fbtrace_id it contains is what Facebook support will ask for.

Timeouts and retries. Set an explicit HTTP timeout (5–10s) in the package config; the default may be unbounded. Retry on 5xx and on rate-limit codes only — retrying on validation errors just burns quota.

Verify the service provider is auto-discovered. If you have extra.laravel.dont-discover set in your root composer.json, the package's provider and facade will not register. This bites most often in legacy apps that disabled discovery wholesale.

No changelog entry means no migration work. v5.4.1 → v5.5.0 has no deprecations or removals to action. Treat it as a routine dependency bump and let your existing integration test be the acceptance gate.