Getting Started

Minimal Steps

Install the package in your Laravel package’s composer.json:
```
composer require kylekatarnls/multi-tester --dev
```
Initialize the config by adding a project to test:
```
vendor/bin/multi-tester --add=laravel/framework
```
This creates a .multi-tester.yml file with default settings for laravel/framework.
Run tests against the configured projects:
```
vendor/bin/multi-tester
```

First Use Case

Scenario: You’re developing a Laravel service provider (myorg/laravel-service) and want to ensure your changes don’t break laravel/framework or other dependent packages.

Add laravel/framework to .multi-tester.yml:
```
laravel/framework:
  version: ^10.0
```
Run tests:
```
vendor/bin/multi-tester
```
The tool will:
1. Clone laravel/framework (or use Packagist if no clone is specified).
2. Replace its vendor/ copy of your package with your local version.
3. Run phpunit (default) or the specified script.
4. Report success/failure for each project.

Implementation Patterns

Core Workflow

Configure Projects Define projects in .multi-tester.yml with optional overrides:

# Test against multiple Laravel versions
laravel/framework:10.x:
  script: vendor/bin/pest --minimal
laravel/framework:11.x:
  script: vendor/bin/pest --minimal
  install: composer install --prefer-dist

# Test a Spatie package with custom Travis commands
spatie/laravel-permission:
  travis  # Uses .travis.yml from spatie/laravel-permission

Integrate with CI Add to .travis.yml or GitHub Actions:

# Travis example
matrix:
  include:
    - php: 8.2
      env: MULTITEST='on'
script:
  - if [ "$MULTITEST" = 'on' ]; then vendor/bin/multi-tester; fi;

Leverage Defaults
- Omit clone: Uses Packagist to fetch Git URL.
- Omit install: Runs composer install --no-interaction.
- Omit script: Runs vendor/bin/phpunit --no-coverage.
Advanced: Version-Specific Testing Test your package against multiple versions of Laravel in one run:
```
laravel/framework:10.0.*:
  version: 10.0.0
laravel/framework:11.0.*:
  version: 11.0.0
```

Laravel-Specific Tips

Test Against Laravel’s Dependency Graph: Add key Laravel packages to .multi-tester.yml:
```
illuminate/support:
illuminate/database:
spatie/laravel-permission:
tightenco/ziggy:
```
PHP Version Compatibility: Use version to test against specific PHP/Laravel combinations:
```
laravel/framework:^10.0:
  version: ^10.0
```
Custom Scripts for Laravel: Override defaults for Laravel-specific test runners (e.g., Pest, PHPUnit with Laravel extensions):
```
laravel/framework:
  script: vendor/bin/pest --minimal --parallel
```

Debugging Workflow

Verbose Output:
```
vendor/bin/multi-tester -v
```
Shows detailed steps (clone, install, test execution).
Isolate Failures: Use stop_on_failure in config to halt after the first failure:
```
config:
  stop_on_failure: true
```
Travis Debugging: Add set -x to your Travis script to log commands:
```
script:
  - set -x
  - vendor/bin/multi-tester
```

Gotchas and Tips

Pitfalls

Packagist API Limits:
- If Packagist fails, multi-tester falls back to libraries.io (slower).
- Fix: Cache results or use clone URLs directly in config.
Git Detach Issues:
- Some projects may fail with detached HEAD states.
- Fix: Add git checkout -f to your clone command or use success_only: true to revert to the last known good commit.
Composer replace Conflicts:
- Projects using composer.json replace may break if your package isn’t a direct replacement.
- Fix: Ensure your package’s name and version match the replace constraints.
PHP Version Mismatches:
- Testing against PHP 8.2 in a PHP 8.1 environment may fail silently.
- Fix: Use Docker or CI environments with matching PHP versions.
Verbose Output Overload:
- Default output can be noisy for large projects.
- Fix: Use --quiet or redirect output:
```
vendor/bin/multi-tester --quiet > test-results.log
```

Debugging Tips

Inspect Working Directories:
- Projects are cloned into ./multi-tester-workdir/<project>. Inspect manually if tests fail:
```
ls ./multi-tester-workdir/laravel/framework/vendor/
```
JSON Error Output:
- If a command fails, multi-tester outputs JSON with error details. Parse it with:
```
vendor/bin/multi-tester | jq '.errors[]'
```
Travis-Specific Issues:
- Travis may timeout during composer install. Use --prefer-dist or shallow clones:
```
laravel/framework:
  install: composer install --prefer-dist --no-scripts
```
Color Output:
- Disable colors in CI if they interfere with logging:
```
vendor/bin/multi-tester --no-colors
```

Extension Points

Custom Commands: Extend beyond clone, install, and script by using shell scripts:

myorg/laravel-package:
  clone: git clone --depth 1 https://github.com/myorg/laravel-package.git .
  install: |
    composer install --prefer-dist
    php artisan package:discover
  script: vendor/bin/pest --minimal

Post-Test Hooks: Add cleanup or validation steps by chaining commands:
```
config:
  post_script: ./scripts/validate-changes.sh
```
Parallel Testing: Use stop_on_failure: false and run in parallel with GNU Parallel:
```
vendor/bin/multi-tester --stop-on-failure=false | parallel --halt now,fail=1
```

GitHub Actions Integration: Cache dependencies to speed up runs:

jobs:
  multi-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v3
        with:
          path: ~/.composer
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
      - run: composer install
      - run: vendor/bin/multi-tester

Laravel-Specific Quirks

Laravel’s vendor/bin: Some Laravel packages expect vendor/bin to be executable. Ensure your install command includes:
```
install: composer install && chmod -R +x vendor/bin/
```
Autoloading Issues: If your package changes PSR-4 autoloading, projects may fail with class not found errors. Fix: Add autoload to your config:
```
config:
  autoload: true  # Ensures composer dump-autoload is run
```
Environment Variables: Laravel projects often rely on .env. Copy your local .env or use a template:
```
laravel/framework:
  install: |
    cp .env.example .env
    composer install
```

Multi Tester Laravel Package