Php Api Client Laravel Package

Technical Evaluation

Architecture fit. mosparo/php-api-client is a thin, first-party HTTP client that wraps the mosparo REST API. It has no framework coupling — PSR-4 autoloading, Composer distribution, and a Guzzle transport that Laravel already ships with. The public surface is small and focused: verifySubmission, storeMetadata, getStatisticByDate, and a rule-package sub-API (hash-index streaming, paginated rules/items, full import, batch update). For a TPM this is a low-blast-radius dependency: it introduces an outbound HTTP service call and a few value objects (VerificationResult, StatisticResult, RulePackage*Result) rather than invasive framework hooks or global state.

Integration feasibility. Very high. Installation is composer require mosparo/php-api-client, and a working verification flow is roughly five lines: instantiate Client($url, $publicKey, $privateKey, $guzzleArgs), read the two _mosparo_* tokens from the request, call verifySubmission($_POST, $submitToken, $validationToken), and branch on isSubmittable(). The README documents every method with signatures, return types, and exception contracts — unusually complete for a package at this maturity. There is a companion frontend script (mosparo-frontend.js) that must be loaded in the form to generate the tokens, so end-to-end integration is a two-sided change (browser + server), not a backend-only one.

Technical risk. The headline risk is adoption, not engineering. Five stars and zero dependents means the library has essentially no independent production validation; we would be an early adopter. Mitigating factors: it is maintained under the mosparo org itself (first-party client for its own protocol), the license is MIT, and the 2.0 release notes show deliberate versioning — PHP minimum raised to 8.1, methods adjusted for mosparo 1.5+, with the verification path explicitly kept backward compatible with pre-1.5 servers. Secondary risks: the verification call is synchronous, adding a network round-trip to every form submission; the client is a stateless wrapper with no retry, circuit-breaking, or caching built in; and the release date metadata (2026-08-05) is anomalous and worth confirming against Packagist before pinning.

Key questions.

• Do we self-host mosparo or use a managed instance, and who owns its availability SLO?
• What is the required behavior on verification failure — fail-open (accept submission, log) or fail-closed (reject)? This is a product decision, not a library one, and the package does not prescribe it.
• Where do privateKey values live (Secrets Manager / Vault / .env) and how are they rotated per environment?
• Is storeMetadata and the rule-package API actually in scope, or is this purely spam verification? The rule-package surface is significantly more complex than the verify path.
• What is the support posture if the upstream project stalls — can we vendor or fork under MIT?

Integration Approach

Stack fit. Laravel 9+ on PHP 8.1+ is a clean match; Guzzle is already a transitive dependency, so the composer footprint is negligible. The client has no service provider, config publishing, or facade — which is fine for a library but means we own the Laravel glue. The idiomatic wrapper is a small internal package or app/Support/Mosparo module containing: a config/mosparo.php (url, public key, private key, timeout, fail policy), a MosparoServiceProvider binding Client as a singleton with Guzzle options injected, an optional Mosparo facade, and a custom validation rule (new MosparoVerified($submitToken, $validationToken)) so controllers stay thin. Map VerificationResult::isSubmittable() to a domain-level outcome and translate Mosparo\ApiClient\Exception into a policy decision rather than a 500.

Migration path. If replacing reCAPTCHA/hCaptcha, the shape is analogous but the ordering differs: mosparo issues tokens from the frontend before submission and validates server-side afterward. Steps: (1) stand up the mosparo instance and create a project to obtain public/private keys; (2) add the <div id="mosparo-box"> and frontend script to each protected form; (3) add the composer dependency; (4) build the Laravel wrapper above; (5) route submissions through verifySubmission, stripping mosparo-unprocessed fields (hidden, checkbox, radio) from the payload as the docs require; (6) run both systems in parallel behind a feature flag for a soak period; (7) cut over and remove the legacy captcha. Because verification remains compatible with mosparo <1.5, the client can be deployed before the server is upgraded, which decouples the rollout.

Compatibility. Client 2.0+ requires PHP 8.1 and pairs with mosparo 1.5+; the verification method alone still works against older servers. Rule-package and statistics endpoints are version-sensitive to server capability (e.g., startDate requires mosparo 1.1), so guard optional features behind a server-version check or feature flag. Pin the client with a caret constraint and verify the lockfile resolves against Packagist, given the unusual release timestamp in the metadata.

Sequencing. Infrastructure (mosparo instance + keys) → configuration and secrets → Laravel binding and validation rule → single form as a canary → telemetry → remaining forms → statistics/rule-package automation last, only if a concrete need exists. Do not attempt the rule-package batch/hash-index flows in the first release; they are a separate, higher-complexity workstream.

Operational Impact

Maintenance. Low ongoing code burden — the wrapper we write is the bulk of the maintained surface, and the library itself changes infrequently. The real maintenance obligation is tracking the mosparo server version, since client/server compatibility is versioned even if the verify call is forgiving. Commit to a quarterly dependency review and subscribe to mosparo releases. MIT license and first-party ownership mean forking or vendoring is a viable escape hatch if the project stalls.

Support. The support model is community-driven and small (5 stars, zero dependents). Internal runbooks must therefore be ours: how to rotate keys, how to diagnose verification failures, how to interpret getIssues() and hasIssues(), and how to distinguish "spam" from "verification infrastructure down." Budget for one engineer to become the internal owner.

Scaling. The client scales horizontally without state — one HTTP request per submission to the mosparo instance, which becomes the scaling bottleneck and must be sized and monitored independently. Two concrete mitigations: set aggressive, explicit Guzzle timeouts and connection reuse; and add a resilience layer (retry with jitter on transient errors, circuit breaker on sustained failures) at the wrapper level, since the library provides none. At high form volumes, the extra round-trip per submission is a measurable latency line item and should be benchmarked before broad rollout.

Failure modes. (1) Network timeout / mosparo unavailable — the exception path must map to an explicit, documented policy; defaulting to fail-open with alerting is usually right for lead-gen forms, fail-closed for auth or payment flows. (2) Missing or malformed tokens — the client throws; the validation rule should surface this as a user-facing form error, not a 500. (3) Invalid private key / misconfigured project — silently rejects all traffic; needs a startup health check or synthetic probe. (4) Server version drift — new client methods against an old server produce opaque failures; pin both sides together. (5) Rule-package partial failure — RulePackageBatchResult::getErrors() requires per-task success handling, so any automation built on it must reconcile partial writes. Instrument all five with counters and alerts.

Ramp-up. Days, not weeks. The verification path is documented end-to-end in the README with copy-paste examples, and the return-object API (isSubmittable, isValid, getVerifiedFields, hasIssues, getIssues) is self-explanatory. The main learning curve is not the library but the mosparo operational model — project/key management, frontend token lifecycle, and the fail-open/fail-closed policy decision. The rule-package and statistics surfaces are materially more complex and should be scoped to a separate, later increment with their own design review.