Treblle Api Tools Laravel Laravel Package

Getting Started

Pull the package in and let Composer resolve the Laravel version constraint:

composer require treblle/treblle-api-tools-laravel

Before writing a single endpoint, spend ten minutes in vendor/treblle/treblle-api-tools-laravel/src. The package is small — the surface area is essentially a base API controller, a base form request, a response object/wrapper, and (depending on version) supporting exception and middleware classes. Read those files rather than relying on the README alone; the classes are the documentation, and you need to know the exact JSON envelope it emits before you commit your frontend to it.

If the package ships a config file, publish and skim it immediately:

php artisan vendor:publish --tag=treblle-tools-config

First use case: take one existing controller that returns ad-hoc arrays (the classic return response()->json(['data' => ..., 'success' => true])) and migrate it. Extend the package's ApiController, swap the Request for the package's ApiRequest, and return the package's response helper instead of hand-rolled arrays. One endpoint is enough to prove the envelope, the validation error shape, and the 404 shape all behave the way your consumers expect. Do not migrate the whole API before you've inspected those three payloads.

Implementation Patterns

Inherit the base controller, don't fight it. The main day-to-day value is a consistent response contract. Create your own App\Http\Controllers\Api\ApiController that extends the package controller so you have a single seam to override methods, add auth helpers, or change the envelope later:

abstract class ApiController extends \Treblle\Tools\Http\Controllers\ApiController
{
    // project-wide helpers live here, not in 40 controllers
}

Then every resource controller extends your class. This one indirection is what saves you when the package's response shape changes in a minor release.

Pair it with the package's request class for uniform 422s. The consistent-response promise is only half-kept if validation errors still leak Laravel's default {message, errors} format while success responses use yours. Subclass the package request (or use it directly) so failedValidation produces the same envelope as your 2xx responses. Consuming clients should never need two error parsers.

Normalise framework exceptions at the handler level, not per-controller. ModelNotFoundException, AuthenticationException, AuthorizationException, and ThrottleRequestsException all bypass your controller and get rendered by Laravel's exception handler. Register renderers in bootstrap/app.php (Laravel 11+) or app/Exceptions/Handler.php so they return the same envelope. Otherwise your API is consistent for 200s and 422s but wildly inconsistent for 404s, 401s, and 429s — exactly the responses clients hit in production.

Add a JSON-forcing middleware to API route groups. Browser and curl requests without Accept: application/json get HTML error pages. Group API routes with the middleware (or an equivalent of ForceJsonResponse) so the request class and exception handler make the right decisions:

Route::middleware(['api', ForceJsonResponse::class])->prefix('v1')->group(...);

Use it as the shape layer, with Laravel Resources underneath it. Don't rewrite your JsonResource classes — compose. Let API Resources do field selection and relationship inclusion, and let the package's response object handle the outer envelope (success, data, message, errors). This keeps the transformation logic idiomatic and the wire contract centralised.

Test the contract, not the implementation. In feature tests, assert on assertJsonStructure against the envelope and on exact status codes rather than assertExactJson of everything — the latter turns every harmless field addition into a failing test suite and discourages teams from adding fields.

Gotchas and Tips

The envelope is a public API; changes are breaking changes. Once mobile clients and third-party integrators pin to your success/data/errors shape, renaming a key is a coordinated release, not a refactor. Write the shape down in the README of your API before you ship the first endpoint, and version your routes (/v1) from day one. Retrofitting versioning is far more expensive than the five minutes it takes now.

Inheritance is the coupling risk. If you already have a base controller doing tenancy, auditing, or auth glue, you cannot extend the package's controller. Prefer composition: use the response classes and request class directly and keep your own base class. The tools are useful standalone; the inheritance is a convenience, not a requirement.

Validation errors won't convert without the right Accept header. This is the single most common "it works in Postman but returns HTML in the browser" bug. Verify with curl -H "Accept: application/json" and confirm both the middleware registration and the route group order. If you have a global middleware that strips headers or an aggressive proxy, that's your culprit.

Don't let APP_DEBUG=true reach production. Consistent error envelopes make it tempting to render exception messages into the payload. Any handler you register must gate on config('app.debug') — otherwise your uniform 500 response becomes a uniform stack-trace leak.

Maturity check before you depend on it. This is a low-star package with no visible dependents. That doesn't make it bad — it's a thin, readable wrapper — but treat it accordingly: pin the version in composer.json, review the source before upgrading minors, and be prepared to vendor or fork it if it goes unmaintained. The classes are simple enough that forking is a realistic escape hatch, which is your safety net.

Debugging checklist when a response looks wrong: php artisan route:list --path=api to confirm middleware attachment, php artisan config:clear after changing published config (cached config silently ignores edits), and a deliberate throw new ModelNotFoundException in a scratch endpoint to verify your handler registration actually fires. Stack traces in logs plus the JSON body in the response tell you whether the problem is the handler or the controller.

Extension points worth knowing: override the base controller methods in your own abstract class rather than editing vendor code; bind your own response implementation in a service provider if the container resolves it; and keep exception renderers in one dedicated file so the contract is reviewable in a single diff. Everything else in the package is thin enough that a local subclass beats a pull request upstream.