Rest Bundle Laravel Package

Getting Started

• Check compatibility first. This bundle is archived and targets the Symfony 2.x/3.x era (PHP 5.6–7.x). On a modern app you will almost certainly need a maintained fork or a pinned set of dependencies. Treat composer require stanlemon/rest-bundle as a spike, not a production install, until composer why-not is clean.

• Register the bundle in app/AppKernel.php (or config/bundles.php on Symfony 3.4+/4):

  new StanLeMon\RestBundle\StanLeMonRestBundle(),
  

• Confirm the routing mechanism before writing config. This bundle generates routes from entity configuration rather than from controller annotations. Depending on the version, routes are either registered automatically from the bundle config or must be imported through a custom route loader in app/config/routing.yml (the usual pattern is a type: stanlemon_rest import). Check Resources/config/ and the README for the exact import line for your version.

• Look here first, in this order: README.md → DependencyInjection/Configuration.php (the authoritative list of config keys and defaults) → the base resource controller under Controller/ → the route loader. The Configuration.php file is the fastest way to discover what is actually supported in the version you installed.

• Minimal configuration is a mapping from a Doctrine entity to a URL path:

  # app/config/config.yml
  stanlemon_rest:
      resources:
          AppBundle\Entity\Post:
              path: /api/posts
              # controller, form type, serialization groups, methods, etc. vary by version
  

• First use case: expose a single, simple entity (no deep associations) as a CRUD resource, verify with bin/console debug:router | grep api/posts, then exercise it:

  curl -i http://localhost/app_dev.php/api/posts
  curl -i -X POST http://localhost/app_dev.php/api/posts \
       -H 'Content-Type: application/json' \
       -d '{"title":"Hello"}'
  

  Get the read path working before enabling writes; most problems surface in serialization and form binding, not in routing.

Implementation Patterns

• Config-driven CRUD for simple entities. The sweet spot is flat entities with scalar fields: configure the resource, add serialization groups, and let the generic controller handle list/get/create/update/delete. Anything with rich business rules belongs in a hand-written controller.
• Use serialization groups aggressively. Configure a group per operation (e.g. post_list, post_read, post_write) so collections return shallow representations and item reads return the full object. This is the single most effective way to avoid recursion and accidental data exposure.
• Bind writes through a form type. Where the version supports it, point the resource at a Symfony form type. This gives you validation, field whitelisting, and consistent 400 responses instead of raw entity hydration (which is effectively mass assignment).
• Customize queries via the repository, not the controller. Add repository methods for filtered/paginated collections and have the controller call them, or extend the bundle's base controller and override the collection action. This keeps pagination, sorting, and eager-loading concerns in one place.
• Subresources and relations need custom controllers. Do not expect nested routes (/posts/{id}/comments) or relationship management out of the box. Register those as ordinary Symfony controllers alongside the generated ones.
• Put the API behind a stateless firewall. Configure a stateless: true firewall for the API prefix and use access_control for coarse-grained rules. Fine-grained ownership checks belong in a voter invoked from a custom controller or a kernel event listener.
• Standardize the envelope early. If the bundle returns bare entities/arrays, add a kernel response listener or a custom controller base to wrap responses in a consistent {data, meta, errors} shape before clients depend on the raw output.
• CORS and content negotiation are not the bundle's job. Pair it with nelmio/cors-bundle and, if you need XML or versioned media types, a format listener. Assume JSON-only unless you verify otherwise.
• Test at the HTTP level. Functional tests hitting the generated routes catch serialization and validation regressions that unit tests miss. Keep a fixture entity and a small CRUD test suite as a regression net when upgrading.

Gotchas and Tips

• Archived means frozen. No security fixes, no PHP 8 / modern Symfony support, and dependency resolution will fight you. Pin exact versions, commit the lock file, and plan a migration path (API Platform is the natural successor for this use case) rather than building long-term on it.
• Circular references are the most common failure. Bidirectional associations will blow up the serializer. Fix with serialization groups and @MaxDepth/circular-reference handlers on the serializer, not by marking relations @Ignore permanently.
• Expect N+1 queries. Lazy-loaded associations are serialized one row at a time. Use fetch joins in the repository for collection endpoints and measure with the profiler before shipping.
• Mass assignment risk. If writes hydrate entities directly, unknown JSON keys and sensitive fields can slip through. Always route writes through a form type or an explicit field whitelist.
• Partial updates are ambiguous. Verify whether PUT replaces the whole entity or merges; if it merges, you cannot null out fields, and if it replaces, clients will accidentally wipe data. Document the behavior and prefer PATCH semantics where supported.
• Validation errors often surface as generic 400s. If the bundle maps form errors into the response, check the exact shape in the base controller. If it does not, add an exception listener for InvalidArgumentException/form exceptions so clients get field-level errors.
• Config changes require a cache clear. Routing is generated from configuration, so bin/console cache:clear after every resource edit — stale route caches are a frequent source of "my new endpoint 404s."
• Watch for route collisions. Two resources with overlapping paths (or a resource shadowing a hand-written route) resolve by registration order. Use bin/console debug:router --show-controllers to confirm which controller actually wins.
• Debugging toolkit: debug:router for generated routes, debug:config stanlemon_rest (Symfony 3.2+) for the resolved configuration, the profiler's Doctrine panel for query counts, and debug:container to find the resource controller service ID if you want to decorate it.
• Extension points, in order of preference: extend the bundle's base controller and override individual actions → override the controller service via a compiler pass → decorate the controller → add kernel event listeners. Avoid editing vendor code; it will be lost on the next composer update and this package will not receive fixes upstream.
• Doctrine filters (soft deletes, tenant filters) apply to generated endpoints. That is usually desirable, but verify the collection count and item lookup both respect the filter, or you will leak deleted/foreign records through the API.