Composer Yaml Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev c33s/composer-yaml
   

   Ensure the package is listed in require-dev in your composer.json.

2. Basic Conversion: Run the conversion from the command line:

   vendor/bin/composer-yaml convert composer.yml
   

   This generates a composer.json file from your composer.yml.

3. First Use Case:

   • Use this package if your project uses composer.yml (e.g., legacy systems or specific workflows).
   • Convert it to composer.json for compatibility with modern Composer tools, CI/CD pipelines, or Laravel’s ecosystem.

Implementation Patterns

Workflows

1. Legacy Migration:

   • Gradually migrate from composer.yml to composer.json by converting files incrementally.
   • Use the package to validate the converted composer.json before fully adopting it.

2. CI/CD Integration:

   • Add the conversion step to your build pipeline:

     # Example GitHub Actions step
     - name: Convert composer.yml to composer.json
       run: vendor/bin/composer-yaml convert composer.yml
     

   • Ensure the converted file is committed or used in subsequent steps.

3. Local Development:

   • Use a post-install-cmd script in composer.json to auto-convert composer.yml on install:

     {
       "scripts": {
         "post-install-cmd": [
           "composer-yaml convert composer.yml"
         ]
       }
     }
     

   • Note: This may cause conflicts if composer.json already exists. Use conditionals or manual triggers instead.

Integration Tips

• Laravel-Specific:

  • If using Laravel, ensure the converted composer.json includes all required packages (e.g., laravel/framework, fruitcake/laravel-cors).
  • Validate the autoloader and classmap generation:

    composer dump-autoload
    

• Custom Configurations:

  • The package may support custom mappings or overrides. Check its documentation for flags like --output or --merge to control the conversion process.

Gotchas and Tips

Pitfalls

1. File Overwrites:

   • The package may overwrite existing composer.json files. Always back up or use --dry-run first:

     vendor/bin/composer-yaml convert --dry-run composer.yml
     

2. Schema Limitations:

   • composer.yml may not support all composer.json features (e.g., complex scripts, plugins, or conditional logic). Test thoroughly after conversion.

3. Dependency Conflicts:

   • Converted composer.json might introduce version conflicts. Use composer validate to check:

     composer validate composer.json
     

4. Laravel-Specific Issues:

   • Laravel’s optimize or config:cache commands may fail if the converted composer.json is malformed. Test in a staging environment first.

Debugging

• Verbose Output: Run with -v or --verbose for detailed conversion logs:

  vendor/bin/composer-yaml convert -v composer.yml
  

• Validation: Use Composer’s built-in validation:

  composer validate composer.json
  

Extension Points

• Custom Conversion Logic: If the package lacks specific features, extend it by:

  1. Forking the repository and modifying the conversion logic.
  2. Using a post-conversion script to apply additional transformations (e.g., via jq or PHP).

• Integration with Laravel Mix/Vite: Ensure the converted composer.json includes frontend dependencies (e.g., npm packages) if your project uses them. Example:

  {
    "extra": {
      "laravel": {
        "vite": ["resources/js/app.js"]
      }
    }
  }
  

Tips

• Document the Process: Add a CONTRIBUTING.md or README section explaining the composer.yml to composer.json conversion workflow for teammates.

• Version Pinning: Pin the package version in composer.json to avoid unexpected behavior:

  {
    "require-dev": {
      "c33s/composer-yaml": "^1.0"
    }
  }