Rest Bundle Laravel Package

Getting Started

Reality check first. innmind/rest-bundle is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/rest.php, no Illuminate\* dependency — and its underlying stack (innmind/http, innmind/rest-server) is built around immutable PSR-7-style value objects and callable handlers, which do not map onto Laravel's Request/Response or its controller lifecycle. composer require innmind/rest-bundle into a Laravel app will install code, then do nothing useful with it.

So the "getting started" for a Laravel developer is a read, not an install:

1. Where to look first. Clone the repo and read, in order:

   • Resources/config/services.xml (or .yml) — this is the entire surface of the bundle. It tells you exactly what the bundle does, which is: register a handful of services into a Symfony container.
   • DependencyInjection/ — the bundle extension. If it's legacy (getContainerExtension(), non-autowired), you'll immediately see the Symfony 3/4 vintage.
   • Then jump outward to innmind/rest-server and innmind/http — that's where the actual behaviour (negotiation, resource exposure, error mapping) lives.

2. First use case. Pick one endpoint you already have in Laravel (e.g. GET /api/products) and use the Innmind model as a reference architecture to sharpen your own controller/serializer/exception split. Write a one-page side-by-side before writing any code: their callable-per-verb + immutable response vs your controller method + JsonResponse.

3. Only if you truly want to run it. You need a separate Symfony 3.4/4.x app on PHP 7.x. That is not your Laravel project. The realistic deliverable for a Laravel dev is a port of the ideas, not a port of the code.

Implementation Patterns

The bundle itself is thin glue; the patterns you can actually lift into Laravel are three, and they translate cleanly:

• Resource-oriented routing → Route::apiResource(). Innmind maps HTTP verbs to callable handlers that each return a resource value. Laravel's analogue is Route::apiResource('products', ProductController::class) plus only()/except() to enforce the verb-per-action discipline. The useful signal from the bundle is opinion: don't let a single controller method branch on $request->method() — one verb, one handler.

• Content negotiation → build it, don't inherit it. Laravel does not negotiate Accept headers out of the box. Copy the Innmind pattern: a small MediaType value object resolved from the request before the handler runs, then a Responsable or a serializer interface that takes the negotiated type. In practice in Laravel:

  • Read Accept in a middleware('negotiate').
  • Store the resolved type on the request ($request->attributes->set('media_type', …)).
  • Feed it into a Transformer contract (toArray() / toJson() / toXml()). This is a ~40-line piece of code you own; the bundle's value is showing you the seam, not giving you the code.

• Standardized errors → a base exception + Handler::render. Innmind throws a domain exception that becomes a resource; Symfony's kernel exception listener renders it. In Laravel the same idea is:

  // app/Exceptions/ApiException.php
  abstract class ApiException extends \Exception {
      abstract public function status(): int;
      abstract public function payload(): array;
  }
  

  and an override of Handler::render() in bootstrap/app.php for ApiException that emits { error: { code, message, details } }. The bundle is a decent reminder that a consistent envelope matters more than the specific status codes.

• Extensible handlers → invokable single-action controllers or a Transformer contract. The Innmind handler is a callable composed by the server. Your Laravel equivalent is a single-action invokable controller (__invoke) plus a transformer. If you want serialization swap-in-points, that's a container binding (app(Transformer::class)), not a bundle.

• Workflow tip. Build one Laravel route that mimics a single Innmind endpoint end-to-end — negotiation → handler → transformer → error envelope — and compare line counts. That number is your build-vs-buy data point, and it's the only durable output of reading this repo.

Gotchas and Tips

• Framework mismatch is the whole story. Bundle inheritance and getContainerExtension() have no Laravel equivalent. Don't assume composer require will "just work"; it will resolve and then be inert. Don't add it to a composer.json you care about — zero dependents and an archived repo is a supply-chain liability with no offsetting benefit to a Laravel app.

• PSR-7 boundary. Innmind messages are immutable and PSR-7-shaped; Laravel is Illuminate\Http\Request/Response. Any bridge is code you write and own — there is no upstream to send a PR to. If you copy the pattern, copy the concept (immutable response value object → serialized output) not the types.

• Version decay. Expect the composer.json to pin PHP 7.x and Symfony 3.4/4.x APIs. It will not install on Laravel's modern PHP 8 baseline without a fork, and the transitive Innmind packages will have drifted independently. Treat "does it even install" as an unknown, not an assumption — a 1-hour composer create-project spike against your PHP version answers this and is worth doing once.

• Error semantics don't map 1:1. Innmind's model is functional (thrown exception → resource). Symfony's kernel.exception listener and Laravel's Handler both intercept exceptions, but the status code and body shape choices are opinionated in Innmind. Don't assume your 422 maps cleanly to theirs; read the exception classes before trusting status codes.

• Debugging. No issue tracker, no docs beyond the source. Use symfony/debug container dump (or just var_dump the resolved service IDs from Resources/config/services.xml) to understand what's registered. There is no event-dispatcher bridge, so don't look for one.

• Extension points. The service definitions are the only real extension surface. If you were forking (don't, unless you're standardising on the Innmind stack for some other reason), that XML/YAML is where you'd subclass and swap in your own transformer/handler. In Laravel, the equivalent extension point is a container binding plus middleware — use those idioms.

• What's worth stealing. Precisely two things: the content negotiation seam (negotiate media type before dispatch) and the error-as-resource envelope (one JSON shape for every failure). Both are ~40 lines in Laravel and worth writing. Everything else — DI wiring, routing primitives, bundle lifecycle — is Symfony-specific and better done in Laravel's own idioms.

• Ramp-up for a Laravel dev. Reading the bundle: an afternoon. Running it: days, mostly inside Innmind's functional model. Operating it: permanently yours, with no patch path after any PHP/Symfony bump. For a Laravel team the correct posture is reference read, then reimplement the two patterns above — API Platform (Symfony) and plain Laravel controllers plus league/fractal or spatie/laravel-fractal dominate on every axis.