Api Bundle Laravel Package

Getting Started

This is a legacy Symfony bundle (last tagged release August 2018, archived upstream), so treat it as maintenance-only. Before writing a line of application code:

1. Confirm it installs against your Symfony version. The composer.json will constrain Symfony to the 3.x/early-4.x range. If you are on Symfony 5+, you will almost certainly need --ignore-platform-reqs or a fork; do not fight this in production — pin the major.
2. Register the bundle in config/bundles.php (or AppKernel::registerBundles() on 3.x):

   Ruwork\ApiBundle\RuworkApiBundle::class => ['all' => true],
   

3. Read the bundle class and DI extension first, not the README. With a package this small and unmaintained, src/RuworkApiBundle.php, src/DependencyInjection/, and the Resources/config/*.xml service definitions are the actual documentation. The README on the archived repo is the secondary source.
4. Identify the entry point you care about. These bundles typically wire (a) a kernel exception listener that converts exceptions to JSON envelopes, (b) a response factory / view listener, and/or (c) serializer normalizer configuration. Find the tagged listeners in the service XML — that tells you where it hooks into the request/response cycle.

First use case: stand up one controller returning an entity and hit it with curl -i. If the bundle's listeners are active you should get a JSON Content-Type, a consistent error envelope on a thrown exception, and (if configured) HTTP-appropriate status codes. If you get HTML or a stack trace, the listener priority is wrong or the bundle isn't registered — check debug:event-dispatcher kernel.exception.

Implementation Patterns

• Thin controllers, exceptions for control flow. The core value of an API bundle like this is centralising error rendering. Throw domain exceptions (NotFoundException, validation exceptions) from services and let the kernel exception listener format them. Keep controllers returning data objects only.
• Response factory over manual JsonResponse. If the bundle exposes a response factory or view service, inject it rather than constructing JsonResponse by hand — that is the single seam you would otherwise have to rewrite if you migrate off the bundle. Wrapping it in your own ApiResponder service now makes the eventual replacement a one-file change.
• Serializer/normalizer wiring. If the bundle configures the Symfony serializer (likely, for an API bundle of this vintage), let it own the normalizer set and add your custom normalizers via the standard serializer.normalizer tag rather than reconfiguring the serializer from scratch. Two competing serializer configs is the classic failure mode.
• Validation → 422. Map ConstraintViolationListInterface to a structured 422 body in one subscriber or exception listener. If the bundle doesn't do this, add a single kernel.exception listener after the bundle's (lower priority number), so the bundle handles the generic case and yours handles validation specifically.
• Content negotiation. Set the request Accept: application/json in tests and clients. Many 2018-era bundles key their listeners on the request format; a missing Accept header silently disables the JSON error handling and you get the framework's HTML error page instead.
• Integration testing hook. Write one functional test per exception type asserting the JSON shape (assertJsonStructure / assertJsonPath) so a future Symfony upgrade that breaks the listener is caught immediately. This is the cheapest insurance for an archived dependency.

Gotchas and Tips

• It is archived with zero dependents and a 2018 release. Do not adopt for new work. Use Symfony's native ErrorHandler/ProblemNormalizer (4.4+) or API Platform instead. The only justified use is inheriting an existing codebase.
• Symfony version ceiling. Check composer.json require before upgrading Symfony. A transitive Symfony minor bump is the most likely thing to break this bundle, and there will be no upstream fix — budget for vendoring/forking.
• Listener priority is the usual bug. If errors render as HTML, confirm the bundle's kernel.exception listener is registered and at what priority (debug:event-dispatcher). Yours must sit below it to override selectively.
• Debug vs. prod divergence. Exception listeners commonly leak messages in dev and mask them in prod. Test the error envelope under APP_ENV=prod APP_DEBUG=0 explicitly; this is where the "works on my machine" tickets come from.
• Accept header / request format coupling. As above — missing or */* Accept frequently bypasses JSON handling. Assert the header in functional tests.
• Config quirks live in the DI extension, not the docs. Read DependencyInjection/Configuration.php for the actual config tree; the README will be stale or incomplete. Use config:dump-reference ruwork_api (adjust the alias) if the extension defines one.
• Extension point: the exception-listener's exception→status/body mapping is typically where you customise. If it's a service you can decorate, decorate it (decorates:) rather than editing vendor code — that survives a composer update and documents your divergence.
• No security/serialization hardening guarantees. A 2018 bundle predates several Symfony serializer CVE fixes and the getPrevious()-in-error-messages hardening. Audit what it echoes back in prod before shipping; strip exception messages for non-HttpException types yourself.
• Migration note for the future: isolate all bundle-specific code (response factory calls, exception classes it understands) behind one or two of your own services. When you replace it with native Symfony error handling, you delete those adapters and nothing else moves.