php.yml

name: 🧪 CI/CD Pipeline
on:
  push:
    branches:
      - master
      - 'feature/**'
      - 'releases/**'
    tags-ignore:
      - v1.0.0
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches: [ master ]
jobs:
  lint:
    if: github.event.pull_request.draft == false
    timeout-minutes: 10
    runs-on: ubuntu-latest
    name: Code Quality (Lint & Validate)
    steps:
    - name: 📥 Checkout code
      uses: actions/checkout@v7
    
    - name: 🐘 Setup PHP 8.4
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.4'
        extensions: mbstring, dom, fileinfo
        coverage: none
        tools: composer:v2

    - name: 📦 Cache Composer packages
      uses: actions/cache@v6
      with:
        path: vendor
        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-

    - name: 📦 Install dependencies
      run: composer install --prefer-dist --no-progress

    - name: ✅ Validate composer files
      run: composer validate --strict

    - name: 🎨 Check coding standards
      run: composer run cs

    - name: 🔍 Run PHPStan analysis
      run: composer run phpstan

    - name: 📋 Generate summary
      if: always()
      run: |
        echo "## 🎨 Code Quality Report" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "✅ **PHP Version:** 8.4" >> $GITHUB_STEP_SUMMARY
        echo "✅ **Composer validation:** Passed" >> $GITHUB_STEP_SUMMARY
        echo "✅ **Coding standards:** Passed" >> $GITHUB_STEP_SUMMARY
        echo "✅ **PHPStan analysis:** Passed" >> $GITHUB_STEP_SUMMARY

  test:
    if: github.event.pull_request.draft == false
    timeout-minutes: 30
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        php-versions: ['8.2', '8.3', '8.4']
        imagemagick: ['6', '7']
        exclude:
          # ImageMagick 6 not available via Chocolatey on Windows
          - os: windows-latest
            imagemagick: '6'
          # Only test PHP 8.4 on Windows and macOS to reduce matrix size
          - os: windows-latest
            php-versions: '8.2'
          - os: windows-latest
            php-versions: '8.3'
          - os: macos-latest
            php-versions: '8.2'
          - os: macos-latest
            php-versions: '8.3'
    runs-on: ${{ matrix.os }}
    name: Tests - PHP ${{ matrix.php-versions }} - IM ${{ matrix.imagemagick }} (${{ matrix.os }})
    steps:
    - name: 📥 Checkout code
      uses: actions/checkout@v7
      
    - name: 🐘 Setup PHP ${{ matrix.php-versions }}
      uses: shivammathur/setup-php@v2
      with:
        php-version: ${{ matrix.php-versions }}
        extensions: mbstring, dom, fileinfo
        ini-values: memory_limit=256M
        coverage: ${{ matrix.os == 'ubuntu-latest' && matrix.php-versions == '8.4' && matrix.imagemagick == '7' && 'xdebug' || 'none' }}
        tools: composer:v2

    - name: 💾 Cache ImageMagick (Windows)
      if: runner.os == 'Windows'
      id: cache-imagemagick-windows
      uses: actions/cache@v6
      with:
        path: C:\ProgramData\chocolatey\lib\imagemagick
        key: ${{ runner.os }}-imagemagick-${{ matrix.imagemagick }}-${{ hashFiles('.github/workflows/php.yml') }}

    - name: 📦 Cache Composer packages
      uses: actions/cache@v6
      with:
        path: vendor
        key: ${{ runner.os }}-php-${{ matrix.php-versions }}-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-${{ matrix.php-versions }}-
          ${{ runner.os }}-php-

    - name: 🎨 Install ImageMagick ${{ matrix.imagemagick }}
      run: |
        if [ "$RUNNER_OS" == "Linux" ]; then
          sudo apt-get update
          if [ "${{ matrix.imagemagick }}" == "6" ]; then
            sudo apt-get install -y imagemagick
          else
            # Install ImageMagick 7 AppImage from the official GitHub releases
            IM_VERSION=7.1.2-34
            wget -q "https://github.com/ImageMagick/ImageMagick/releases/download/${IM_VERSION}/ImageMagick-${IM_VERSION}-gcc-x86_64.AppImage" -O /tmp/magick
            sudo install -m 755 /tmp/magick /usr/local/bin/magick
            # Ubuntu 24.04 runners lack FUSE, so let the AppImage extract itself instead of mounting
            echo "APPIMAGE_EXTRACT_AND_RUN=1" >> "$GITHUB_ENV"
          fi
        elif [ "$RUNNER_OS" == "macOS" ]; then
          if [ "${{ matrix.imagemagick }}" == "6" ]; then
            brew install imagemagick@6
          else
            # Always reinstall to ensure dependencies are present
            brew install imagemagick
          fi
        elif [ "$RUNNER_OS" == "Windows" ]; then
          # Check if already installed
          if command -v magick &> /dev/null; then
            echo "ImageMagick already installed"
          elif [ "${{ steps.cache-imagemagick-windows.outputs.cache-hit }}" != "true" ]; then
            choco install imagemagick -y --no-progress
          fi
        fi
      shell: bash
      continue-on-error: false

    - name: 📦 Install dependencies
      run: composer install --prefer-dist --no-progress

    - name: ✅ Verify ImageMagick installation
      id: verify-imagemagick
      run: |
        if command -v magick &> /dev/null; then
          magick -version
        elif command -v convert &> /dev/null; then
          convert -version
        else
          echo "ImageMagick not found!"
          exit 1
        fi
      shell: bash
      continue-on-error: true

    - name: 🔧 Set ImageMagick path (Linux/macOS)
      if: runner.os != 'Windows' && success()
      run: |
        if [ "$RUNNER_OS" == "Linux" ]; then
          if [ "${{ matrix.imagemagick }}" == "6" ]; then
            echo "IMAGEMAGICK_PATH=/usr/bin/" >> $GITHUB_ENV
          else
            echo "IMAGEMAGICK_PATH=/usr/local/bin/" >> $GITHUB_ENV
          fi
        elif [ "$RUNNER_OS" == "macOS" ]; then
          if [ "${{ matrix.imagemagick }}" == "6" ]; then
            MAGICK_PATH=$(brew --prefix imagemagick@6)/bin
            echo "IMAGEMAGICK_PATH=${MAGICK_PATH}/" >> $GITHUB_ENV
          else
            MAGICK_PATH=$(dirname $(which magick))
            echo "IMAGEMAGICK_PATH=${MAGICK_PATH}/" >> $GITHUB_ENV
          fi
        fi
      shell: bash

    - name: 🔧 Set ImageMagick path (Windows)
      if: runner.os == 'Windows'
      run: |
        $magickPath = (Get-Command magick).Source | Split-Path
        echo "IMAGEMAGICK_PATH=$magickPath/" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
      shell: pwsh

    - name: 🧪 Run unit tests (without coverage)
      if: matrix.os != 'ubuntu-latest' || matrix.php-versions != '8.4' || matrix.imagemagick != '7'
      run: composer run unit -- --no-coverage

    - name: 🧪 Run unit tests (with coverage)
      if: matrix.os == 'ubuntu-latest' && matrix.php-versions == '8.4' && matrix.imagemagick == '7'
      run: composer run unit
      env:
        XDEBUG_MODE: coverage

    - name: 📊 Upload coverage report
      if: matrix.os == 'ubuntu-latest' && matrix.php-versions == '8.4' && matrix.imagemagick == '7'
      uses: actions/upload-artifact@v7
      with:
        name: coverage-ubuntu-latest-8.4
        path: coverage/

    - name: 📋 Generate test summary
      if: always()
      run: |
        echo "## 🧪 Test Results - PHP ${{ matrix.php-versions }} - IM ${{ matrix.imagemagick }} on ${{ matrix.os }}" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "| Component | Status |" >> $GITHUB_STEP_SUMMARY
        echo "|-----------|--------|" >> $GITHUB_STEP_SUMMARY
        echo "| PHP Version | ${{ matrix.php-versions }} |" >> $GITHUB_STEP_SUMMARY
        echo "| Platform | ${{ matrix.os }} |" >> $GITHUB_STEP_SUMMARY
        echo "| ImageMagick | ${{ matrix.imagemagick }} (${{ steps.verify-imagemagick.outcome == 'success' && '✅ Installed' || '⚠️ Check required' }}) |" >> $GITHUB_STEP_SUMMARY
      shell: bash
        
    - name: 📋 Add coverage info to summary
      if: always() && matrix.os == 'ubuntu-latest' && matrix.php-versions == '8.4' && matrix.imagemagick == '7'
      run: echo "| Coverage | ✅ Generated |" >> $GITHUB_STEP_SUMMARY
      shell: bash
      
    - name: 📋 Add coverage skipped to summary  
      if: always() && (matrix.os != 'ubuntu-latest' || matrix.php-versions != '8.4' || matrix.imagemagick != '7')
      run: echo "| Coverage | ⏭️ Skipped |" >> $GITHUB_STEP_SUMMARY
      shell: bash

  docs:
    name: Build Documentation
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
    - name: 📥 Checkout code
      uses: actions/checkout@v7
    
    - name: 🟢 Setup Node.js 24
      uses: actions/setup-node@v7
      with:
        node-version: '24'
        cache: 'npm'
    
    - name: 📚 Build documentation site
      run: |
        npm install
        npm run docs:build 

    - name: 💾 Save documentation artifact
      uses: actions/upload-artifact@v7
      with:
        name: docs
        path: docs/.vuepress/dist

    - name: 📋 Generate documentation summary
      if: always()
      run: |
        echo "## 📚 Documentation Build" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "✅ Documentation site generated successfully" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "**Build Tool:** VuePress 2.0" >> $GITHUB_STEP_SUMMARY
        echo "**Node.js Version:** 24" >> $GITHUB_STEP_SUMMARY

  publish:
    name: Publish to GitHub Pages
    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
    needs: [docs, test]
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v7
      with:
        ref: gh-pages
        persist-credentials: false
        fetch-depth: 0
        
    - name: 🗑️ Remove old coverage
      run: if [ -d ./coverage ] ; then rm -r ./coverage; fi
      
    - name: 📥 Download coverage report
      uses: actions/download-artifact@v8
      with:
        name: coverage-ubuntu-latest-8.4
        path: coverage
        
    - name: 📥 Download documentation
      uses: actions/download-artifact@v8
      with:
        name: docs
        path: .
        
    - name: 📄 Ensure .nojekyll exists
      run: |
        if [ ! -f .nojekyll ]; then
          touch .nojekyll
        fi
        
    - name: 📝 Commit changes
      run: |
        git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
        git config --local user.name "github-actions[bot]"
        git add -A
        git commit -m "Updated documentation"
        
    - name: 🚀 Push to GitHub Pages
      uses: ad-m/github-push-action@master
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        branch: gh-pages
    - name: ��� Generate publish summary
      if: always()
      run: |
        echo "## ��� GitHub Pages Deployment" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "✅ Successfully deployed to GitHub Pages" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "��� **Site URL:** https://localgod.github.io/karla/" >> $GITHUB_STEP_SUMMARY
        echo "��� **Coverage Report:** https://localgod.github.io/karla/coverage/" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "_Deployment completed at $(date -u +'%Y-%m-%d %H:%M:%S UTC')_" >> $GITHUB_STEP_SUMMARY