Laravel Laravel Package

Getting Started

Fopost Laravel is a thin facade over fopost/sdk — almost everything you'll do runs through the Fopost facade rather than services you resolve by hand. Minimum viable setup:

1. composer require fopost/fopost-laravel — v0.2.0 requires fopost/sdk ^0.3. If you were pinned to 0.2.x of the SDK from an earlier install, run composer update fopost/sdk.
2. Publish the config if the package ships one (php artisan vendor:publish --tag=fopost-config) and set your API token in .env (typically FOPOST_API_KEY). Check config/fopost.php for the exact key name in this release.
3. Look at the facade docblock first — Fopost::media(), Fopost::activity(), Fopost::googleBusiness(), Fopost::whatsapp() are the new v0.2.0 entry points, and the class-level docblock is the fastest source of truth for the full resource list.

First use case worth wiring: grab the activity feed, since it's read-only, cheap, and confirms auth/endpoint wiring before you touch anything that posts:

use Fopost\Laravel\Facades\Fopost;

$activity = Fopost::activity()->list(); // verify token + connectivity

Once that returns, move on to Fopost::googleBusiness() or Fopost::whatsapp() for the read paths before attempting writes.

Implementation Patterns

Facade + resource chaining. The dominant pattern is Fopost::{resource}()->{action}(...). Each facade method returns a resource object from the underlying SDK; chain a terminal call on it. Keep a thin service class in your app (e.g. App\Services\SocialPublisher) that wraps the facade so controllers and jobs never depend on Fopost directly — this makes it trivial to fake in tests and to swap SDK versions.

Direct media uploads. The new media() hint is explicitly for direct uploads. Typical flow: upload the asset through Fopost::media() to get back an ID/reference, then pass that reference into the post/broadcast payload. Don't inline base64 or public URLs into the create call — use the media handle so the platform owns the asset lifecycle.

Scheduled broadcasts / drip sequences. broadcasts (v0.2.0) are a natural fit for queued jobs. Wrap creation in a queued job (ShouldQueue) so retries and backoff are handled by Laravel, not by you re-calling the SDK. Store the returned broadcast ID in your own table so you have a local correlation key for webhooks and cleanup.

Inbound blog articles. PR #12 added receiving published blog articles — this is almost certainly an inbound webhook or a pull endpoint. If it's a webhook, put it behind VerifyCsrfToken's except list, validate the shared secret, and dispatch a job rather than processing in the request. If it's a pull, schedule it with ->withoutOverlapping().

Meta Ads depth. The "Meta Ads depth" work means ad-specific resources exist beyond generic posts. Keep ad spend / campaign calls in a separate service from organic posting — they have different rate limits and different failure modes.

Multi-tenant routing. If you serve multiple Fopost accounts, resolve the token per-tenant and bind it before the facade call, either via a scoped config repository or a Config::set() in a middleware. Never let the token leak from a long-running queue worker into the next job.

Gotchas and Tips

• SDK version drift is the biggest one. v0.2.0 jumped to fopost/sdk ^0.3 (PR #14) after a stay on ^0.2 (PR #8). Laravel's lockfile will hold you on the old SDK if you only bump the package — run composer update fopost/sdk fopost/fopost-laravel together, and check composer why fopost/sdk if the constraint won't resolve.
• Camel-cased facade methods. googleBusiness() is camelCase, not google_business(). Magic-method proxies on facades are case-sensitive; a missing method throws a BadMethodCallException rather than returning null, which is actually the good outcome — but it fails at runtime, not at IDE time. Use the facade docblock or an IDE helper.
• Don't type-hint the facade. Fopost is a Laravel facade; injecting it via constructor works but couples you to the alias. Prefer @method annotations or your own wrapper interface.
• No parent-SDK constant assumptions. PR #1 replaced a hardcoded /api/v1 with the parent's path constant — a hint that base URL paths can move between SDK minors. If you've hardcoded endpoint URLs anywhere (webhook receivers, CORS, proxies), read them off the SDK/config instead.
• Rate limiting is not yours to manage. The SDK doesn't queue. Wrap writes in RateLimited jobs or Bus::batch() so a retry storm doesn't turn into a 429 ban on your token.
• Webhook verification. Treat any inbound Fopost payload (blog articles, broadcast status) as untrusted until you verify the signature. Log the raw body on failure — signature mismatches are nearly always a JSON re-encoding issue upstream of the check.
• Testing. Because the facade resolves through the service container, Fopost::shouldReceive('media') works from feature tests, but it's brittle against SDK churn. Prefer Http::fake() at the SDK boundary, or fake your own SocialPublisher service — the latter survives SDK upgrades.
• Release/tag workflow. The tag-triggered release workflow (PR #4) means this package follows semver-ish tagging. Pin with ~0.2.0 rather than ^0.2 if you're relying on specific facade methods added mid-release — those methods landed in a single minor bump and could move again.
• CI note. PR #2 dropped an "untestable" workflow because it couldn't resolve the parent SDK from GitHub. If you run CI in a sandboxed network, your composer install will hit the same wall — mirror the SDK in your private registry (Satis/Private Packagist) rather than pulling from github.com at build time.