Sdk Laravel Package

Getting Started

1. Install the package and let Laravel auto-discover its service provider:

   composer require fopost/fopost-php
   

2. Publish any package config if the README provides a tag, then add credentials to .env:

   FOPOST_API_KEY=your-token
   FOPOST_BASE_URL=https://api.fopost.com
   

3. Start with the validate resource or the accounts resource to confirm credentials and list connected social accounts. This is the quickest smoke test before wiring anything into your app.
4. First practical use case: fetch an account, create an account group, upload media directly, then publish a simple post. From there, add platform-specific resources only as needed.
5. Look first at config/fopost.php, the service provider, and src/Resources (or equivalent) to understand naming conventions. The v0.3.0 release adds a very broad surface area, so avoid assuming every network behaves the same.

Implementation Patterns

• Inject the client, don’t instantiate it. Resolve the package client/facade through Laravel’s container in services, jobs, and controllers. This keeps tests simple and lets you swap config per tenant.
• Use resources as the unit of work. The package is organized around resources: accounts, inbox, ads, blogs, activity, knowledge, broadcasts, WhatsApp, Reddit, Google Business Profile, etc. Wrap each resource in a small application service rather than calling it from controllers directly.
• Queue slow or fan-out operations. Media uploads, ad catalog syncs, broadcast/drip creation, keyword planning, and multi-account metric reads should run in jobs. Use per-account jobs so one failing network does not block the rest.
• Treat account groups as tenant boundaries. For multi-tenant apps, store the Fopost account/group ID on your local model, then resolve credentials or account context before each call. Account groups are useful for grouping networks by brand or client.
• Handle webhooks with the built-in verifier. Route webhook endpoints to a thin controller, verify the signature against the raw request body, then dispatch an internal job. Persist the event ID for idempotency before processing.
• Use per-network extras deliberately. The v0.3.0 release adds many platform-specific surfaces — Meta messaging settings, Discord bot channels/messages/events/members, TikTok Spark ads, Reddit flairs/rules, Google Ads recommendations, WhatsApp Business connections. Keep platform-specific code behind adapters so core publishing logic stays clean.
• Model content workflows explicitly. Broadcasts and drip sequences, blog articles and approval, keyword planning, content decay, posting cadence, post timelines, and native posts are distinct resources. Use separate application services for “planning”, “approval”, and “publishing” rather than one giant content service.
• For ads, separate read models from write actions. Catalogs, reach/frequency, ad archive, recommendations, and optimization score are read-heavy. Cache them where appropriate; reserve synchronous calls for user-triggered actions.
• Test with Laravel’s HTTP fake or the package’s testing hooks. Assert the outgoing resource path and payload rather than mocking the package client itself. This catches API contract drift when upgrading.

Gotchas and Tips

• v0.3.0 is a very large release. There are no obvious breaking changes called out, but the surface area expands significantly across ads, inbox, blogs, messaging, and platform resources. Pin the version and review the changelog before upgrading in production.
• Upload size limits are platform-specific. The release adds upload size limits; check the limit before direct media upload and fail early with a useful validation message. Do not assume a single global max size.
• Direct media upload differs from URL-based publishing. Some networks require uploaded media IDs; others accept URLs. Normalize this in your own media service so callers do not need to know platform differences.
• Webhook verification must use the raw body. Do not verify against a re-encoded JSON payload. Also implement replay protection using event IDs and timestamps.
• IDs are often strings. Social platform IDs can exceed 32-bit integer ranges. Avoid casting account, post, comment, or ad IDs to int; keep them as strings in your database and DTOs.
• Account reconnect flags are actionable. When an account is flagged for reconnect or returns an auth error, mark it locally and pause publishing jobs for that account. Do not retry indefinitely.
• Per-network fields are nullable. A Meta messaging setting, Discord canPost flag, Reddit default target, or TikTok identity may be absent. Use nullable DTOs and guard against missing data rather than assuming a uniform shape.
• Rate limits and retries. Use exponential backoff for read operations. Be much more conservative with non-idempotent writes such as publishing posts, sending messages, or creating ads. Log request IDs where available.
• Config caching quirks. After changing FOPOST_* values, run php artisan config:clear. In Octane or long-running workers, resolve clients per request/tenant rather than caching credentials globally.
• Extension points. If a resource does not cover an endpoint yet, prefer a small custom wrapper or an HTTP macro over forking the package. Keep custom calls in one adapter so they are easy to replace when the package catches up.
• Debugging. Log the resource name, account ID, and request ID at minimum. For failed writes, log the response body but redact tokens and message contents.