Continuous Integration Scripts Laravel Package

Getting Started

Minimal Steps

1. Installation Clone the repository into your Laravel project’s root or a dedicated scripts directory:

   git clone https://github.com/chaplean/continuous-integration-scripts.git bin/ci-scripts
   

   Ensure the scripts are executable:

   chmod +x bin/ci-scripts/*.sh
   

2. First Use Case: Running PHPUnit Tests Use phpunit.sh to execute tests in CI environments (e.g., GitLab CI, Codeship). Example invocation:

   ./bin/ci-scripts/phpunit.sh --parallel=4
   

   • Prerequisite: Ensure MySQL is available (use services-waiting.sh if needed).

3. Key Configurations

   • Edit scripts to reference your Laravel project’s paths (e.g., ./vendor/bin/phpunit).
   • Set environment variables (e.g., DB_DATABASE, DB_PASSWORD) in your CI pipeline or .env.

Implementation Patterns

Workflows

1. CI Pipeline Integration

   • GitLab CI Example:

     test:
       script:
         - ./bin/ci-scripts/services-waiting.sh
         - ./bin/ci-scripts/phpunit.sh --parallel=2 --coverage
     

   • Codeship: Use the deploy.sh script in the deploy stage after tests pass.

2. Parallel Test Execution Split PHPUnit tests by class or group using --parallel=N in phpunit.sh. Merge coverage reports with:

   ./bin/ci-scripts/phpunit.sh --parallel=4 --merge-coverage
   

3. Environment-Specific Deployments

   • Use deploy-htaccess.sh to conditionally deploy .htaccess files with htpasswd only in staging/production:

     if [ "$ENVIRONMENT" = "production" ]; then
       ./bin/ci-scripts/deploy-htaccess.sh
     fi
     

4. Docker Service Dependencies In Dockerized Laravel apps, use services-waiting.sh to wait for MySQL before running migrations/tests:

   ./bin/ci-scripts/services-waiting.sh mysql://root:secret@db:3306
   

Integration Tips

• Laravel-Specific Adjustments:
  • Update phpunit.sh to include Laravel’s test bootstrapping (e.g., --bootstrap=vendor/autoload.php).
  • For parallel tests, annotate test classes with @group unit/@group integration and configure phpunit.xml accordingly.
• Capistrano Deployments:
  • Customize deploy.sh to include Laravel-specific tasks (e.g., php artisan config:cache):

    ./bin/ci-scripts/deploy.sh --task=deploy:update_code --task=deploy:shared --task="run:artisan config:cache"
    

Gotchas and Tips

Pitfalls

1. Outdated Scripts

   • The package hasn’t been updated since 2018. Verify compatibility with:
     • PHPUnit 9+ (scripts may need --testdox-html or --log-junit flags).
     • Laravel 8/9’s service provider autoloading (adjust phpunit.sh paths).
   • Fix: Fork the repo and update shebangs/dependencies (e.g., #!/usr/bin/env bash).

2. Hardcoded Paths

   • Scripts assume bin/ directory structure. Override paths in CI variables:

     export SCRIPTS_DIR="custom/path/ci-scripts"
     ./$SCRIPTS_DIR/phpunit.sh
     

3. MySQL Connection Issues

   • services-waiting.sh may fail if MySQL credentials are misconfigured. Use environment variables:

     export DB_URL="mysql://user:pass@host:3306"
     ./bin/ci-scripts/services-waiting.sh $DB_URL
     

4. Parallel Test Conflicts

   • Race conditions may occur if tests write to shared storage (e.g., /tmp). Use --temp-dir in phpunit.sh:

     ./bin/ci-scripts/phpunit.sh --parallel=4 --temp-dir=/tmp/laravel-tests
     

Debugging

• Verbose Output: Add set -x to script headers to debug failures.
• Dry Runs: Test deployments locally with --dry-run (if supported by Capistrano).

Extension Points

1. Custom Scripts Extend the package by adding scripts (e.g., artisan.sh for Laravel commands):

   #!/usr/bin/env bash
   ./vendor/bin/sail artisan "$@"
   

   Place in bin/ci-scripts/ and make executable.

2. CI-Specific Hooks

   • GitLab: Use before_script to set up dependencies:

     before_script:
       - apt-get install -y mysql-client
       - ./bin/ci-scripts/services-waiting.sh
     

   • Codeship: Add scripts to deploy: or test: stages with environment variables.

3. Configuration Management

   • Replace hardcoded values with a .env.ci file (e.g., DB_PASSWORD) and source it in scripts:

     set -a && source .env.ci && set +a