Api Bundle Laravel Package

Getting Started

somnambulist/api-bundle is a Symfony bundle, not a Laravel package — there is no ServiceProvider, no facade, and no config-publishing. As a Laravel dev you're borrowing the response-building pieces (somnambulist/response-builder, somnambulist/validation, somnambulist/api-problem) and adapting the plumbing yourself.

Minimal steps:

1. composer require somnambulist/api-bundle
2. Register the bundle in a Symfony kernel (bundles.php) — in Laravel you instead manually wire the classes you want: ResponseBuilder, ApiProblemFactory, and the content-negotiation listeners, typically in a small dedicated service provider you write yourself.
3. Publish/define config for the negotiation formats (JSON, HAL, XML) and error handling.
4. First use case: build a controller that extends/uses ApiController semantics — return a transformer result through the response builder rather than response()->json().

Where to look first:

• src/Controller/ApiController.php — the base controller pattern.
• src/Response/ — ResponseBuilder and how it composes Fractal transformers + status codes + links.
• The api-problem integration (ApiProblemFactory, exception listeners) — this is the highest-value piece to lift into Laravel because Laravel's default JSON error shape is not RFC 7807.
• The negotiation listener — determines request/response format from Accept.

Implementation Patterns

Transformer-driven responses. The bundle assumes league/fractal transformers. Instead of Eloquent API Resources, you define a transformer class and pass it to the response builder:

return $this->responseBuilder
    ->item($user, new UserTransformer(), 200)
    ->build();

Adapt by binding a ResponseBuilder singleton in a Laravel provider and injecting it into controllers — this gives you consistent envelope shape (data/meta/links) across the API.

RFC 7807 problem+json for errors. Wrap ApiProblemFactory and register it inside app/Exceptions/Handler::render() (or Laravel 11+ withExceptions). This is the single most portable, highest-leverage integration: it turns validation errors and thrown exceptions into application/problem+json bodies, which clients consuming your API can parse uniformly.

Validation via somnambulist/validation. The bundle expects a Validator producing a structured error set that the problem factory understands. If you're on Laravel, either (a) keep validation in FormRequest and manually translate ValidationException into a problem+json shape, or (b) adopt somnambulist/validation alongside — but not instead of — FormRequest so you don't lose Laravel's authorization hooks.

Content negotiation. The negotiation listener parses Accept and picks a format. In Laravel you replicate this with a middleware: read Accept, set an api.format request attribute, and have the response builder respect it. Don't rely on Laravel's Accept handling for HAL/JSON variants — it only knows about json.

Documentation. The bundle's docs story is Symfony/Nelmio-centric. In Laravel, use knuckleswtf/scribe or dedoc/scramble and annotate the same transformer output shapes yourself; don't try to port the Nelmio annotations.

Controller organization. Mirror the bundle's ApiController in a base ApiController in your app that handles: negotiation format resolution, problem-factory access, response-builder access, and a helper for paginated collection responses. This keeps individual controllers thin.

Gotchas and Tips

• Framework mismatch is the primary gotcha. Every bundle registration step (Symfony Kernel, config/packages/api.yaml) has no Laravel equivalent. Budget time for hand-wiring the listener stack or you'll end up with a half-integrated API where errors are RFC 7807 but successes aren't (or vice versa).
• Accept header strictness. The negotiation listener rejects unsupported formats with a 406. Laravel's request()->expectsJson() is much looser. If you port the listener, test with real clients (Postman, curl, browsers) — browser Accept strings often break naive parsing.
• Error shape leaks. ApiProblemFactory includes a detail field that can leak internal exception messages. Set it to a safe value in production and log the original — this is a common production footgun with any problem+json integration.
• Transformers vs. Resources. Fractal transformers have transform() + includeX() methods; Eloquent resources use toArray(). Don't mix them per-endpoint — pick one and document it, or response envelopes will differ subtly between routes.
• Pagination metadata. The bundle expects a paginator adapter around Fractal; Laravel's LengthAwarePaginator maps cleanly only via league/fractal's IlluminatePaginatorAdapter (in the league/fractal package itself, not this bundle). Add this adapter in your provider.
• Extension points are interfaces, not hooks. Because it's Symfony, customization is done by swapping services (implement ResponseBuilderInterface, ValidatorInterface, etc.), not by firing events. In Laravel, bind your implementations in the container rather than subclassing.
• Debugging. When responses come back empty or wrapped unexpectedly, first dump the resolved format attribute from the negotiation listener — silently falling through to JSON when you expected HAL is the most common cause. Second, confirm the response builder actually received your transformer (a null transformer yields { "data": null } with no error).
• License/star count signal. Three stars and zero dependents means almost no community troubleshooting; treat the source as the docs. Pin the version and be prepared to vendor the pieces you need (especially api-problem and response-builder) rather than depending on the bundle meta-package.