speed-matrix.yml

name: Speed Matrix

# Manual-only: never runs on push. Dispatch from the Actions tab ("Run workflow") or
# with: gh workflow run speed-matrix.yml
#
# Benchmarks every hot-path optimization candidate as paired A/B comparisons across
# PHP versions and platforms. Numbers are B-vs-A ratios measured interleaved in one
# process, so shared-runner speed wobble cancels out; treat anything within +/-5% as
# a tie. See .github/scripts/speed-probe.php for the tests and design rules, and
# .github/scripts/speed-results.md for the latest full-run grid and verdicts.
# Also hosts the SmartArray shape tests (arr-* rows): both libraries share this
# harness, one matrix covers both repos.
# No Windows ARM cell: php.net ships no ARM64 Windows builds.
on:
  workflow_dispatch:
    inputs:
      os:
        description: 'Runner (blank = all)'
        required: false
        type: choice
        options:
          - ''
          - ubuntu-latest
          - ubuntu-24.04-arm
          - windows-latest
          - macos-15-intel
          - macos-latest
      php:
        description: 'PHP version (blank = all)'
        required: false
        type: choice
        options: ['', '8.1', '8.2', '8.3', '8.4', '8.5']
      jit:
        description: 'opcache JIT'
        required: false
        default: 'off'
        type: choice
        options: ['off', 'tracing']
      scale:
        description: 'Iteration scale (1.0 = full, 0.3 = quick)'
        required: false
        default: '1.0'
      filter:
        description: 'Comma-separated test ids (blank = all)'
        required: false
        default: ''

jobs:
  matrix:
    name: Load matrix
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.load.outputs.os }}
      php: ${{ steps.load.outputs.php }}
    steps:
      - name: Build matrix from inputs
        id: load
        run: |
          if [ -n "${{ inputs.os }}" ]; then
            echo 'os=["${{ inputs.os }}"]' >> "$GITHUB_OUTPUT"
          else
            echo 'os=["ubuntu-latest", "ubuntu-24.04-arm", "windows-latest", "macos-15-intel", "macos-latest"]' >> "$GITHUB_OUTPUT"
          fi
          if [ -n "${{ inputs.php }}" ]; then
            echo 'php=["${{ inputs.php }}"]' >> "$GITHUB_OUTPUT"
          else
            echo 'php=["8.1", "8.2", "8.3", "8.4", "8.5"]' >> "$GITHUB_OUTPUT"
          fi

  probe:
    name: PHP ${{ matrix.php }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    needs: matrix
    timeout-minutes: 15

    strategy:
      fail-fast: false
      matrix:
        os: ${{ fromJSON(needs.matrix.outputs.os) }}
        php: ${{ fromJSON(needs.matrix.outputs.php) }}

    defaults:
      run:
        shell: bash

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # No xdebug (coverage: none), opcache enabled for CLI to match production
      # opcode optimization. JIT is set explicitly both ways: the runner images
      # ship a non-zero opcache.jit_buffer_size, so leaving the jit input alone
      # would silently benchmark with JIT on and label the run "off"
      - name: Setup PHP ${{ matrix.php }}
        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
        with:
          php-version: ${{ matrix.php }}
          coverage: none
          ini-values: >-
            opcache.enable_cli=1,
            ${{ inputs.jit == 'tracing' && 'opcache.jit=tracing, opcache.jit_buffer_size=64M' || 'opcache.jit=off, opcache.jit_buffer_size=0' }}

      # scale and filter are free-form text: pass them as env vars so the shell
      # gets them as data, never as script source
      - name: Run probe
        env:
          SCALE: ${{ inputs.scale }}
          FILTER: ${{ inputs.filter }}
        run: |
          SLUG="${{ matrix.os }}-php${{ matrix.php }}${{ inputs.jit == 'tracing' && '-jit' || '' }}"
          echo "SLUG=$SLUG" >> "$GITHUB_ENV"
          php .github/scripts/speed-probe.php \
            --json="probe-$SLUG.json" \
            --scale="$SCALE" \
            ${FILTER:+--filter="$FILTER"} \
            >> "$GITHUB_STEP_SUMMARY"

      - name: Upload probe results
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: probe-${{ env.SLUG }}
          path: probe-*.json
          if-no-files-found: ignore

  summary:
    name: Merge comparison grid
    runs-on: ubuntu-latest
    needs: probe
    # Aggregates every matrix job and runs even when some fail, so partial grids
    # still get built; !cancelled() keeps it out of manual cancellations only
    if: ${{ !cancelled() }}

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Setup PHP
        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
        with:
          php-version: '8.1'
          coverage: none

      - name: Download probe results
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          pattern: probe-*
          merge-multiple: true
          path: probes

      - name: Build comparison grid
        run: php .github/scripts/speed-merge.php probes/*.json >> "$GITHUB_STEP_SUMMARY"