Api Platform Ms Bundle Laravel Package

Getting Started

This assessment covers v1.2.0.

First, the honest framing: mtarld/api-platform-ms-bundle is a Symfony bundle for API Platform, not a Laravel package. There is no service provider, no facade, no config/*.php to publish, and no package auto-discovery. If your day-to-day is a Laravel monolith, you will only touch this in one of two situations:

1. You maintain a separate Symfony/API Platform service that your Laravel app consumes over HTTP.
2. You are using API Platform 4 standalone (it no longer requires a full Symfony app skeleton) as a schema/contract layer.

If neither applies, stop here — this is not a dependency you can drop into a Laravel app and get value from.

Minimal steps (Symfony service):

composer require mtarld/api-platform-ms-bundle:^1.2

• v1.2.0 requires API Platform ^4.0 and Symfony ^7.0. On API Platform 3 / Symfony 6, stay on ^1.1.
• Register the bundle in config/bundles.php.
• Confirm it wired up before writing any code:

bin/console debug:config mtarld_api_platform_ms   # actual root key may differ — check `debug:config --list`
bin/console lint:container

Where to look first: the bundle README's config reference, then the mtarld/signify docs — v1.2.0 is explicitly a Signify support release, so the behaviour you care about lives in Signify, not in the bundle.

First use case: take one existing API resource DTO, generate its JSON Schema from the PHP types, and hand that schema to the front-end (TypeScript types) or to an external consumer. That single loop — typed PHP DTO → schema artifact → typed client — is the whole value proposition.

Implementation Patterns

Keep DTOs boring and fully typed. The generator introspects PHP types. Constructor-promoted, explicitly typed properties (string, int, array, backed enums, \DateTimeImmutable) produce clean schemas. Anything relying on magic (__get, ArrayAccess, untyped arrays) produces mush.

Separate write models from read models. Define request payloads and response payloads as distinct DTOs in a dedicated namespace (e.g. App\Api\Schema\). This keeps generated schemas stable and stops internal entities leaking into your public contract.

Treat schemas as build artifacts, not runtime output. Generate in CI and commit the JSON:

bin/console cache:clear
# dump the generated document / schema set to a known path
git diff --exit-code docs/schema/

A non-empty diff means someone changed a public contract. That is the single most useful habit with this package.

Bridge to the Laravel side deliberately. Have the Symfony service publish its schema JSON (as a build artifact or an endpoint), and let the Laravel app consume the artifact, not the bundle. Generate TypeScript or validation rules from it in your Laravel repo's build step. This keeps the two stacks decoupled and means a Symfony upgrade never breaks a Laravel deploy.

Pin the compatibility matrix in composer.json. ^1.2 only resolves on AP4/Symfony 7. If you run multiple services on different Symfony versions, document which service is on which line — otherwise a shared lockfile or a copy-pasted constraint will bite you.

Snapshot-test the output. A functional test asserting the generated schema for one representative resource catches accidental contract changes far earlier than an integration test.

Gotchas and Tips

v1.2.0 is a compatibility release, not a feature release. The only change is Signify support for API Platform ^4.0 and Symfony ^7.0. That means the constraint floor moved. Consequences:

• On AP3/Symfony 6, composer update will silently keep you on v1.1.x — or fail resolution. Check with:

  composer why-not mtarld/api-platform-ms-bundle 1.2.0
  

• Upgrading to v1.2.0 means upgrading to API Platform 4. That is the real migration. AP4 changed metadata/attribute handling and state processor/provider wiring. Budget for the AP4 jump separately; do not treat this as a patch bump.

No Laravel affordances. No auto-discovery, no php artisan vendor:publish, no Laravel config merge. Attempting to install it in a pure Laravel app will produce a bundle class that nothing registers. Don't fight it.

Untyped constructs degrade silently. array without a value type, mixed, and union types with null often produce permissive or empty schemas rather than an error. Add docblock generics/annotations where the type system is ambiguous, and eyeball the generated output for the first few DTOs before trusting it.

Caching will lie to you. Schema generation is cached. After editing a DTO, bin/console cache:clear — and in dev, be aware that var/cache/dev can serve stale schemas across a container rebuild.

Debugging order of operations:

bin/console debug:config <bundle_root_key>   # is my config even applied?
bin/console debug:container --tag=<tag>      # which services feed generation?
bin/console lint:container                   # did the bundle break container compile?
bin/console api:openapi:export               # did schemas land where I expected?

Extension points: prefer decorating the generator service over forking the bundle. Register a decorator in services.yaml and post-process the schema array. That survives minor version bumps; copying bundle internals does not.

Version support expectation: given the release cadence (v1.1 → v1.2 with a hard AP4/Symfony 7 bump), assume the package tracks current majors and drops old ones. Pin exactly, and read the CHANGELOG before every minor — a "minor" here can move your platform requirements.