Api Platform Config Converter Bundle Laravel Package

Getting Started

Install it as a dev-only dependency (it is a code-generation/migration tool, not runtime infrastructure):

composer require --dev gheb/api-platform-config-converter-bundle

If Flex does not auto-register it, add the bundle to config/bundles.php for dev/test only. Then look in this order:

1. README.md — the supported input/output format matrix and the exact command signature.
2. src/Command/ — the console command name and its options (--from, --to, --output, dry-run flags).
3. src/Converter/ (or similarly named namespace) — the service that actually performs the transformation, which is what you decorate or extend if you need a custom format.
4. php bin/console list and php bin/console <command> --help — confirm the installed version's options rather than trusting the README.

First use case: converting a single legacy resource definition (typically a YAML file under config/api_platform/) into XML or annotations while upgrading an API Platform 2.x project. Do it on a branch, commit the current config, run the converter on one resource, and diff the result. Once that resource behaves identically (compare bin/console debug:router and the exported OpenAPI document), repeat for the rest.

Implementation Patterns

Branch-and-diff migration workflow. Never run the converter directly against your working tree on main. Create a branch, commit the existing config, run the converter into a separate output directory (--output=var/converted if supported, otherwise copy the source tree first), review the diff, then move files into place. This makes semantic regressions obvious and revertible.

Verify semantics, not just syntax. Before and after conversion, export the OpenAPI spec and compare:

bin/console api:openapi:export --yaml > var/openapi-before.yaml
# run converter, clear cache
bin/console cache:clear
bin/console api:openapi:export --yaml > var/openapi-after.yaml
diff -u var/openapi-before.yaml var/openapi-after.yaml

Also diff bin/console debug:router output. These two checks catch lost operations, wrong paths, dropped filters, and missing serialization groups far faster than manual review.

Convert one resource (or one directory) at a time. Large batch conversions produce enormous diffs that nobody reviews carefully. Convert, test, commit, repeat. Keep converted files under config/api_platform/ with the matching extension so API Platform's loader picks them up.

Chain with Rector for the final hop. The bundle handles the structural format change (YAML ↔ XML, annotations ↔ YAML/XML). If your target is PHP attributes on API Platform 3, use the bundle to get into annotations, then apply Rector's API Platform rulesets to finish the annotations → attributes step. Splitting the migration this way keeps each step reviewable.

Automate invocation in a Composer script or Makefile. A target like make convert-config that runs the command with -vvv and a fixed output directory makes the migration reproducible across team members and CI, and documents the exact invocation your project relies on.

Extend via services, not by editing vendor code. The converter is a Symfony service. If you need a custom format or post-processing (e.g., stripping docblock comments, reordering keys), decorate the converter service or add a compiler-pass-registered implementation of its interface. Check src/DependencyInjection/ for tags and configuration keys.

Pair with linters in CI. Run bin/console lint:yaml config/, xmllint --noout on generated XML, and php -l on generated PHP before committing. Converters are string/DOM emitters and occasionally produce edge-case output that only a linter will flag.

Gotchas and Tips

• It is archived. There will be no fixes for newer api-platform/core or Symfony versions, and no PHP attribute support from upstream. Pin the bundle and the API Platform version together in composer.json, and be prepared to fork. Treat it as a one-shot migration aid, not a long-term dependency.
• Conversion is structural, not semantic. Custom extensions, ApiResource options, filters, subresource definitions, and serializer metadata may not round-trip. The OpenAPI diff described above is your primary safety net. Anything that disappears must be re-added by hand.
• Comments and formatting are lost. YAML comments, docblock prose, and attribute ordering will not survive. If comments carry meaning (deprecation notes, ownership), extract them before running the converter.
• Noisy diffs from ordering/quoting. The emitter may reorder keys or change quoting style even when semantics are unchanged. Review at the semantic level (parsed structure) rather than line-by-line, or normalize output with a formatter before committing.
• Clear the cache after swapping files. API Platform caches resource metadata aggressively. A "failed" conversion is often just a stale cache — run bin/console cache:clear before concluding anything.
• Check the supported format matrix first. The bundle supports a specific set of source/target pairs. Attempting an unsupported hop may silently produce partial output. If your pair is unsupported, chain through a supported intermediate format rather than assuming it works.
• Run with -vvv and watch var/log/dev.log. Failures in parsing a resource usually surface as a warning with the offending file path; without verbose mode they can be swallowed and you get incomplete output.
• Keep it in require-dev. There is no reason for this bundle to be installed in production, and its archived status makes that doubly true.
• Watch PHP/Symfony version constraints. An archived package's composer.json constraints may conflict with current Symfony versions; if composer require fails, try a constrained version or install it in a throwaway branch with --ignore-platform-reqs only for the conversion run.