IP-8351: Laravel 12 Support

[mjwallace1989]

✅ Upgrade Libraries for Laravel 12 + CI Matrix + PHPUnit Attributes

Main Task

These instructions apply to all PHP libraries in the org. Copy into your issue/PR template or an AI agent prompt.
Notes:

• For Path A (Lightweight), list all illuminate/* components used by the package in the --with lines.
• For Path B (Testbench).
• Do not introduce orchestra/testbench to repos that don't already need it.

---

1) Composer changes (Laravel 12 support; drop 10)

• In composer.json, update all Laravel constraints:
  • For component packages:
    • "illuminate/*": "^11.0|^12.0" (remove any 10.*)
  • If the repo uses the metapackage:
    • "laravel/framework": "^11.0|^12.0"
• Ensure PHP allows newest versions:
  • "php": "^8.3|^8.4"
• Keep dependency graph minimal:
  • Do not add laravel/framework or orchestra/testbench if the repo only needs illuminate/*.

---

2) PHPUnit & tests

• Require PHPUnit 10 or 11 in require-dev:
  • "phpunit/phpunit": "^10.0|^11.0"
• Avoid updating unless necessary. e.g., if already running 10, do not update. if running 4, update to 11, not 10.
• Check for test cases that use a docblock style @test to require running. These will be test case methods that do not begin with the word test.
• For tests that would not otherwise run, add to each test file:

  use PHPUnit\Framework\Attributes\Test;

  • Add #[Test] above every test method in the file.
  • IMPORTANT: ONLY MAKE THIS ATTRIBUTE CHANGE IF TESTS IN THE FILE WOULD NOT OTHERWISE RUN.
• Common modernizations (only if present):
  • setExpectedException* → $this->expectException*
  • assertRegExp → assertMatchesRegularExpression
  • assertInternalType → assertIs* variants

---

3) CI: Matrix across PHP & Laravel

Use one GitHub Actions workflow per repo with a matrix:

• PHP: 8.3, 8.4
• Laravel: 11, 12
• Dependency strategy: Choose the appropriate path based on your package requirements:
  • If orchestra/testbench is in require-dev or tests extend Orchestra\Testbench\TestCase, use Path B: Testbench.
  • Otherwise use Path A: Lightweight with illuminate/* components.

.github/workflows/tests.yml (Path A: Lightweight)

name: Tests
on:
  push:
    branches: [ "**" ]
  pull_request:

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        php: ["8.3", "8.4"]
        laravel: ["11", "12"]

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          coverage: none
          tools: composer
          extensions: json, mbstring, ctype, openssl, tokenizer, pdo, curl

      - name: Validate composer.json
        run: composer validate --no-check-publish

      - name: Install deps for Laravel ${{ matrix.laravel }}
        shell: bash
        env: # Only include composer auth if the package already has github workflow files that user composer auth
          COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{secrets.COMPOSER_PACKAGES_DEPLOY_KEY}}"} }' # [tl! **]
        run: |
          # Add/adjust each illuminate component this library requires:
          # Example includes support & database; add others if present.
          composer update --no-interaction --prefer-dist --ansi \
            --with "illuminate/support:^${{ matrix.laravel }}" \
            --with "illuminate/database:^${{ matrix.laravel }}" \
            --with-all-dependencies

      - name: Run tests
        run: vendor/bin/phpunit --no-coverage

.github/workflows/tests.yml (Path B: Testbench)

name: Tests
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        php: [8.3, 8.4]
        laravel: ['^11.0', '^12.0']
        dependency-version: [prefer-stable]
        include:
          - laravel: "^12.0"
            testbench: 10.*
          - laravel: "^11.0"
            testbench: 9.*

    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }} - ${{ matrix.dependency-version }}

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: curl, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, iconv
          coverage: xdebug

      - name: Setup problem matchers
        run: |
          echo "::add-matcher::${{ runner.tool_cache }}/php.json"
          echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"

      - name: Install dependencies
        env: # Only include composer auth if the package already has github workflows that use composer auth
          COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{secrets.COMPOSER_PACKAGES_DEPLOY_KEY}}"} }' # [tl! **]
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
          composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction

      - name: Execute tests
        run: vendor/bin/phpunit

Notes:

• For lightweight libraries, list all illuminate/* components used by the package in the --with lines.
• Do not introduce orchestra/testbench to repos that don't already need it.
• Only include COMPOSER_AUTH in the composer build step if the repository already has github workflows that use composer auth.

---

4) Composer.lock policy (libraries only)

• Do not commit or track composer.lock in libraries.
• If present, remove and add to .gitignore

---

5) Acceptance criteria (definition of done)

• All illuminate/* (or laravel/framework) constraints allow ^11.0|^12.0 and do not allow 10.x.
• PHP constraint allows 8.3 and 8.4 (via ^8.3|^8.4 ).
• phpunit/phpunit is ^10.0|^11.0 in require-dev.
• All tests are annotated with #[Test] (and import use PHPUnit\Framework\Attributes\Test;).
• Single GitHub Actions workflow runs a matrix on PHP 8.3/8.4 and Laravel 11/12.
• No composer.lock in the repo; it is ignored by Git.

---

IMPORTANT: Minimize changes as much as possible.

• Do not update pint, unless absolutely necessary for package conflict resolution, as pint minor versions contain rule changes.
• Do not apply changes to codestyle unless absolutely necessary.