Configuration Converter Bundle Laravel Package

Getting Started

This bundle is a one-shot migration tool, not a runtime dependency. Treat it like a codemod: install it as a dev dependency, convert a directory of API Platform config, review the diff, then remove it.

1. Install (dev only). It is archived upstream, so pin the version you tested and expect to fork if you need fixes:

   composer require --dev gheb/configuration-converter-bundle
   

2. Register the bundle in config/bundles.php (dev/test env is enough):

   Gheb\ConfigurationConverterBundle\ConfigurationConverterBundle::class => ['dev' => true],
   

3. Find the command first. Command names/signatures are the one thing you should not guess — after install run:

   bin/console list | grep -i convert
   bin/console <command> --help
   

   Then read the README examples and the bundle's Command/ directory; that is the authoritative surface area, because the package is small and undocumented beyond its README.
4. First use case. You have a working API Platform 2.x app whose resources live in YAML (config/api_platform/resources.yaml) or XML (config/api_platform/resources.xml) and you want to move them into entity annotations (or the reverse), typically to consolidate config or to match a team convention. Point the converter at your existing mapping directory, generate the other format, diff, and delete the old files only after bin/console debug:config api_platform and /api/docs still look correct.

The realistic day-to-day leverage is: once per project, for a few hours, when migrating API Platform config style. It is not something you keep in composer.json long-term.

Implementation Patterns

Baseline-and-diff workflow (the only safe pattern).

git checkout -b chore/api-platform-config-format
# commit current state untouched
bin/console <converter-command> <source-format> <target-format> config/api_platform
git diff  # review every generated resource
bin/console cache:clear && bin/console debug:config api_platform

Run your functional/API tests and open /api/docs before committing. The converter is mechanical; the review is where you catch semantic drift.

Keep mapping.paths in sync. API Platform only loads resources from the paths declared in config/packages/api_platform.yaml. Before running the converter, confirm those paths point at the source format; after converting, update them to the new extension and re-run debug:config. A common failure is generating XML while mapping.paths still lists only .yaml files, so nothing changes at runtime.

Convert per-resource, not blindly in bulk, when the config is large. If the command accepts a file/directory argument, do one entity at a time on a branch, commit each, and test. This keeps diffs reviewable and isolates lossy conversions to a single resource.

Annotations ↔ file formats. Moving from annotations to YAML/XML means the converter reads @ApiResource from entities and emits config files; afterwards you must remove the annotation imports and use ApiPlatform\Core\Annotation\ApiResource; references. Going the other direction writes annotations into src/Entity, so ensure mapping.paths includes src/Entity and that annotation_reader/framework.annotations is enabled.

Treat output as generated, then own it. Do not plan to keep regenerating after hand-editing — the converter is one-way per file and re-running over hand-tuned config will clobber ordering and comments. Generate once, commit, then maintain by hand.

Gotchas and Tips

• Archived means frozen. No PHP 8 attributes support: modern API Platform uses #[ApiResource], and this bundle predates that. If your target is attributes, this tool will not get you all the way — plan a manual pass or a fork.
• Lossy round-trips. Comments, key ordering, !php/const / !php/enum YAML tags, custom serialization_context structures and version-specific operations/collectionOperations shapes are the usual casualties. Always diff, never trust silently.
• Version coupling. The generated shape matches the API Platform version the bundle was written against. On API Platform 3+, expect operations to need manual rework and test the result against debug:config api_platform.
• Back up and use VCS. Commit before running; never run the converter on uncommitted working-tree config.
• Debugging conversion failures:
  • -vvv on the command to surface parser exceptions.
  • Symfony YAML parse errors usually mean an unsupported tag or indentation issue in the source.
  • bin/console lint:yaml config/api_platform after generating YAML.
  • bin/console cache:clear — stale container config masks whether the conversion took effect.
• Config quirks. Ensure the bundle is enabled in the env you run the command in, that output directories exist and are writable (config/api_platform/, src/Entity/), and that api_platform.mapping.paths matches the source format before you run it.
• Extension points are thin. There is no meaningful plugin API; if you need a format the bundle doesn't support (attributes, custom DSL), the practical path is to fork, add a converter class alongside the existing ones, and keep it internal. Given 0 dependents and an archived status, budget for maintaining that fork rather than expecting upstream fixes.
• Remove it after migration. Drop the dev dependency and the bundles.php entry once the conversion PR is merged; leaving it installed invites accidental re-runs over hand-edited config.