Converter Bundle Laravel Package

Getting Started

1. Install the bundle as a development-only tool and register it only in your dev/test environment:

   composer require --dev tuck/converter-bundle
   

   // app/AppKernel.php (Symfony 2.x)
   if (in_array($this->getEnvironment(), ['dev', 'test'], true)) {
       $bundles[] = new Tuck\ConverterBundle\TuckConverterBundle();
   }
   

2. Run app/console list (or bin/console list on Symfony 3+) and locate the converter command. Historically this bundle exposes a command like container:convert. Confirm the exact name and arguments in the README, then inspect Command/ and Resources/config/services.xml to see how loaders/dumpers are wired.

3. First use case: convert one legacy service file before migrating a bundle:

   app/console container:convert app/config/services.xml app/config/services.yml
   

   If the command expects --input/--output options instead, use those. Review the generated file, diff it against the original, and verify the container still compiles before committing.

Implementation Patterns

• Convert one file per commit. Treat the converter as a migration assistant, not a bulk rewrite tool. Convert services.xml to services.yml, run git diff, fix lossy definitions by hand, then repeat for the next file.
• Use it as a scaffolding/discovery tool. Converting an XML service file to PHP is a quick way to learn the programmatic Definition API. Convert, inspect the generated PHP, then edit it into maintainable code.
• Round-trip to detect lossy conversion. Convert A -> B -> A and diff the result. If the round trip is clean, you can trust the format change more; if not, inspect tags, aliases, parameters, and factory/configurator definitions.
• Keep conversion in a minimal dev kernel. Run the command in the dev environment with as few bundles as possible. Avoid invoking it against a production container build, and never let it overwrite production config directly.
• Use it during Symfony 2-to-3/4 migrations. Move bundle service definitions from XML to YAML or PHP, then manually fix imports, parameter placeholders, tags, visibility, and deprecated flags.
• Generate XML when tooling expects it. If an external tool or legacy bundle only understands XML services, convert a YAML source file to XML, validate the result, and keep the YAML as the source of truth.
• Extend via services if needed. If your target format is unsupported, check the bundle’s converter/dumper services and add your own loader/dumper, or write a small command that uses Symfony’s XmlFileLoader/YamlFileLoader directly.

Gotchas and Tips

• This is a 2014-era package. It targets Symfony 2.x and has low adoption. Composer constraints may block modern Symfony versions, and the generated PHP/XML may use old APIs or schemas. Prefer a small custom command for new projects, and vendor/patch this bundle only if you need its exact behavior.
• Conversion is lossy. Comments, ordering, imports, extension config, expression language, %parameter%/%env()% placeholders, aliases, tags, visibility, factories, configurators, synthetic/abstract services, and deprecation flags may not survive. Always diff and compile the container afterward.
• Imports are not followed automatically. Convert imported files separately; imported paths may remain relative to the original file. Use absolute paths when running the command to avoid path-resolution surprises.
• Format is often inferred from the extension. Ensure outputs end in .yml, .xml, or .php; otherwise pass explicit format options if the command supports them.
• Validate before trusting. Run lint:yaml for YAML, validate XML against the expected schema, then swap the generated file into a dev kernel and run debug:container / container:debug. Check var/logs/dev.log and use -vvv for command-level errors.
• Do not overwrite source configs. Write to var/tmp/ or a scratch directory, compare, and only then move the file into place. Keep the original under version control.
• Generated PHP is a starting point, not final code. Review it for old Symfony APIs, missing arguments, and hard-coded service IDs before deploying.
• Extension point: look at the bundle’s service definitions for converter/dumper tags. If the built-in formats are insufficient, implement a custom dumper and register it, or bypass the bundle and use Symfony’s loaders plus your own dumper in a one-off command.