Evocms Extras Laravel Package

Product Decisions This Supports

• API contract standardization: v1.6.2 aligns endpoint responses with the qmedia-by family envelope ({"success": true, "data": ...} on success, message + empty errors object on refusal). This supports a decision to standardize response shape across all first-party modules rather than maintaining per-module variants — a real reduction in client-side branching.
• Breaking-change rollout planning: The relocation of failure text from errors.message to top-level message is a breaking change for any consumer parsing the old path. This forces a concrete decision: version the API (v2 endpoints or a compatibility shim) versus coordinating a synchronized frontend/mobile release. PM input is needed on which consumer cohorts can absorb the change and on the deprecation window.
• Diagnostics/observability roadmap: Failed installs now surface installation notes and raw Composer output under data, rendered beneath the human-readable sentence. This improves support triage and self-service debugging — a candidate for a first-class "install diagnostics" capability rather than an incidental payload.
• Build vs. buy / ecosystem reuse: Matching the qmedia-by conventions is evidence the package is converging on shared infrastructure. That argues for treating it as part of a suite (reuse the shared response helper, shared error taxonomy) instead of a bespoke integration.
• Use cases unlocked: programmatic module installation and health checks from admin UIs, CLIs, or CI pipelines, where machine-readable success plus structured data matters more than prose.

When to Consider This Package

Adopt when:

• You are already in, or standardizing on, the qmedia-by package family and want one response envelope across modules — the consistency benefit compounds with each additional module.
• Your consumers are code you control (admin SPA, internal tooling, CLI) and can be updated in lockstep with the v1.6.2 response change.
• You need programmatic install/diagnostic flows where Composer output and install notes must be captured and displayed rather than lost in logs.
• You want machine-checkable outcomes (success boolean) instead of string-matching error text.

Look elsewhere or defer when:

• You have third-party or hard-to-update clients pinned to errors.message. Budget for a compatibility layer, dual-field emission, or a major version before upgrading — do not ship this as a patch bump to external consumers.
• Any consumer distinguishes error types by inspecting errors. It is now an empty object on refusals; typed error codes are not in this contract.
• You require stable, versioned API schemas with deprecation guarantees; this release changes shape in a point release.
• You are outside the qmedia-by ecosystem and would be adopting a convention you do not otherwise share.
• You need rich validation detail per field on failures — the empty errors object removes that affordance.

How to Pitch It (Stakeholders)

For executives: This release brings our module's API in line with the rest of the qmedia-by suite — one predictable response format everywhere. That lowers integration and support cost, and failed installs are now self-diagnosing: the module shows the reason plus the underlying Composer output, so support tickets get resolved without engineering escalation. The tradeoff is a deliberate breaking change to the error payload; it is small and contained, but it must be sequenced, not shipped silently.

For engineering: v1.6.2 changes the response envelope. Success is {"success": true, "data": ...}. Refusals put the human sentence in message, with errors as an empty object — previously the sentence lived at errors.message. Failed installs carry install notes and Composer output under data, which the module renders under the message. Action items: audit every consumer for errors.message reads; add a compatibility shim or bump the API version; add regression tests asserting the new envelope; confirm no caller depends on per-field validation detail in errors. Treat this as a minor-version break in our own release notes even though upstream shipped it as a patch.