Sdk Laravel Package

Technical Evaluation

Scope of the release. v0.3.0 is not a maintenance release; it is a step-change in surface area. The changelog lists ~30 merged PRs expanding the SDK from a core posting client into a broad multi-platform social/ads/blog management client. New domains include: inbox actions and comment moderation, Telegram/Slack/Discord bots, Meta messaging + webhook subscriptions, WhatsApp Business, Google Business Profile, Google Ads (recommendations, optimization score), TikTok ads (identities, Spark ads, conversions, ad comments), a second ad network, Snapchat in Platforms::ALL, Reddit (subreddits, rules, flairs, voting), broadcasts and drip sequences, a knowledge resource, an activity/security audit log, blog articles/products on connected sites, and upload size limits. It also introduces a webhook verifier — the one security-critical component in the list.

Architecture fit. The package follows the conventional Laravel integration shape implied by the release (resources/models mirroring API nouns, a Platforms enum-like registry, per-network account extras and metrics). For a Laravel codebase, that is a low-friction fit: service provider + published config + facade + resource objects is the idiom our engineers already know. The risk is not fit, it is breadth: this is effectively a client for a dozen third-party APIs, each with its own auth model, rate limits, pagination, and deprecation cadence. We are adopting a wrapper over a vendor aggregator (Fopost), which means our integration risk is two-layered — the package's own 0.x churn plus every upstream platform change it tracks.

Integration feasibility. Mechanically straightforward: composer require, publish config, supply an API token, call resources. The unknowns are environmental, not conceptual — Laravel version support matrix, PHP constraint, HTTP client dependency (Guzzle/Saloon/raw), and whether uploads stream or buffer. Given the "direct media upload" and "upload size limits" work, we must confirm memory behaviour before routing large video through web requests.

Technical risk (ranked).

1. 0.x semver with a very high merge velocity. 30 PRs in one minor bump, no BREAKING CHANGE callouts and no deprecation section. Under semver, 0.x permits breaking changes on minor bumps — so ^0.3 is not a safe constraint.
2. Bus factor of one. Every PR is by the same author. No co-maintainers, no reviewer names in the changelog.
3. Webhook verifier is security-critical and newly introduced. It needs signature comparison timing-safety, replay protection, and tolerance-window handling verified before we accept inbound traffic.
4. Upstream volatility. Ads surfaces (Meta, Google, TikTok) and messaging APIs change frequently; a thin wrapper will lag. Silent breakage is more likely than loud failure if responses are mapped to dynamic properties.
5. Token/account lifecycle. "Account reconnect flag" and "webhook subscription" imply OAuth refresh and revocation handling. If the package does not surface re-auth signals reliably, we get silent posting failures.
6. Unverifiable quality signals. No test coverage, CI status, static analysis level, or license is visible in the notes.

Key questions for the maintainer / spike.

• Exact composer.json constraints: PHP version, illuminate/support range (Laravel 10/11/12?), HTTP client and its major version.
• Is there a documented upgrade guide for 0.2 → 0.3, and is 0.4 expected to break 0.3?
• Test suite size, CI matrix, and whether tests hit live APIs or mocks.
• Does the webhook verifier use hash_equals, and is there a timestamp/replay guard?
• Are 429/5xx handled with retry/backoff, or surfaced raw to the caller?
• Are resources immutable DTOs or mutable models with lazy-loaded relations (N+1 risk on metrics/inbox listing)?
• Is a Fopost account and hosted API mandatory, or can it point at first-party platform APIs directly? (Vendor lock-in and data-residency implications.)
• License and support commitment.

Integration Approach

Stack fit. Presumed fit for a modern Laravel app (PHP 8.1+, Laravel 10/11). Verify illuminate/support and Guzzle constraints against our lockfile before committing — dependency conflicts here are the most common cause of a multi-day stall on packages like this.

Migration path. Greenfield — no prior assessment and no incumbent SDK, so there is nothing to migrate off. The relevant "migration" is the future 0.3 → 0.4 hop. Treat every 0.x minor as a migration event and budget for it.

Compatibility posture.

• Pin exactly: "fopost/fopost-php": "0.3.0", not ^0.3. Bump deliberately, in a branch, with the changelog read first.
• Isolate behind an internal SocialGateway interface in our domain layer; the package should be referenced in exactly one adapter namespace. This costs ~1 day and buys us the option to swap or fork.
• Do not let package models leak into controllers, jobs, or API resources. Map to our own DTOs at the boundary.

Sequencing (recommended, 4 phases).

1. Foundations (week 1): install, config, auth, a single read-only call (accounts list, per-network metrics). Confirm auth, pagination, and error shape. No writes.
2. One channel end-to-end (week 2–3): pick the highest-value single network (likely Meta/Facebook or Telegram) and go publish → read back → inbox read. Validate rate-limit behaviour under a small load test.
3. Inbound (week 4): webhook verifier + subscription management, behind a feature flag, with signature tests and replay tests written by us (do not rely on the package's own tests for this).
4. Ads, blogs, and long-tail platforms: defer. Ads (Meta/Google/TikTok), blogs, Reddit, and Google Business are large, low-urgency surfaces — adopting them now imports maintenance we cannot yet support.

Explicitly defer broadcasts/drip sequences and the knowledge resource until a product requirement exists; they add surface without a current consumer.

Operational Impact

Maintenance. Expect a steady upgrade tax. With ~30 PRs per minor version and a single maintainer, 0.3.x will drift under us. Assign a named owner and a recurring monthly "SDK currency" task. Budget roughly 1–2 engineer-days per minor bump for changelog review, regression tests, and re-pinning.

Support. Assume community-only, best-effort. There is no evidence of an SLA, LTS branch, or security disclosure policy. For anything touching webhooks or tokens, we must be prepared to patch ourselves — confirm we can fork under the license before adopting.

Scaling.

• Throughput is bounded by upstream platform rate limits, not by the package. Inbox polling, metrics reads, and ad insights are the heavy calls; design them as queued jobs with per-platform concurrency caps from day one.
• Media uploads must go through a queue with streamed/chunked transfer; do not proxy large files through PHP-FPM request workers. The new upload-size-limit feature suggests the package knows about this — verify it enforces limits client-side rather than relying on the remote API to reject.
• Inbound webhooks need a horizontally scalable, idempotent consumer; assume at-least-once delivery.

Failure modes to instrument.

• Silent platform breakage — schema drift in third-party responses mapped onto models. Mitigate with response validation at the adapter boundary and alerting on unmapped/empty payloads.
• Token expiry / revoked connections — surface the account reconnect flag into an operator queue; do not let it fail quietly.
• 429 and 5xx — verify retry/backoff exists; if not, wrap in our own middleware.
• Webhook verification failures and replays — log and alert; a spike here is either an attack or a secret rotation.
• Memory exhaustion on media paths.
• 0.x breaking change landing via an unattended composer update — prevented by exact pinning plus a CI lockfile check.

Ramp-up. Low-to-moderate for a Laravel engineer on the mechanics (consistent resource pattern, familiar idioms): ~2–3 days to first productive call. High for domain competence: 12+ platform quirks, ads hierarchies, and messaging semantics cannot be absorbed at once. Plan for one engineer to own one platform deeply rather than the team skimming all of them, and write internal docs for the adapter boundary as the durable artifact — not the SDK itself.