Rest Bundle Laravel Package

Getting Started

Install the bundle and confirm which Symfony versions it actually supports before you write code against it:

composer require yabx/rest-bundle

The package has three stars and zero dependents, so treat the composer.json require block as the source of truth — not the README. Check symfony/framework-bundle, symfony/serializer, and symfony/validator constraints and make sure they line up with the Symfony version already in your composer.lock. If they don't, stop here and evaluate before wiring anything up.

Register the bundle in config/bundles.php (it will usually be added automatically by Flex if the bundle ships a recipe; if there's no recipe, add it by hand):

return [
    // ...
    Yabx\RestBundle\YabxRestBundle::class => ['all' => true],
];

Where to look first, in this order:

1. vendor/yabx/rest-bundle/DependencyInjection/Configuration.php — this is the definitive list of every option the bundle accepts. Do not trust the README's config sample; it drifts. Dump the reference instead:

   php bin/console config:dump-reference <alias>
   

   The alias is whatever Configuration::getAlias() in DependencyInjection/Configuration.php returns — it is not necessarily yabx_rest.

2. vendor/yabx/rest-bundle/EventListener/ and EventSubscriber/ — this is where a REST bundle usually does its real work (exception-to-JSON mapping, response formatting, content negotiation). Read these before you configure anything.

3. Any Controller/ or Model/ directory — base controller classes and response/error DTOs. Find the base controller via:

   php bin/console debug:container --tag=controller.service_arguments
   

4. README.md last. For a low-adoption package the code is the documentation.

First use case — pick exactly one endpoint. Take a single existing controller action that currently does return new JsonResponse(['data' => $foo]) and route it through the bundle: extend the bundle's base controller (if it has one), return the bundle's response object, and deliberately throw an exception from that action to see what the bundle's exception listener produces. That one exercise tells you three things at once: whether the response envelope matches what your API consumers expect, whether errors leak stack traces, and whether the listener fires at all. If any of those three is wrong, you've learned it in ten minutes instead of after migrating twenty controllers.

Also run php bin/console debug:router immediately after enabling the bundle. Some REST bundles ship their own routes (documentation endpoints, health checks). You want to know about those before they show up in production.

Implementation Patterns

Extend the base controller, don't reimplement it. If the bundle exposes an abstract Controller or a trait with response helpers (ok(), created(), noContent(), error()), use it consistently across every controller. Mixed response shapes are the single most common way these bundles end up half-adopted and useless. If the base controller doesn't fit your existing envelope, subclass it once in your app (App\Controller\ApiController extends VendorController) and adapt there, so the vendor surface is touched in exactly one place.

Let the exception listener own error formatting. This is the highest-value part of any REST bundle. Map your domain exceptions to HTTP codes via the bundle's configuration (or a Symfony kernel.exception listener registered after the bundle's) rather than in controller try/catch blocks:

// Instead of try/catch in every action:
throw new NotFoundHttpException('Order not found');
// ...and let the bundle serialize it into the standard error body.

Verify the resulting payload in a functional test, not by eye — the exact JSON shape ({"error": {...}} vs {"errors": [...]} vs RFC 7807 application/problem+json) is a contract with your clients.

Validate request payloads at the boundary. If the bundle provides a request-to-DTO deserialization path, use it so that validation happens before your controller body executes:

public function create(CreateOrderRequest $request): Response
{
    // $request is already populated and validated, or an exception has been thrown.
}

If the bundle doesn't provide this, don't invent a parallel mechanism inside it — put a Symfony MapRequestPayload/argument resolver in front and keep the bundle responsible only for output.

Pagination should be one helper, used everywhere. Whether the bundle ships a paginator or you hand it a PaginatorInterface, funnel every list endpoint through the same helper so page, limit, total, and _links are identical across resources. Clients that have to special-case pagination per endpoint are a support burden forever.

Wrap third-party service access. Rather than injecting bundle services directly into twenty controllers, define one or two app-level services (e.g. ApiResponseFactory) that delegate to the bundle. When the bundle goes unmaintained — and at zero dependents, plan for it — you replace one class instead of grepping.

Test at the HTTP layer. The bundle's behaviour lives in listeners and normalizers, which unit tests won't catch. Use KernelBrowser against a real route:

$client->request('POST', '/api/orders', [], [], ['CONTENT_TYPE' => 'application/json'], $json);
$this->assertResponseStatusCodeSame(422);
$this->assertJsonPath('error.code', 'validation_failed');

Gotchas and Tips

Adoption risk is the headline gotcha. Three stars, zero dependents, and a score near the floor means: no community to answer questions, no guarantee of a security patch, and a real chance the repo is a company's internal extraction that gets abandoned. Mitigations, in order of preference: pin an exact version ("yabx/rest-bundle": "1.2.3", not ^1.2); commit composer.lock; keep the bundle's surface area behind one or two app-level wrapper classes; and confirm you can fork it before you depend on it. Check the last commit date and open issue count — if the last release predates your Symfony version, expect to patch compatibility yourself.

Config alias mismatch. The bundle's config key (yabx_rest, yabx_rest_bundle, rest) is not predictable from the package name. config:dump-reference with the wrong alias throws rather than guessing, so read Configuration::getAlias() if you're stuck. A silently-ignored config file is the most common "the bundle doesn't work" report — Symfony only errors on unknown keys under a known root, so a typo'd root is ignored entirely.

Exception listener ordering. Symfony dispatches kernel.exception to listeners in priority order. If your app already has an error listener (or Sentry, or a ProblemNormalizer), the bundle's may fire first and swallow it, or never fire at all. Inspect with:

php bin/console debug:event-dispatcher kernel.exception

If the bundle's listener runs before yours, adjust priority in your own listener registration rather than editing vendor code.

Dev vs prod divergence. Exception listeners very commonly behave differently under kernel.debug — full traces in dev, sanitized bodies in prod. A 500 that "looks fine locally" may produce an empty body in prod. Always assert on the prod payload shape at least once (APP_ENV=prod functional test or a staging smoke test).

Serialization pitfalls. With Symfony Serializer underneath, expect circular reference errors on bidirectional entities, MaxDepth exceptions on nested graphs, and datetime formats that don't match what your frontend parses. Prefer explicit DTOs over serializing Doctrine entities directly — it sidesteps circular references, prevents accidental field leakage, and decouples your JSON from your schema. Confirm the date format is explicit in config, not a default.

Content negotiation bites in two places. A missing Accept: application/json header can yield HTML errors from Symfony's own error handler rather than the bundle's JSON — clients report "the API returns HTML on 500". And if the bundle does format negotiation, a strict Accept check can 406 legitimate requests. Test with Accept: application/json, */*, and no header.

Don't let the bundle own CORS or auth. Preflight OPTIONS requests are frequently intercepted by the exception listener before your CORS listener runs, producing a 500 on preflight. Keep CORS (nelmio/cors-bundle) and authentication on the Symfony side, and verify preflight separately with curl -X OPTIONS.

Extension points to prefer over forking. In rough order of safety: decoration (decorates: in services.yaml) → a custom normalizer registered with a higher priority → a compiler pass → a fork. Only fork for genuine bugs, and when you do, tag it in your composer.json as a VCS repository so the deviation is visible in review.

Debugging toolkit for this class of bundle:

php bin/console debug:config <alias>       # what config actually took effect
php bin/console debug:container --tag=   # find tagged services
php bin/console debug:event-dispatcher kernel.exception
php bin/console lint:container            # catch wiring mistakes early

debug:config versus your YAML file is the fastest way to resolve "I set the option and nothing changed" — it shows merged, post-processing values, not what you wrote.