# GitHub Actions workflow for Continuous Integration (CI)
# This pipeline validates Composer config, installs dependencies, audits for vulnerabilities,
# enforces PSR-12 coding standards via PHPCS (lint job), runs PHPUnit tests with coverage (tests job),
# and verifies compatibility with the lowest allowed dependency versions (lowest-deps job).
# Tests run on multiple PHP versions to ensure broad compatibility.
name: CI

# Concurrency prevents duplicate runs on the same branch/PR by cancelling in-progress runs.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  # Trigger on pushes to main, but ignore docs/markdown-only changes to save CI minutes.
  push:
    branches: [ main ]
    paths-ignore:
      - 'README.md'
      - 'readme.md'
      - 'CHANGELOG.md'
      - 'docs/**'
  # Trigger on PRs targeting the main with the same path ignores.
  pull_request:
    branches: [ main ]
    paths-ignore:
      - 'README.md'
      - 'readme.md'
      - 'CHANGELOG.md'
      - 'docs/**'
  # Allow manual runs from the Actions UI.
  workflow_dispatch:

jobs:
  # Fast linting feedback - run on ALL PRs including Dependabot
  lint:
    name: Lint (PHP 8.3)
    runs-on: ubuntu-latest
    # Remove the dependabot exclusion - we want basic validation on all PRs
    steps:
      # Download the repository source code to the runner
      - name: Checkout repository
        uses: actions/checkout@v6

      # Install PHP with required extensions and configure memory limit
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: openssl, mbstring  # Required extensions for the project
          coverage: none  # No coverage needed for linting job
          ini-values: memory_limit=-1  # Remove memory limit for Composer operations

      # Verify that composer.json and composer.lock are valid and in sync
      - name: Validate composer.json and composer.lock
        run: composer validate --strict

      # Install project dependencies using cached composer packages for speed
      - name: Install dependencies (with cache)
        uses: ramsey/composer-install@v3
        with:
          composer-options: --prefer-dist --no-progress --no-interaction

      # Check for known security vulnerabilities in dependencies
      - name: Composer audit
        run: composer audit --no-interaction --format plain

      # Enforce PSR-12 coding standards on source and test files
      - name: Run PHP CodeSniffer (PSR-12)
        run: ./vendor/bin/phpcs --standard=PSR12 src tests

  # Static analysis - catch potential bugs and type mismatches
  analyse:
    name: Analyse (PHP 8.3)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: openssl, mbstring
          coverage: none
          ini-values: memory_limit=-1

      - name: Install dependencies (with cache)
        uses: ramsey/composer-install@v3
        with:
          composer-options: --prefer-dist --no-progress --no-interaction

      - name: Run PHPStan
        run: ./vendor/bin/phpstan analyse --configuration=phpstan.neon.dist --memory-limit=512M

  # Full test matrix - conditional based on PR type
  tests:
    name: Tests (PHP ${{ matrix.php-version }})
    runs-on: ubuntu-latest
    # Run full tests on:
    # 1. Non-Dependabot PRs
    # 2. Dependabot PRs with "major-update" or "production" labels (production deps)
    # Skip full tests on dev-only and ci updates to save resources
    if: |
      github.actor != 'dependabot[bot]' || 
      contains(github.event.pull_request.labels.*.name, 'major-update') ||
      contains(github.event.pull_request.labels.*.name, 'production')
    needs: [lint, analyse]
    strategy:
      # Continue running all matrix jobs even if one fails to get full coverage of results.
      fail-fast: false
      matrix:
        # Test across all supported PHP versions.
        php-version: ['7.4', '8.0', '8.1', '8.2', '8.3']

    steps:
      # Download the repository source code to the runner
      - name: Checkout repository
        uses: actions/checkout@v6

      # Install PHP with conditional coverage (Xdebug only on PHP 8.3)
      - name: Setup PHP (no coverage)
        if: ${{ matrix.php-version != '8.3' }}
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: openssl, mbstring  # Required extensions for the project
          coverage: none  # Disable coverage for non-8.3 versions
          ini-values: memory_limit=-1  # Remove memory limit for Composer operations

      - name: Setup PHP (with Xdebug)
        if: ${{ matrix.php-version == '8.3' }}
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: openssl, mbstring  # Required extensions for the project
          coverage: xdebug  # Enable Xdebug for code coverage collection on 8.3 only
          ini-values: memory_limit=-1  # Remove memory limit for Composer operations

      # Install project dependencies using cached composer packages for speed
      - name: Install dependencies (with cache)
        uses: ramsey/composer-install@v3
        with:
          composer-options: --prefer-dist --no-progress --no-interaction

      # Create directory structure for coverage and test result files (only for PHP 8.3)
      - name: Prepare coverage directory
        if: ${{ matrix.php-version == '8.3' }}
        run: mkdir -p build/logs

      # Execute PHPUnit for non-coverage PHP versions
      - name: Run PHPUnit (no coverage)
        if: ${{ matrix.php-version != '8.3' }}
        run: ./vendor/bin/phpunit --configuration phpunit.xml --colors=always

      # Execute PHPUnit with coverage and XML reporting (PHP 8.3 only)
      - name: Run PHPUnit with coverage
        if: ${{ matrix.php-version == '8.3' }}
        run: ./vendor/bin/phpunit --configuration phpunit.xml --coverage-clover build/logs/clover.xml --log-junit build/logs/junit.xml --colors=always

      # Upload test results and coverage data as artifacts (PHP 8.3 only)
      - name: Upload coverage artifacts
        if: ${{ always() && matrix.php-version == '8.3' }}
        uses: actions/upload-artifact@v6
        with:
          name: coverage-php-${{ matrix.php-version }}
          path: |
            build/logs/clover.xml
            build/logs/junit.xml

  # Lowest deps - only for production dependency updates
  lowest-deps:
    name: Lowest Deps (PHP 8.3)
    runs-on: ubuntu-latest
    # Only run on non-Dependabot or production dependency updates
    if: |
      github.actor != 'dependabot[bot]' || 
      contains(github.event.pull_request.labels.*.name, 'production')
    needs: lint
    steps:
      # Download the repository source code to the runner
      - name: Checkout repository
        uses: actions/checkout@v6

      # Install PHP without coverage since we only need basic functionality testing
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: openssl, mbstring  # Required extensions for the project
          coverage: none  # No coverage needed for dependency compatibility testing
          ini-values: memory_limit=-1  # Remove memory limit for Composer operations

      # Install the lowest allowed versions of all dependencies to test compatibility
      - name: Update to lowest dependencies
        run: composer update --prefer-lowest --prefer-stable --no-interaction --no-progress

      # Run tests without coverage to verify functionality with minimum dependency versions
      - name: Run PHPUnit (no coverage)
        run: ./vendor/bin/phpunit --configuration phpunit.xml --colors=always

  # Lightweight check for dev-only and CI updates
  quick-check:
    name: Quick Check (Dev/CI Updates)
    runs-on: ubuntu-latest
    # Only run on Dependabot PRs that are dev-only or ci updates
    if: |
      github.actor == 'dependabot[bot]' && 
      (contains(github.event.pull_request.labels.*.name, 'dev-only') || 
       contains(github.event.pull_request.labels.*.name, 'ci'))
    needs: lint
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: openssl, mbstring
          coverage: none
          ini-values: memory_limit=-1

      - name: Install dependencies (with cache)
        uses: ramsey/composer-install@v3
        with:
          composer-options: --prefer-dist --no-progress --no-interaction

      # Just run tests on latest PHP - no coverage needed
      - name: Run PHPUnit (quick check)
        run: ./vendor/bin/phpunit --configuration phpunit.xml --colors=always
