Bresources Laravel Package

Getting Started

Install and confirm wiring

composer require behamin/bresources

Before writing any code, open the repository and read three things in this order:

1. composer.json — check extra.laravel.providers and extra.laravel.aliases to confirm auto-discovery, and note the require constraints (PHP/Laravel versions).
2. src/ — identify the actual classes behind the "basic" and "standard" formats. The package name advertises two response shapes; the class names, constructor signature, and any static helpers are the real documentation here. There are 6 stars and 0 dependents, so there is no ecosystem of examples to fall back on — the source is the spec.
3. README.md and any config/ directory — if a config file ships, publish it early:

php artisan vendor:publish --tag=bresources-config

First use case

The realistic day-one use is: take one existing JSON endpoint and route it through the package's standard envelope so clients see a consistent { data, message, status }-style payload instead of response()->json($model).

// app/Http/Controllers/Api/UserController.php
public function show(User $user)
{
    // Class name below is illustrative — confirm against src/ before adopting.
    return new \Behamin\BResources\Resources\StandardResource($user);
}

Then verify the contract immediately by hitting the route and inspecting the raw JSON:

curl -s localhost:8000/api/users/1 | jq

Check four things before going further: the top-level keys, where the payload sits, how HTTP status is set, and what an empty/null result looks like. Those four decisions determine whether the rest of your API layer can adopt the package cleanly.

Reality check before committing

Score 0.15, 6 stars, 0 dependents, last release 2025-01-09. This is a single-team utility package, not infrastructure. Pin the exact version ("behamin/bresources": "1.2.3" rather than ^1.0) and plan for the possibility that you fork it. That is not a reason to avoid it — a thin response-formatter is easy to replace — but it should shape how tightly you couple application code to it (see Implementation Patterns).

Implementation Patterns

Wrap the package behind one app-level class

The highest-value pattern for a low-adoption dependency: never let package classes appear in more than one or two places. Create an app-level ApiResponse service or a base ApiController that delegates to bresources, and have every controller call that.

abstract class ApiController extends Controller
{
    protected function ok($data, string $message = 'OK')
    {
        return new StandardResource($data, $message); // adapt to real signature
    }

    protected function fail(string $message, int $status = 400, $errors = null)
    {
        return /* package error shape */;
    }
}

If the package is abandoned or a fork is needed, you rewrite one class instead of 40 controllers.

Centralize error and validation shape

A response envelope is only as good as its worst endpoint. The data/message/status contract breaks the moment Laravel's default exception handler returns {"message": "...", "errors": {...}} for a 422. Handle it in one place:

// bootstrap/app.php (Laravel 11) or app/Exceptions/Handler.php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (ValidationException $e, $request) {
        if ($request->is('api/*')) {
            return ApiResponse::fail('Validation failed', 422, $e->errors());
        }
    });
    $exceptions->render(function (AuthenticationException $e, $request) {
        return $request->is('api/*')
            ? ApiResponse::fail('Unauthenticated', 401)
            : null;
    });
})

Do the same for ModelNotFoundException and AuthorizationException. Consumers of a "standard format" package always notice the endpoints that don't conform, not the ones that do.

Transform before formatting

Treat the package as the final serializer, not a model-to-JSON converter. Map Eloquent models to plain arrays or DTOs first, then wrap:

$payload = $user->only(['id', 'name', 'email'])
    + ['roles' => $user->roles->pluck('name')];

return $this->ok($payload);

This keeps the package out of your domain concerns, avoids accidental exposure of model attributes, and means the envelope is tested independently of the data mapping.

Collections and pagination

The "basic" vs "standard" distinction most likely shows up here. Decide once whether paginated responses put meta inside data or beside it, write it down, and add a failing test that locks it in:

$response->assertJsonStructure([
    'data' => [['id', 'name']],
    'meta' => ['current_page', 'per_page', 'total'],
    'message',
]);

Run one paginated and one non-paginated endpoint through the package side by side before rolling it out broadly — that is where envelope packages most often surprise you.

Adopt incrementally per API version

If you version your API, apply the envelope to new versions (/api/v2/*) and leave v1 alone. Retrofitting an envelope onto a live v1 is a breaking change for every mobile client; a version boundary makes the migration a deliberate client-side decision.

Test the contract, not the package

Write assertions against the JSON structure, never against package internals. That way a future swap to a fork, or to Laravel's own JsonResource with a custom with(), is a non-event.

Gotchas and Tips

Confirm the API before you write code against it. With 0 dependents there are no usage examples in the wild. Read the constructors and any facade/service-provider bindings in src/; the README on a 6-star package is frequently out of date relative to the last release (2025-01-09). If the README and source disagree, the source wins.

Pin the version. Use an exact constraint in composer.json. A patch release on an unmaintained package can change the envelope; you want that to be a deliberate composer update.

Status codes are commonly decoupled from payloads. Many envelope packages return HTTP 200 with the status inside the body. If your clients, gateways, or monitoring expect 201/204/401 to be real HTTP codes, you will need:

return $this->ok($user)->response()->setStatusCode(201);

Check this explicitly for create and delete endpoints — it is the single most common mismatch when adopting a response-format package.

Watch for double-wrapping. Returning the package resource from inside another resource, or applying response()->json() on top of it, produces {"data": {"data": ...}}. Debug payloads with dd($resource->resolve()) or ->toArray(request()) to see the array before JSON encoding rather than guessing from the HTTP response.

Null vs empty array vs empty object. data: null, data: [], and data: {} are different types to strongly-typed mobile clients (Kotlin/Swift/TypeScript). Test the empty-result path on every list and detail endpoint — it is the classic post-launch crash.

Config caching bites after publishing. After php artisan vendor:publish, remember php artisan config:cache in deploy and config:clear locally; a stale cached config is the usual reason a published file appears to have no effect.

Exception rendering bypasses middleware. Responses produced in the exception handler do not pass through response middleware — CORS headers, request-id injection, and logging decorators can silently disappear on error paths. Verify a 401 and a 422 from a browser/curl with the Origin header set.

Validation errors come from Laravel, not the package. FormRequest::failedValidation and the default ValidationException renderer produce Laravel's shape. Override deliberately (see Implementation Patterns) rather than discovering the mismatch in client integration.

Date and cast serialization. Confirm how Carbon instances and $casts (especially datetime, enums, and Arrayable casts) land in the envelope. If the package manipulates the array, custom serializeDate() on your models may be overridden.

Extend, don't edit. For any behavior change — extra meta keys, different error shape — subclass the package's resource classes or wrap them in your own. Never patch vendor/. If you need a fork, fork to a private VCS repository and swap the composer constraint; a formatter is small enough that this is a half-day job, which is exactly why the low adoption numbers are tolerable here.

Debugging checklist when the output looks wrong: confirm the service provider registered (php artisan about), confirm the config is published and not cached, dd() the resource's resolved array, then check whether a middleware or exception path is producing the response instead of your controller. In that order — it distinguishes "package misconfigured" from "a different code path answered the request."