4.7.6 Ready code

.gitattributes

@@ -24,7 +24,6 @@ utils/                       export-ignore
 .php-cs-fixer.user-guide.php export-ignore
 structarmed-baseline.php     export-ignore
 structarmed.php              export-ignore
-phpmetrics.json              export-ignore
 phpstan-baseline.php         export-ignore
 phpstan-bootstrap.php        export-ignore
 phpstan.dist.neon            export-ignore

.github/copilot-instructions.md

@@ -23,8 +23,15 @@ Prioritize actionable findings involving:
 ## Review behavior
 
 - Determine the PR base branch and apply the compatibility policy from
-  `AGENTS.md`. If the base branch cannot be determined, assume `develop`
-  and state that assumption.
+  `AGENTS.md`. When it is not visible, read it from the title prefix and
+  the labels as `AGENTS.md` describes, and otherwise assume `develop` and
+  state that assumption.
+- Before reporting a compatibility break, confirm the symbol exists in the
+  latest tagged release. A symbol introduced on the base branch since that
+  release is unreleased and may change freely, as `AGENTS.md` describes.
+- Do not report a PHPStan suppression or baseline entry covered by the
+  exceptions in `AGENTS.md`, or a missing reset of state that
+  `CIUnitTestCase::tearDown()` already restores.
 - Do not report formatting-only issues already enforced by PHP-CS-Fixer.
 - Every finding should identify a concrete failure scenario and the
   affected code.

.github/instructions/tests.instructions.md

@@ -14,6 +14,8 @@ applyTo: "tests/**/*.php"
   Avoid testing private implementation details.
 - Restore services, factories, environment variables, superglobals, handlers,
   locale, time-related state, and other global state modified by a test.
+  Check `CIUnitTestCase::tearDown()` first: a test need not repeat the
+  resets it already performs.
 - Tests must not depend on execution order or state left by another test.
 - Do not replace a meaningful assertion with a weaker assertion to make a test
   pass.

.github/workflows/deploy-apidocs.yml

@@ -44,7 +44,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: '8.2'
           tools: phive

.github/workflows/deploy-distributables.yml

@@ -172,7 +172,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: '3.12'
 

.github/workflows/deploy-userguide-latest.yml

@@ -30,13 +30,13 @@ jobs:
           persist-credentials: false
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: '8.2'
           coverage: none
 
       - name: Setup Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: '3.12'
 
@@ -59,7 +59,7 @@ jobs:
 
       # Create an artifact of the html output
       - name: Upload artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: HTML Documentation
           path: user_guide_src/build/html/

.github/workflows/reusable-coveralls.yml

@@ -22,14 +22,14 @@ jobs:
           persist-credentials: false
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ inputs.php-version }}
           tools: composer
           coverage: xdebug
 
       - name: Download coverage files
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           path: build/cov
 
@@ -46,10 +46,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ steps.composer-cache.outputs.COMPOSER_CACHE_FILES_DIR }}
-          key: ${{ github.job }}-php-${{ inputs.php-version }}-${{ hashFiles('**/composer.*') }}
+          key: composer-php-${{ inputs.php-version }}-${{ hashFiles('**/composer.json') }}
           restore-keys: |
-            ${{ github.job }}-php-${{ inputs.php-version }}-
-            ${{ github.job }}-
+            composer-php-${{ inputs.php-version }}-
+            composer-
 
       - name: Cache PHPUnit's static analysis cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0

.github/workflows/reusable-phpunit-test.yml

@@ -175,7 +175,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ inputs.php-version }}
           tools: composer
@@ -195,11 +195,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ steps.setup-env.outputs.COMPOSER_CACHE_FILES_DIR }}
-          key: ${{ inputs.job-id || github.job }}-php-${{ inputs.php-version }}-db-${{ inputs.db-platform || 'none' }}-${{ hashFiles('**/composer.*') }}
+          key: composer-php-${{ inputs.php-version }}-${{ hashFiles('**/composer.json') }}
           restore-keys: |
-            ${{ inputs.job-id || github.job }}-php-${{ inputs.php-version }}-db-${{ inputs.db-platform || 'none' }}-
-            ${{ inputs.job-id || github.job }}-php-${{ inputs.php-version }}-
-            ${{ inputs.job-id || github.job }}-
+            composer-php-${{ inputs.php-version }}-
+            composer-
 
       - name: Cache PHPUnit's static analysis cache
         if: ${{ inputs.enable-artifact-upload }}
