test.yml

name: Test

on:
  # Run on pushes to `stable` and `develop` and on all pull requests.
  push:
    branches:
      - stable
      - develop
    paths-ignore:
      - '**.md'
      - 'docs/**'
  pull_request:
  # Allow manually triggering the workflow.
  workflow_dispatch:

# Cancels all previous workflow runs for the same branch that have not yet completed.
concurrency:
  # The concurrency group contains the workflow name and the branch name.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  # - COMPOSER_ROOT_VERSION is needed to get round the recursive dependency when using CI.
  COMPOSER_ROOT_VERSION: '1.99.99'

jobs:
  lint:
    if: ${{ github.ref != 'refs/heads/develop' }}
    runs-on: ubuntu-latest

    strategy:
      matrix:
        php: ['5.4', '7.0', '7.4', '8.0', '8.3', '8.4']

    name: "Lint: PHP ${{ matrix.php }}"

    continue-on-error: ${{ matrix.php == '8.4' }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          ini-file: 'development'
          coverage: none
          tools: cs2pr

      - name: Install Composer dependencies - normal
        if: ${{ matrix.php < 8.4 }}
        uses: "ramsey/composer-install@v3"
        with:
          # Bust the cache at least once a month - output format: YYYY-MM.
          custom-cache-suffix: $(date -u "+%Y-%m")

      # For the PHP "nightly", we need to install with ignore platform reqs as not all dependencies allow it yet.
      - name: Install Composer dependencies - with ignore platform
        if: ${{ matrix.php >= 8.4 }}
        uses: "ramsey/composer-install@v3"
        with:
          composer-options: --ignore-platform-req=php+
          custom-cache-suffix: $(date -u "+%Y-%m")

      - name: "Lint against parse errors (PHP < 7.2)"
        if: ${{ matrix.php < 7.2 }}
        run: composer lint-lt72 -- --checkstyle | cs2pr

      - name: "Lint against parse errors (PHP 7.2+)"
        if: ${{ matrix.php >= 7.2 }}
        run: composer lint -- --checkstyle | cs2pr


  #### TEST STAGE ####
  test:
    if: ${{ github.ref != 'refs/heads/develop' }}
    needs: lint
    runs-on: ubuntu-latest

    strategy:
      # Keys:
      # - risky: Whether to run with tests which check for being in sync with PHPCS.
      # - experimental: Whether the build is "allowed to fail".
      matrix:
        # The GHA matrix works different from Travis.
        # You can define jobs here and then augment them with extra variables in `include`,
        # as well as add extra jobs in `include`.
        # https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix
        #
        # IMPORTANT: test runs shouldn't fail because of PHPCS being incompatible with a PHP version.
        #
        # The matrix is set up so as not to duplicate the builds which are run for code coverage.
        php: ['5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2']
        phpcs_version: ['lowest', 'dev-master']
        risky: [false]
        experimental: [false]

        include:
          - php: '5.6'
            phpcs_version: 'lowest'
            risky: false
            experimental: false
            extensions: ':iconv' # Run with iconv disabled.
          - php: '8.0'
            phpcs_version: 'dev-master'
            risky: false
            experimental: false
            extensions: ':iconv' # Run with iconv disabled.

          # Experimental builds. These are allowed to fail.
          - php: '8.4'
            phpcs_version: 'dev-master'
            risky: false
            experimental: true

          - php: '7.4'
            phpcs_version: '4.0.x-dev'
            risky: false
            experimental: true

          # Run risky tests separately.
          - php: '7.4'
            phpcs_version: '4.0.x-dev'
            risky: true
            experimental: true

          - php: '5.4'
            phpcs_version: 'lowest'
            risky: true
            experimental: true

          - php: '5.4'
            phpcs_version: 'dev-master'
            risky: true
            experimental: true

          - php: '8.3'
            phpcs_version: 'lowest'
            risky: true
            experimental: true

          - php: '8.3'
            phpcs_version: 'dev-master'
            risky: true
            experimental: true

    name: "Test: PHP ${{ matrix.php }} - PHPCS ${{ matrix.phpcs_version }}${{ matrix.risky == true && ' (risky)' || '' }}"

    continue-on-error: ${{ matrix.experimental }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # On stable PHPCS versions, allow for PHP deprecation notices.
      # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
      - name: Setup ini config
        id: set_ini
        run: |
          if [[ "${{ matrix.phpcs_version }}" != "dev-master" && "${{ matrix.phpcs_version }}" != "4.0.x-dev" ]]; then
            echo 'PHP_INI=error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On' >> $GITHUB_OUTPUT
          else
            echo 'PHP_INI=error_reporting=-1, display_errors=On' >> $GITHUB_OUTPUT
          fi

      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: ${{ matrix.extensions }}
          ini-values: ${{ steps.set_ini.outputs.PHP_INI }}
          coverage: none

      - name: "Composer: set PHPCS version for tests (master)"
        if: ${{ matrix.phpcs_version != 'lowest' }}
        run: composer require squizlabs/php_codesniffer:"${{ matrix.phpcs_version }}" --no-update --no-scripts --no-interaction

      # Remove PHPCSDevCS as it would (for now) prevent the tests from being able to run against PHPCS 4.x.
      - name: 'Composer: remove PHPCSDevCS'
        run: composer remove --dev --no-update phpcsstandards/phpcsdevcs

      - name: "Composer: use lock file when necessary"
        if: ${{ matrix.phpcs_version == 'lowest' }}
        run: composer config --unset lock

      # Install dependencies and handle caching in one go.
      # @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
      - name: Install Composer dependencies - normal
        if: ${{ matrix.php < 8.4 }}
        uses: "ramsey/composer-install@v3"
        with:
          # Bust the cache at least once a month - output format: YYYY-MM.
          custom-cache-suffix: $(date -u "+%Y-%m")

      # For PHP "nightly", we need to install with ignore platform reqs as not all dependencies allow it yet.
      - name: Install Composer dependencies - with ignore platform
        if: ${{ matrix.php >= 8.4 }}
        uses: "ramsey/composer-install@v3"
        with:
          composer-options: --ignore-platform-req=php+
          custom-cache-suffix: $(date -u "+%Y-%m")

      - name: "Composer: set PHPCS version for tests (lowest)"
        if: ${{ matrix.phpcs_version == 'lowest' }}
        run: composer update squizlabs/php_codesniffer --prefer-lowest --no-scripts --no-interaction

      - name: Grab PHPUnit version
        id: phpunit_version
        # yamllint disable-line rule:line-length
        run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> $GITHUB_OUTPUT

      - name: Determine PHPUnit config file to use
        id: phpunit_config
        run: |
          if [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}" == "true" ]; then
            echo 'FILE=phpunit10.xml.dist' >> $GITHUB_OUTPUT
            echo 'EXTRA_ARGS=' >> $GITHUB_OUTPUT
          else
            echo 'FILE=phpunit.xml.dist' >> $GITHUB_OUTPUT
            echo 'EXTRA_ARGS= --repeat 2' >> $GITHUB_OUTPUT
          fi

      - name: Run the unit tests without caching (non-risky)
        if: ${{ matrix.risky == false }}
        run: vendor/bin/phpunit -c ${{ steps.phpunit_config.outputs.FILE }} --no-coverage
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version == '4.0.x-dev' && '4.0.0' || matrix.phpcs_version }}
          PHPCSUTILS_USE_CACHE: false

      - name: Run the unit tests with caching (non-risky)
        if: ${{ matrix.risky == false }}
        run: >
          vendor/bin/phpunit -c ${{ steps.phpunit_config.outputs.FILE }}
          --testsuite PHPCSUtils --no-coverage ${{ steps.phpunit_config.outputs.EXTRA_ARGS }}
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version == '4.0.x-dev' && '4.0.0' || matrix.phpcs_version }}
          PHPCSUTILS_USE_CACHE: true

      # Only run the "compare with PHPCS" group against dev-master as it ensures that PHPCSUtils
      # functionality is up to date with `dev-master`, so would quickly fail on older PHPCS.
      - name: Run the unit tests (risky, comparewithPHPCS)
        if: ${{ matrix.risky && matrix.phpcs_version == 'dev-master' }}
        # "nothing" is excluded to force PHPUnit to ignore the <exclude> settings in phpunit.xml.dist.
        run: vendor/bin/phpunit -c ${{ steps.phpunit_config.outputs.FILE }} --no-coverage --group compareWithPHPCS --exclude-group nothing
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version == '4.0.x-dev' && '4.0.0' || matrix.phpcs_version }}

      # Run the "xtra" group against high and low PHPCS as these are tests safeguarding PHPCS itself.
      - name: Run the unit tests (risky, xtra)
        if: ${{ matrix.risky }}
        # "nothing" is excluded to force PHPUnit to ignore the <exclude> settings in phpunit.xml.dist.
        run: vendor/bin/phpunit -c ${{ steps.phpunit_config.outputs.FILE }} --no-coverage --group xtra --exclude-group nothing
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version == '4.0.x-dev' && '4.0.0' || matrix.phpcs_version }}


  #### CODE COVERAGE STAGE ####
  # N.B.: Coverage is only checked on the lowest and highest stable PHP versions
  # and a low/high of each major for PHPCS.
  # These builds are left out off the "test" stage so as not to duplicate test runs.
  coverage:
    # No use running the coverage builds if there are failing test builds.
    needs: test
    # The default condition is success(), but this is false when one of the previous jobs is skipped
    if: always() && (needs.test.result == 'success' || needs.test.result == 'skipped')

    runs-on: ubuntu-latest

    strategy:
      matrix:
        include:
          - php: '8.3'
            phpcs_version: 'dev-master'
          - php: '8.3'
            phpcs_version: 'lowest'
            extensions: ':iconv' # Run one build with iconv disabled.
          - php: '5.4'
            phpcs_version: 'dev-master'
          - php: '5.4'
            phpcs_version: 'lowest'

    name: "Coverage: PHP ${{ matrix.php }} - PHPCS ${{ matrix.phpcs_version }}"

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # On stable PHPCS versions, allow for PHP deprecation notices.
      # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
      - name: Setup ini config
        id: set_ini
        run: |
          if [ "${{ matrix.phpcs_version }}" != "dev-master" ]; then
            echo 'PHP_INI=error_reporting=E_ALL & ~E_DEPRECATED, display_errors=On' >> $GITHUB_OUTPUT
          else
            echo 'PHP_INI=error_reporting=-1, display_errors=On' >> $GITHUB_OUTPUT
          fi

      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: ${{ matrix.extensions }}
          ini-values: ${{ steps.set_ini.outputs.PHP_INI }}
          coverage: xdebug

      - name: "DEBUG: Show version details"
        run: php -v

      - name: "Composer: set PHPCS version for tests (master)"
        if: ${{ matrix.phpcs_version != 'lowest' }}
        run: composer require squizlabs/php_codesniffer:"${{ matrix.phpcs_version }}" --no-update --no-scripts --no-interaction

      - name: "Composer: use lock file when necessary"
        if: ${{ matrix.phpcs_version == 'lowest' }}
        run: composer config --unset lock

      - name: Install Composer dependencies
        uses: "ramsey/composer-install@v3"
        with:
          # Bust the cache at least once a month - output format: YYYY-MM.
          custom-cache-suffix: $(date -u "+%Y-%m")

      - name: "Composer: set PHPCS version for tests (lowest)"
        if: ${{ matrix.phpcs_version == 'lowest' }}
        run: composer update squizlabs/php_codesniffer --prefer-lowest --no-scripts --no-interaction

      - name: Grab PHPUnit version
        id: phpunit_version
        # yamllint disable-line rule:line-length
        run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> $GITHUB_OUTPUT

      - name: "DEBUG: Show grabbed version"
        run: echo ${{ steps.phpunit_version.outputs.VERSION }}

      # PHPUnit 9.3 started using PHP-Parser for code coverage causing some of our coverage builds to fail.
      # As of PHPUnit 9.3.4, a cache warming option is available.
      # Using that option prevents issues with PHP-Parser backfilling PHP tokens when PHPCS does not (yet),
      # which would otherwise cause tests to fail on tokens being available when they shouldn't be.
      # As coverage is only run on high/low PHP, the high PHP version will use PHPUnit 10, so just check for that.
      - name: "Warm the PHPUnit cache (PHPUnit 9.3+)"
        if: ${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}
        run: vendor/bin/phpunit -c phpunit10.xml.dist --coverage-cache ./build/phpunit-cache --warm-coverage-cache

      - name: "Run the unit tests without caching with code coverage (PHPUnit < 10)"
        if: ${{ ! startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}
        run: vendor/bin/phpunit
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version }}
          PHPCSUTILS_USE_CACHE: false

      - name: "Run the unit tests without caching with code coverage (PHPUnit 10+)"
        if: ${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}
        run: vendor/bin/phpunit -c phpunit10.xml.dist --coverage-cache ./build/phpunit-cache
        env:
          PHPCS_VERSION: ${{ matrix.phpcs_version }}
          PHPCSUTILS_USE_CACHE: false

      - name: Upload coverage results to Coveralls
        if: ${{ success() }}
        uses: coverallsapp/github-action@v2
        with:
          format: clover
          file: build/logs/clover.xml
          flag-name: php-${{ matrix.php }}-phpcs-${{ matrix.phpcs_version }}
          parallel: true

  coveralls-finish:
    needs: coverage
    if: always() && needs.coverage.result == 'success'

    runs-on: ubuntu-latest

    steps:
      - name: Coveralls Finished
        uses: coverallsapp/github-action@v2
        with:
          parallel-finished: true