Evocms Extras Laravel Package

Getting Started

Start by locating the module’s install/status endpoints and any client code that currently reads errors.message. In v1.6.2, the response contract is now:

• Success: {"success": true, "data": ...}
• Refusal: a top-level message sentence plus errors as an empty object ({}), not errors.message
• Failed install: the human-readable install notes and Composer output are returned under data, alongside the refusal message

The first practical use case is the install flow: call the module’s install endpoint, branch on the envelope, show message on refusal, and render data as install diagnostics when the install fails.

Minimal integration checklist:

1. Update any parser that reads errors.message to read top-level message.
2. Read successful payloads from data.
3. Read failed-install diagnostics from data, not from the error object.
4. Add a contract test for the success envelope and the refusal envelope.
5. Check for any global Laravel response wrapper/middleware that might double-wrap the module’s response.

Implementation Patterns

Treat the module as an API client boundary and centralize envelope handling in one service/class rather than scattering json() calls through controllers and Livewire components.

Typical success handling:

$response = Http::post($moduleUrl.'/install', $payload);

$body = $response->json();

if (($body['success'] ?? false) === true) {
    return $body['data'];
}

Typical refusal handling:

$message = $body['message'] ?? 'The operation could not be completed.';
$errors = $body['errors'] ?? [];

For failed installs, keep the response data for diagnostics:

if (($body['success'] ?? false) !== true) {
    return [
        'message' => $body['message'] ?? 'Install failed.',
        'details' => $body['data'] ?? null,
    ];
}

In a Blade/Livewire UI, show message as the primary sentence and put data behind a details/expandable panel. Composer output can be long, so escape it and render it in a <pre> block rather than injecting it as HTML.

For transitional deployments, use a small normalizer:

$message = $body['message']
    ?? data_get($body, 'errors.message');

This lets older and newer module responses coexist briefly, but remove the fallback once all environments run v1.6.2 or later.

Testing pattern:

$response->assertJson([
    'success' => true,
]);

$response->assertJsonPath('data.installed', true);

$response->assertJsonPath('errors', []);
$response->assertJsonMissingPath('errors.message');

Gotchas and Tips

• Breaking change: errors.message is no longer the error sentence. Use top-level message. Searching for errors.message is the fastest way to find affected clients.
• errors is now an empty object on refusal. Do not treat errors as the message container, and do not assume it contains field-level validation details.
• Failed installs still carry useful data. The install notes and Composer output are under data. Dropping data on failure makes debugging installs much harder.
• Do not double-wrap. If the host application has a global API response wrapper, verify it does not wrap the module envelope again into { success, data: { success, data } }.
• Check the envelope, not only the HTTP status. If both successes and refusals can return a 200 response, branch on success/message rather than assuming 4xx/5xx for all failures.
• Sanitize Composer output. It can be large and may contain paths or environment-specific details. Escape it in the UI and avoid exposing it publicly.
• Centralize parsing. Put envelope handling in one service or response DTO so future response shape changes are a one-file update.
• Extension point: if you currently customize the module’s install failure display, move that logic to consume data rather than reconstructing details from Composer output yourself.