@@ -233,7 +232,7 @@ jobs:
 
       - name: Upload coverage results as artifact
         if: ${{ inputs.enable-artifact-upload }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: ${{ steps.setup-env.outputs.ARTIFACT_NAME }}
           path: build/cov/coverage-${{ steps.setup-env.outputs.ARTIFACT_NAME }}.cov

.github/workflows/reusable-serviceless-phpunit-test.yml

@@ -72,7 +72,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ inputs.php-version }}
           tools: composer
@@ -92,10 +92,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ steps.setup-env.outputs.COMPOSER_CACHE_FILES_DIR }}
-          key: ${{ inputs.job-id || github.job }}-php-${{ inputs.php-version }}-${{ hashFiles('**/composer.*') }}
+          key: composer-php-${{ inputs.php-version }}-${{ hashFiles('**/composer.json') }}
           restore-keys: |
-            ${{ inputs.job-id || github.job }}-php-${{ inputs.php-version }}-
-            ${{ inputs.job-id || github.job }}-
+            composer-php-${{ inputs.php-version }}-
+            composer-
 
       - name: Cache PHPUnit's static analysis cache
         if: ${{ inputs.enable-artifact-upload }}
@@ -127,7 +127,7 @@ jobs:
 
       - name: Upload coverage results as artifact
         if: ${{ inputs.enable-artifact-upload }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: ${{ steps.setup-env.outputs.ARTIFACT_NAME }}
           path: build/cov/coverage-${{ steps.setup-env.outputs.ARTIFACT_NAME }}.cov

.github/workflows/run-carson.yml

@@ -32,7 +32,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Run Carson
-        uses: NexusPHP/carson@cb35604ab330c2e44dba673fcef712c78e75f858 # v1.7.0
+        uses: NexusPHP/carson@53c45cf25e2303bc503209f8b5dd9107f27b2e8f # v1.8.0
         with:
           app_id: ${{ secrets.CARSON_APP_ID }}
           private_key: ${{ secrets.CARSON_PRIVATE_KEY }}

.github/workflows/test-autoreview.yml

@@ -30,79 +30,3 @@ jobs:
       php-version: '8.2'
       job-id: auto-review-tests
       group-name: AutoReview
-
-  composer-normalize-tests:
-    name: Check normalized composer.json
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
-        with:
-          php-version: '8.2'
-
-      - name: Install dependencies
-        run: composer update
-
-      - name: Run on root composer.json
-        id: normalize-root-composer
-        if: ${{ always() }}
-        run: |
-          echo "ROOT_COMPOSER_RESULT<<RCR" >> $GITHUB_OUTPUT
-          echo "$(composer normalize)" >> $GITHUB_OUTPUT
-          echo "RCR" >> $GITHUB_OUTPUT
-
-      - name: Run on framework composer.json
-        id: normalize-framework-composer
-        if: ${{ always() }}
-        working-directory: admin/framework
-        run: |
-          echo "FRAMEWORK_COMPOSER_RESULT<<FCR" >> $GITHUB_OUTPUT
-          echo "$(composer normalize)" >> $GITHUB_OUTPUT
-          echo "FCR" >> $GITHUB_OUTPUT
-
-      - name: Run on starter composer.json
-        id: normalize-starter-composer
-        if: ${{ always() }}
-        working-directory: admin/starter
-        run: |
-          echo "STARTER_COMPOSER_RESULT<<SCR" >> $GITHUB_OUTPUT
-          echo "$(composer normalize)" >> $GITHUB_OUTPUT
-          echo "SCR" >> $GITHUB_OUTPUT
-
-      - name: Analyse normalization results
-        run: |
-          if [[ '${{ steps.normalize-root-composer.conclusion }}' == 'failure' ]]; then
-            echo 'Normalization of root composer.json encountered a problem.';
-            echo 'Please run it locally: `composer normalize`';
-            exit 1;
-          fi
-
-          if [[ ${{ contains(steps.normalize-root-composer.outputs.ROOT_COMPOSER_RESULT, 'Successfully normalized') }} == true ]]; then
-            echo 'Root composer.json is not yet normalized.';
-            exit 1;
-          fi
-
-          if [[ '${{ steps.normalize-framework-composer.conclusion }}' == 'failure' ]]; then
-            echo 'Normalization of framework composer.json encountered a problem.';
-            echo 'Please run it locally: `composer normalize -d admin/framework`';
-            exit 1;
-          fi
-
-          if [[ ${{ contains(steps.normalize-framework-composer.outputs.FRAMEWORK_COMPOSER_RESULT, 'Successfully normalized') }} == true ]]; then
-            echo 'Framework composer.json is not yet normalized.';
-            exit 1;
-          fi
-
-          if [[ '${{ steps.normalize-starter-composer.conclusion }}' == 'failure' ]]; then
-            echo 'Normalization of starter composer.json encountered a problem.';
-            echo 'Please run it locally: `composer normalize -d admin/starter`';
-            exit 1;
-          fi
-
-          if [[ ${{ contains(steps.normalize-starter-composer.outputs.STARTER_COMPOSER_RESULT, 'Successfully normalized') }} == true ]]; then
-            echo 'Starter composer.json is not yet normalized.';
-            exit 1;
-          fi

.github/workflows/test-coding-standards.yml

@@ -38,7 +38,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: ${{ matrix.php-version }}
           extensions: tokenizer
@@ -52,10 +52,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ steps.composer-cache.outputs.COMPOSER_CACHE_FILES_DIR }}
-          key: ${{ runner.os }}-${{ matrix.php-version }}-${{ hashFiles('**/composer.lock') }}
+          key: composer-php-${{ matrix.php-version }}-${{ hashFiles('**/composer.json') }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.php-version }}-
-            ${{ runner.os }}-
+            composer-php-${{ matrix.php-version }}-
+            composer-
 
       - name: Install dependencies
         run: composer update --ansi --no-interaction ${{ matrix.composer-option }}

