Getting Started

Minimal Steps

Installation: Add the package to your composer.json under require-dev:
```
"require-dev": {
    "phpcq/travis-configuration-check": "^1.0"
}
```
Run composer update.
First Run: Execute the CLI tool in your project root:
```
./vendor/bin/check-travis-configuration.php
```
This validates that:
- PHP versions in .travis.yml match those in composer.json.
- All PHP versions in .travis.yml are supported by Travis CI.

Quick Use Case: Integrate into a pre-commit hook or CI pipeline to catch misconfigurations early:

# Example: Add to package.json scripts
"scripts": {
    "validate:travis": "vendor/bin/check-travis-configuration.php"
}

Implementation Patterns

Usage Patterns

Local Development Validation: Run during development to catch inconsistencies before pushing:
```
composer validate:travis
```
- Pattern: Use in composer.json scripts or a custom Artisan command.
CI Pipeline Enforcement: Fail builds if .travis.yml is invalid:
```
# .travis.yml
before_script:
  - composer validate:travis || travis_terminate 1
```
- Pattern: Treat validation as a gate in CI workflows.
Unmaintained Version Checks: Enable stricter security checks (blocks PHP <5.4):
```
./vendor/bin/check-travis-configuration.php --unmaintained-version-error
```
- Pattern: Use in security-focused pipelines or pre-merge checks.
Multi-Project Validation: Validate external projects (e.g., monorepos or vendor packages):
```
./vendor/bin/check-travis-configuration.php /path/to/external/project
```
- Pattern: Use in dependency validation workflows.

Workflows

Laravel-Specific Integration: Wrap the CLI tool in an Artisan command for seamless Laravel integration:

// app/Console/Commands/ValidateTravisConfig.php
public function handle() {
    $command = base_path('vendor/bin/check-travis-configuration.php');
    $exitCode = shell_exec("$command " . $this->option('path'));
    if ($exitCode !== 0) {
        $this->error('Travis config validation failed!');
        exit(1);
    }
    $this->info('Travis config is valid.');
}

Workflow: Register the command in app/Console/Kernel.php and run via:
```
php artisan travis:validate
```

Git Hook Integration: Add to .git/hooks/pre-commit to block invalid .travis.yml changes:
```
#!/bin/sh
./vendor/bin/check-travis-configuration.php || exit 1
```
- Workflow: Enforce consistency before commits are accepted.

CI/CD Pipeline Integration: Use in parallel with other checks (e.g., PHPStan, Pest):

# .github/workflows/ci.yml (GitHub Actions example)
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: composer install
      - run: vendor/bin/check-travis-configuration.php

Pattern: Treat as a separate job to fail fast.

Integration Tips

Customize Error Handling: Parse the tool’s output to generate Laravel-friendly error messages:

$output = shell_exec('vendor/bin/check-travis-configuration.php');
if (strpos($output, 'ERROR') !== false) {
    throw new \RuntimeException("Travis config error: " . $output);
}

Combine with Laravel’s phpunit: Ensure PHP versions in .travis.yml align with Laravel’s testing requirements:

# .travis.yml
php:
  - 8.1
  - 8.2

# composer.json
"config": {
    "platform-check": false,
    "platform": {
        "php": "8.1"
    }
}

Extend for Laravel-Specific Checks: Add custom rules to validate Laravel-specific CI settings (e.g., deploy scripts):

# Example: Check for required Laravel CI variables
if ! grep -q "LARAVEL_ENV=testing" .travis.yml; then
    echo "ERROR: Missing LARAVEL_ENV in .travis.yml"
    exit 1
fi

Cache Validation Results: Avoid re-running validation in CI by caching results:

# .travis.yml
cache:
  directories:
    - $HOME/.cache/travis-validation
before_script:
  - if [ ! -f "$HOME/.cache/travis-validation/valid" ]; then
      composer validate:travis && touch "$HOME/.cache/travis-validation/valid";
    fi

Gotchas and Tips

Pitfalls

Archived Package Risks:
- Issue: The package is archived with no active maintenance.
- Fix: Fork the repo and maintain it internally, or replace with a modern alternative (e.g., laravel-shift/ci-config).
False Positives for Custom PHP Versions:
- Issue: The tool may flag nightly or custom PHP versions (e.g., php: 8.3-nightly) as invalid.
- Fix: Use the --unmaintained-version-error flag cautiously or whitelist versions in a custom wrapper.
Circular Dependency in CI:
- Issue: Running the validator in .travis.yml itself may fail if the tool’s PHP version requirements aren’t met.
- Fix: Run validation in a separate CI job or use a different CI system for the check.
Laravel-Specific Misalignments:
- Issue: Laravel’s composer.json may use platform-check: false or custom PHP constraints, causing conflicts.
- Fix: Normalize PHP versions in composer.json before validation:
```
composer config platform.php 8.1
```
Travis CI Environment Changes:
- Issue: Travis CI may deprecate PHP versions not listed in the tool’s hardcoded rules.
- Fix: Extend the tool’s validation logic or update the forked version.

Debugging

Verbose Output: The tool lacks verbose logging. To debug:
```
# Check raw YAML/JSON parsing
vendor/bin/check-travis-configuration.php --debug
```
- Workaround: Manually inspect .travis.yml and composer.json for inconsistencies.
Handling Partial Validations: If the tool fails but you’re sure the config is correct:
- Temporary Workaround: Disable checks via a custom script:
```
#!/bin/sh
if [ "$CI" = "true" ]; then
    exit 0  # Skip in CI
else
    vendor/bin/check-travis-configuration.php
fi
```
CI-Specific Errors:
- Symptom: Validation fails in CI but passes locally.
- Cause: Differences in composer.json (e.g., platform constraints) or .travis.yml (e.g., environment variables).
- Fix: Use composer install --no-platform-reqs in CI to match local validation.

Configuration Quirks

Unmaintained Version Logic:
- The tool hardcodes PHP <5.4 as unmaintained, which may not align with Laravel’s supported versions (8.0+).
- Tip: Override the logic in a fork or use a custom script:
```
// Example: Update the unmaintained versions list
$unmaintainedVersions = ['5.3', '5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3'];
```
Case Sensitivity in YAML:
- .travis.yml keys are case-sensitive. Ensure:
```
# Correct:
php: 8.1
# Incorrect (will fail):
PHP: 8.1
```
Composer Platform Constraints:
- If composer.json uses platform-check: false, the tool may misalign with actual runtime PHP.
- Tip: Normalize constraints before validation:
```
composer config platform.php 8.1
vendor/bin/check-travis-configuration.php
```

Extension Points

Custom Validation Rules: Extend the

Travis Configuration Check Laravel Package