Api Bundle Laravel Package

Getting Started

Reality check first — this is not a Laravel package. monofony/api-bundle is a Symfony bundle (Monofony\Bundle\ApiBundle\MonofonyApiBundle), with no ServiceProvider, no publishable config, no facade, and no container bindings. Running composer require monofony/api-bundle inside a Laravel app will either fail on Symfony/API Platform constraints or drag in symfony/*, api-platform/core, doctrine/orm, and (likely) monofony/core + sylius/* transitives you cannot use. If you try to composer require it in a fresh Laravel 10/11 app you will almost certainly hit a conflict wall within minutes. Do not add it as a dependency. Treat it as a reference implementation you read.

Where to look first (in this order):

1. composer.json inside the package — confirms the Symfony/API Platform version floor. This tells you how dated the patterns are and which API Platform major it targets (2.x vs 3.x differ meaningfully at the serializer/metadata layer).
2. src/Resources/config/ — the YAML/XML service definitions and any api_resources/*.yaml files. This is where the actual resource shapes and serialization groups live; it is the most useful file to read for a Laravel developer, because it shows you exactly the HTTP resource contract an e-commerce API is expected to expose.
3. src/Controller/ — the "extensible controller" pattern. Small classes that delegate to services. This maps cleanly onto Laravel controllers.
4. src/DependencyInjection/Configuration.php — what (if anything) is configurable. Usually very little.

First use case for a Laravel developer: open the resource YAML, list the fields each endpoint exposes (product, order, cart), and write down the read/write serialization split. Then implement that exact contract as App\Http\Resources\ProductResource, OrderResource, etc. in your Laravel app, using $this->whenLoaded() and $this->when($request->user()?->can(...)) to reproduce the same conditional field exposure the Symfony bundle achieves via serialization groups. You get the design intent without the dependency risk.

Implementation Patterns

The bundle is small enough that "leveraging" it day-to-day means translating its patterns into Laravel idioms, not consuming its code. Five patterns are worth porting:

1. Serialization groups → Laravel API Resources with conditional fields. The bundle uses API Platform's serializer groups to distinguish "list view" from "detail view" from "admin view" payloads. In Laravel, reproduce this with dedicated Resource classes or a single Resource plus $this->when():

class ProductResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id'    => $this->id,
            'sku'   => $this->sku,
            'name'  => $this->name,
            'price' => new MoneyResource($this->price),
            // detail-only fields
            'description' => $this->when($request->routeIs('*.show'), $this->description),
            'stock'       => $this->when($request->boolean('include_stock'), $this->stock),
            // relations - lazy-eager-loaded only when included
            'variants' => VariantResource::collection($this->whenLoaded('variants')),
        ];
    }
}

2. Versioned routes → /api/v1/* route prefix, isolated by file. The bundle's "versioned routes for backward-compatible evolution" maps directly to Laravel's route-file convention:

// routes/api.php
Route::prefix('v1')->group(base_path('routes/api/v1.php'));
Route::prefix('v2')->group(base_path('routes/api/v2.php'));

Treat each version file as a frozen contract. Only add fields in v1; breaking shapes get a new v2 file. This is the single most valuable pattern the package encodes, and it costs you zero dependencies.

3. Thin controllers over a domain service. The bundle's "extensible controllers" are small Symfony controllers that call a service. In Laravel: inject a service class, keep the controller to three lines, put order state transitions and cart recalculation in the service.

class OrderTransitionController extends Controller
{
    public function __invoke(Request $request, Order $order, OrderStateMachine $machine)
    {
        $machine->apply($order, $request->string('transition'));
        return new OrderResource($order->fresh());
    }
}

4. State machine for orders. Monofony uses Symfony Workflow to drive order state (cart → addressed → shipped → cancelled). The Laravel equivalent is spatie/laravel-model-states or symfony/workflow standalone (the latter actually works fine in Laravel since it is framework-agnostic). Whatever you pick, encode the transitions as data (cart → addressed is legal; cart → shipped is not) and expose transitions as the API resource contract — the same way the bundle does.

5. Conditional field exposure by caller role. The bundle uses groups per role. In Laravel, use policies plus Resource gating: the same OrderResource returns a different shape for customer vs. admin because $this->when(auth()->user()->can(...)) is doing the grouping for you. Do not build two separate resources — one resource with a policy check keeps the contract in one place.

Integration tip: if you want a Monofony-compatible API on Laravel, the honest equivalent stack is:

• HTTP layer: Laravel controllers + Route::apiResource
• Serialization: Eloquent API Resources
• Auth: Laravel Sanctum (for mobile/SPA) or Passport (for third-party OAuth)
• Docs: dedoc/scramble (auto-generates OpenAPI from your controllers/resources)
• Versioning: /api/v{n} route files
• Pagination: Laravel's LengthAwarePaginator shape (data, meta.links) — pick one and freeze it in v1

That combination replicates 100% of what this bundle does for real users, with none of the framework-fit problems.

Gotchas and Tips

The name is misleading. "api-bundle" reads like a portable library. It is not — it is the extracted API surface of the Monofony e-commerce distribution. Its assumptions baked into every class are: Monofony customer/order/product entities exist, Doctrine ORM is the persistence layer, API Platform annotations/attributes drive routing, and Symfony's serializer is the wire format. None of that transfers to Eloquent/Illuminate.

Do not attempt to "make it Laravel." Any port is a rewrite. The only sane option is to read the resource YAML, extract the field list and transition graph, and reimplement. If someone asks you to integrate it into Laravel, the correct answer is a one-hour spike that ends in "port the contract, not the code."

Composer will fight you first. If you try anyway, run this before anything else:

composer require monofony/api-bundle --dry-run -W 2>&1 | grep -i conflict

You will see pinning against symfony/framework-bundle, api-platform/core, doctrine/orm, and php floor versions. Those are the real compatibility constraints — the README is not.

Pagination contract. The bundle inherits API Platform's Hydra/Iri pagination (@id, @type, hydra:member, hydra:totalItems). Laravel's built-in paginator shape is completely different (data, links, meta). If you ever migrate a client from a Monofony-backed API to a Laravel-backed one (or vice versa), the pagination envelope is the first thing that breaks. Freeze your Laravel envelope choice in v1 and write contract tests on it.

Serialization groups vs. API Resources — the "silent drift" trap. Just like an API Platform entity annotation can change a payload by tweaking a groups array, a change to a Laravel API Resource can silently change every endpoint that returns it. Guard against this with response-level tests (assert exact JSON keys), not just unit tests on the resource class.

Auth is your problem, twice. The bundle ships no auth. In Laravel, that is fine — Sanctum is a one-line install. The gotcha is that Sanctum's token ability model does not map to the Symfony bundle's "serialization groups per role" concept; if you port the role-gated resource pattern, wire it into policies ($user->can('viewSensitiveFields', $order)) so the gates show up in one policy file rather than scattered across resources.

Versioning without a versioning tool. Both API Platform and Laravel require you to hand-manage versions. There is no version negotiation, no deprecation header scheme, no sunset policy in this bundle. If you build on the pattern, add Sunset: / Deprecation: headers yourself — clients will thank you, and it is the difference between "evolved API" and "surprise breaking change."

If you must use it, it is Symfony only. If your team is genuinely on Monofony/Symfony and using this as a starting point: fork it into a private repo, pin every transitive dependency, add a composer.lock, and treat it as owned code from day one (1 star / 0 dependents means no upstream safety net). Never consume it as a composer require dependency in production.

Better alternatives on Laravel, in order: (1) build the catalog/order endpoints directly with Route::apiResource + dedicated API Resources; (2) add spatie/laravel-query-builder for filtering/sorting/includes; (3) add dedoc/scramble for auto OpenAPI; (4) spatie/laravel-model-states for the order state machine. That stack is what this bundle is a reference implementation of — for a Laravel team, it is strictly better than any attempt to graft the Symfony bundle on.