.github/workflows/test-composer-normalize.yml

@@ -0,0 +1,54 @@
+name: Composer Normalize
+
+on:
+  pull_request:
+    paths:
+      - '**/composer.json'
+      - '.github/workflows/test-composer-normalize.yml'
+  push:
+    paths:
+      - '**/composer.json'
+      - '.github/workflows/test-composer-normalize.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  composer-normalize:
+    name: Check normalized composer.json
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
+        with:
+          php-version: '8.2'
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --ansi --no-interaction --working-dir=utils
+
+      - name: Run on root composer.json
+        if: ${{ !cancelled() }}
+        run: composer normalize --ansi --dry-run --working-dir=utils "$GITHUB_WORKSPACE/composer.json"
+
+      - name: Run on framework composer.json
+        if: ${{ !cancelled() }}
+        run: composer normalize --ansi --dry-run --working-dir=utils "$GITHUB_WORKSPACE/admin/framework/composer.json"
+
+      - name: Run on starter composer.json
+        if: ${{ !cancelled() }}
+        run: composer normalize --ansi --dry-run --working-dir=utils "$GITHUB_WORKSPACE/admin/starter/composer.json"
+
+      - name: Run on utils composer.json
+        if: ${{ !cancelled() }}
+        run: composer normalize --ansi --dry-run --working-dir=utils

.github/workflows/test-phpstan.yml

@@ -49,7 +49,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: '8.2'
           extensions: intl
@@ -69,8 +69,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ${{ steps.composer-cache.outputs.COMPOSER_CACHE_FILES_DIR }}
-          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
-          restore-keys: ${{ runner.os }}-composer-
+          key: composer-php-8.2-${{ hashFiles('**/composer.json') }}
+          restore-keys: |
+            composer-php-8.2-
+            composer-
 
       - name: Create PHPStan result cache directory
         run: mkdir -p build/phpstan
@@ -79,8 +81,8 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: build/phpstan
-          key: ${{ runner.os }}-phpstan-${{ github.sha }}
-          restore-keys: ${{ runner.os }}-phpstan-
+          key: phpstan-${{ hashFiles('**/*.php', '**/*.neon', 'composer.json') }}
+          restore-keys: phpstan-
 
       - name: Install dependencies
         run: composer update --ansi --no-interaction