Rest Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. It exists to layer extra behaviour onto friendsofsymfony/rest-bundle (FOSRestBundle), which itself depends on Symfony's HttpKernel, routing annotations, and typically JMSSerializer. If your day job is Laravel, you cannot use this package directly — the only realistic scenario is that you've been dropped into a Symfony codebase (or a legacy one) that already standardises on FOSRest, and this bundle is proposed as an add-on. Treat it as a Symfony-side dependency with a Laravel-shaped mental model.

Minimal steps in a Symfony app:

composer require ibrows/rest-bundle

Then register it in config/bundles.php (or AppKernel::registerBundles() on older skeletons) after FOSRestBundle. Import the routing if the bundle ships controllers, and add a config block — check the bundle's DependencyInjection/Configuration.php for the exact root key and node names, because the README is thin.

Where to look first, in this order:

1. DependencyInjection/Configuration.php — the real documentation for config options.
2. Resources/config/services.xml (or .yaml) — what it actually registers, and therefore what it overrides.
3. Any Controller/, EventListener/, or Annotation/ directories — these are the features you'll touch.
4. tests/ — if present, it's the only reliable spec; if absent, budget time for your own smoke tests.

A sensible first use case: pick one endpoint that already works under plain FOSRest and re-implement it using the bundle's abstractions (base controller trait, response helper, or exception listener). If the output is byte-identical to what FOSRest produced, the integration is sound and you can expand from there.

Implementation Patterns

Base controller + traits. Bundles like this usually ship an abstract controller or traits that wrap FOSRest's View handling. Prefer composing those traits into your existing controllers over extending a vendor base class — it keeps you free to swap the bundle out later.

Error normalisation via listeners. The most common value-add in this space is a kernel.exception listener that turns exceptions into a consistent JSON envelope (code, message, errors). Wire it through the bundle config first, then only decorate it if you need custom fields. Keep your own domain exceptions extending a known base so the listener can map them predictably.

Request body handling. Where the bundle offers deserialization or param conversion, keep it in one place: either always rely on the bundle's converter or always do it explicitly in the controller. Mixing both produces hard-to-trace validation gaps.

Serialization groups per action. Pin JMS serialization groups at the controller/action level and let the bundle's view layer handle rendering. Avoid ad-hoc json_encode in actions — that's the quickest way to diverge from whatever contract the rest of the API follows.

Functional tests. Use Symfony's KernelBrowser to assert status codes and response shape per endpoint. This is your safety net given the package's near-zero community footprint.

Laravel translation, if you're porting the idea rather than the code: the equivalents are FormRequests (deserialization + validation), API Resources (serialization groups), Handler::render in bootstrap/app.php (exception normalisation), and route-model binding (param conversion). If your goal is "adopt these patterns," implement them natively in Laravel — do not chase a Symfony bundle.

Gotchas and Tips

• Maintenance risk is the headline. Zero stars, zero dependents, and a one-line description mean no community, no issue triage, and no compatibility guarantees. Pin the exact version in composer.json, and be prepared to fork. Do not put it on a critical path without owning the source.
• Symfony version drift. Packages of this vintage typically target Symfony 3.x/4.x and older FOSRest majors. Check composer.json's require block against your Symfony version before anything else; a failed composer update here is a blessing, not a bug.
• Bundle registration order matters. Register after FOSRestBundle so its service definitions win where intended, and clear the cache (bin/console cache:clear) after config changes — stale container definitions cause the most confusing "my config is ignored" bugs.
• Config keys are undocumented. Do not guess YAML keys from the README. Read Configuration.php, then verify with bin/console config:dump-reference <bundle_alias> and bin/console debug:container --tag=kernel.event_listener to confirm the listener is actually registered.
• Debugging responses. Use the Symfony profiler's Events panel to see whether the bundle's listener fired and in what order relative to FOSRest's own ExceptionListener/ViewListener. Double-rendering (two listeners both writing a response) is the classic symptom of an ordering conflict.
• Extension points. Prefer decorating the bundle's services (decorates: in your own services.yaml) over editing vendor code or monkey-patching via compiler passes. Compiler passes are fine for small adjustments, but decoration survives upgrades.
• Write contract tests. Assume upstream won't. Snapshot the JSON shape of each endpoint so an accidental composer bump can't silently change your API.
• Honest recommendation for a Laravel developer: if the surrounding Symfony app doesn't already use FOSRestBundle, this package adds no value — skip it and implement the same conventions with Symfony's native AbstractController + serializers. If the app does already use FOSRestBundle, evaluate the bundle's source line-by-line (it's small) and decide whether copying the few useful listeners into your own src/ is cheaper than the dependency. Usually it is.