Composer Test Scenarios Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require --dev g1a/composer-test-scenarios
   

2. Define scenarios in composer.json:

   "extra": {
       "scenarios": {
           "symfony4": {
               "require": {
                   "symfony/console": "^4.0"
               }
           },
           "phpunit6": {
               "require-dev": {
                   "phpunit/phpunit": "^6.5"
               }
           }
       }
   }
   

3. Update scenarios:

   composer scenario:update
   

   This generates .scenarios.lock/ with lockfiles for each scenario.

4. Test a scenario locally:

   composer scenario symfony4 && composer test
   

First Use Case

Use this to test your project against multiple dependency versions (e.g., Symfony 4 vs. 5) without maintaining separate branches or composer.lock files. Ideal for CI/CD pipelines (e.g., Travis/GitHub Actions) to validate compatibility.

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Use environment variables (SCENARIO, HIGHEST_LOWEST) to dynamically select scenarios and dependency resolutions.
   • Example .travis.yml snippet:

     matrix:
       include:
         - env: SCENARIO=symfony4 HIGHEST_LOWEST=highest
         - env: SCENARIO=phpunit6 HIGHEST_LOWEST=lowest
     before_script:
       - composer scenario:update
       - composer scenario $SCENARIO
       - if [ "$HIGHEST_LOWEST" = "highest" ]; then composer update; fi
       - if [ "$HIGHEST_LOWEST" = "lowest" ]; then composer update --prefer-lowest; fi
     

2. Local Development:

   • Switch scenarios with composer scenario <name>.
   • Reset to default with composer install or composer scenario default.

3. License Compliance:

   • Automatically update LICENSE with dependency licenses:

     composer dependency-licenses
     

Integration Tips

• Version Pinning: Commit .scenarios.lock/ to ensure reproducible builds.
• Platform Config: Use config.platform in scenarios to mock PHP versions (e.g., php: "7.4").
• Exclude Lockfiles: Set "create-lockfile": "false" for scenarios where lockfiles aren’t needed (e.g., dev-only dependencies).

Gotchas and Tips

Pitfalls

1. Lockfile Conflicts:

   • Avoid modifying .scenarios.lock/ manually. Use composer scenario:update to regenerate.
   • If a scenario fails to update, check for conflicting require constraints in composer.json.

2. CI Cache Issues:

   • Cache .scenarios.lock/ in CI to avoid redundant updates. Example (GitHub Actions):

     cache:
       key: scenarios-${{ hashFiles('composer.json') }}
       paths:
         - .scenarios.lock
     

3. Platform Overrides:

   • Platform settings (e.g., php: "7.1") in scenarios may override global composer.json config. Test thoroughly.

Debugging

• Verify Scenario Installation:

  composer scenario <name> && composer show
  

  Check installed versions match expectations.

• Dry Runs: Use composer update --dry-run to preview changes before applying.

Extension Points

1. Custom Commands: Extend the plugin by creating custom commands in composer.json:

   "scripts": {
     "post-scenario-update": "php scripts/post-scenario.php"
   }
   

2. Pre/Post Hooks: Use post-scenario-install or post-scenario-update scripts to run validation or migrations.

3. Dynamic Scenarios: Generate scenarios programmatically by extending the plugin’s ScenarioManager class (advanced).

Tips

• Travis Matrix Optimization: Combine scenarios with PHP versions for efficient testing:

  matrix:
    include:
      - php: 7.4
        env: SCENARIO=symfony4 HIGHEST_LOWEST=highest
      - php: 8.0
        env: SCENARIO=phpunit6 HIGHEST_LOWEST=lowest
  

• Exclude Dev Dependencies: Use "scenario-options": {"exclude-dev": true} to skip dev dependencies in a scenario.

• Partial Updates: Update only specific scenarios with:

  composer scenario:update symfony4