diff --git a/.github/SECURITY.md b/.github/SECURITY.md
new file mode 100644
index 0000000..2b3ce36
--- /dev/null
+++ b/.github/SECURITY.md
@@ -0,0 +1,23 @@
+# Security Policy
+
+## Reporting Security Issues
+If you believe you have found a security vulnerability in any MacPaw-owned repository, please report it to us through coordinated disclosure.
+
+Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
+
+Instead, please send an email to `security[@]macpaw.com`.
+
+Please include as much of the information listed below as you can to help us better understand and resolve the issue:
+
+- The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+## Policy
+See MacPaw's [Vulnerability Disclosure Policy](https://macpaw.com/vulnerability-disclosure-policy)
diff --git a/.github/workflows/release-reusable.yml b/.github/workflows/release-reusable.yml
new file mode 100644
index 0000000..749793c
--- /dev/null
+++ b/.github/workflows/release-reusable.yml
@@ -0,0 +1,73 @@
+name: Release
+
+on:
+  workflow_call:
+    secrets:
+      GH_TOKEN:
+        description: 'Token for release'
+        required: true
+    inputs:
+      dry_run:
+        description: 'Dry run (no release will be created)'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  discussions: write
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+
+      - name: Semantic Release
+        uses: cycjimmy/semantic-release-action@v4
+        id: semantic
+        with:
+          dry_run: ${{ inputs.dry_run || false }}
+          extra_plugins: |
+            @semantic-release/changelog@6.0.3
+            @semantic-release/git@10.0.1
+            conventional-changelog-conventionalcommits@7.0.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+
+      - name: Summary
+        if: steps.semantic.outputs.new_release_published == 'true'
+        run: |
+          echo "## 🎉 Release Created Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **Version:** ${{ steps.semantic.outputs.new_release_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Tag:** v${{ steps.semantic.outputs.new_release_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Channel:** ${{ steps.semantic.outputs.new_release_channel }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Release Notes:** Auto-generated by semantic-release" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "🔗 [View Release](https://github.com/${{ github.repository }}/releases/tag/v${{ steps.semantic.outputs.new_release_version }})" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📝 Release Notes" >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.semantic.outputs.new_release_notes }}" >> $GITHUB_STEP_SUMMARY
+
+      - name: No Release Summary
+        if: steps.semantic.outputs.new_release_published != 'true'
+        run: |
+          echo "## ℹ️ No Release Created" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "No new version was released. This could be because:" >> $GITHUB_STEP_SUMMARY
+          echo "- No commits since last release with valid conventional commit messages" >> $GITHUB_STEP_SUMMARY
+          echo "- All commits are non-release types (chore, docs, style, refactor, test)" >> $GITHUB_STEP_SUMMARY
+          echo "- Running in dry-run mode" >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..cd0f2c4
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - next
+      - beta
+      - alpha
+      - '[0-9]+.x'
+      - '[0-9]+.[0-9]+.x'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run (no release will be created)'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    name: Release
+    uses: ./.github/workflows/release-reusable.yml
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    with:
+      dry_run: ${{ inputs.dry_run || false }}
diff --git a/.github/workflows/symfony-php-reusable.yml b/.github/workflows/symfony-php-reusable.yml
index b7858c8..edb4160 100644
--- a/.github/workflows/symfony-php-reusable.yml
+++ b/.github/workflows/symfony-php-reusable.yml
@@ -2,9 +2,35 @@ name: Symfony PHP Reusable Workflow
 
 on:
   workflow_call:
+
+    secrets:
+      CODECOV_TOKEN:
+        description: 'Token for Codecov uploads (optional)'
+        required: false
+      INFECTION_BADGE_API_KEY:
+        description: 'API key for Infection badge (optional)'
+        required: false
+
     inputs:
+      matrix-include:
+        description: |
+          JSON array of additional matrix combinations to include.
+          Use this to add specific package version combinations or custom configurations.
+          Examples:
+          - Add lowest dependencies test: [{"php":"8.2","dependencies":"lowest"}]
+          - Add code coverage: [{"php":"8.3","symfony":"7.0.*","coverage":"xdebug"}]
+          - Test specific package versions: [{"php":"8.2","symfony":"6.4.*","doctrine/orm":"2.14.*"}]
+        required: false
+        type: string
+        default: '[]'
       versions-matrix:
-        description: 'JSON object with package versions to test. Format: {"php": ["8.2", "8.3"], "symfony/framework-bundle": ["6.4.*", "7.0.*"], "package/name": ["1.0.*"]}'
+        description: |
+          JSON object with package versions to test.
+          - PHP versions create matrix combinations with Symfony versions
+          - Symfony versions are tested with each PHP version
+          - Additional packages are installed from first version in array
+          - Use matrix-include for specific package version combinations
+          Format: {"php": ["8.2", "8.3"], "symfony/framework-bundle": ["6.4.*", "7.0.*"], "package/name": ["1.0.*"]}
         required: false
         type: string
         default: |
@@ -12,11 +38,6 @@ on:
             "php": ["8.2", "8.3", "8.4"],
             "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]
           }
-      enable-code-coverage:
-        description: 'Enable code coverage reporting'
-        required: false
-        type: boolean
-        default: true
       enable-phpstan:
         description: 'Enable PHPStan static analysis'
         required: false
@@ -52,11 +73,26 @@ on:
         required: false
         type: boolean
         default: true
-      test-lowest-dependencies:
-        description: 'Test with lowest dependencies'
+      enable-coverage-check:
+        description: 'Enable coverage validation and PR comments'
         required: false
         type: boolean
         default: false
+      coverage-threshold:
+        description: 'Minimum code coverage percentage required (0-100)'
+        required: false
+        type: number
+        default: 70
+      coverage-file:
+        description: 'Coverage file name (Clover XML format)'
+        required: false
+        type: string
+        default: 'coverage.xml'
+      phpcov-version:
+        description: 'phpcov PHAR version to download from phar.phpunit.de (e.g. 8.2 -> phpcov-8.2.phar)'
+        required: false
+        type: string
+        default: '8.2'
       phpstan-level:
         description: 'PHPStan level (0-9 or max)'
         required: false
@@ -72,6 +108,11 @@ on:
         required: false
         type: string
         default: 'mbstring, json'
+      php-version-quality-tools:
+        description: 'PHP version to use for quality tools (PHPStan, PHPCS, Rector, Infection, etc.)'
+        required: false
+        type: string
+        default: '8.3'
       matrix-exclude:
         description: 'JSON array of matrix combinations to exclude (e.g. [{"php": "8.1", "symfony/framework-bundle": "7.0.*"}]). Default excludes Symfony 7.x with PHP < 8.2'
         required: false
@@ -131,19 +172,17 @@ on:
         required: false
         type: string
         default: ''
-    secrets:
-      codecov-token:
-        description: 'Codecov token for coverage upload'
-        required: false
 
 env:
   COMPOSER_ROOT_VERSION: "1.0.0"
 
 jobs:
+
+
   commitlint:
     name: Commit Lint
     runs-on: ubuntu-latest
-    if: inputs.enable-commitlint
+    if: inputs['enable-commitlint']
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -177,10 +216,11 @@ jobs:
             npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
           fi
 
+
   composer-validate:
     name: Composer Validate
     runs-on: ubuntu-latest
-    if: inputs.enable-composer-validate
+    if: inputs['enable-composer-validate']
     timeout-minutes: 5
     steps:
       - name: Checkout code
@@ -189,17 +229,18 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: none
 
       - name: Validate composer.json and composer.lock
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: composer validate --strict --no-check-publish
 
+
   phpcs:
     name: PHP_CodeSniffer
     runs-on: ubuntu-latest
-    if: inputs.enable-phpcs
+    if: inputs['enable-phpcs']
     timeout-minutes: 10
     steps:
       - name: Checkout code
@@ -208,13 +249,13 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: none
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }} xdebug
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -237,10 +278,11 @@ jobs:
             vendor/bin/phpcs
           fi
 
+
   php-cs-fixer:
     name: PHP-CS-Fixer
     runs-on: ubuntu-latest
-    if: inputs.enable-php-cs-fixer
+    if: inputs['enable-php-cs-fixer']
     timeout-minutes: 10
     steps:
       - name: Checkout code
@@ -249,13 +291,13 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: none
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }}
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -270,18 +312,19 @@ jobs:
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Run PHP-CS-Fixer
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: |
-          if [ -n "${{ inputs.php-cs-fixer-config }}" ]; then
-            vendor/bin/php-cs-fixer fix --dry-run --diff --verbose --config=${{ inputs.php-cs-fixer-config }}
+          if [ -n "${{ inputs['php-cs-fixer-config'] }}" ]; then
+            vendor/bin/php-cs-fixer fix --dry-run --diff --verbose --config=${{ inputs['php-cs-fixer-config'] }}
           else
             vendor/bin/php-cs-fixer fix --dry-run --diff --verbose
           fi
 
+
   phpstan:
     name: PHPStan
     runs-on: ubuntu-latest
-    if: inputs.enable-phpstan
+    if: inputs['enable-phpstan']
     timeout-minutes: 10
     steps:
       - name: Checkout code
@@ -290,13 +333,13 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: none
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }}
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -311,18 +354,19 @@ jobs:
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Run PHPStan
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: |
-          if [ -n "${{ inputs.phpstan-config }}" ]; then
-            vendor/bin/phpstan analyse --level=${{ inputs.phpstan-level }} --no-progress -c ${{ inputs.phpstan-config }}
+          if [ -n "${{ inputs['phpstan-config'] }}" ]; then
+            vendor/bin/phpstan analyse --level=${{ inputs['phpstan-level'] }} --no-progress -c ${{ inputs['phpstan-config'] }}
           else
-            vendor/bin/phpstan analyse --level=${{ inputs.phpstan-level }} --no-progress
+            vendor/bin/phpstan analyse --level=${{ inputs['phpstan-level'] }} --no-progress
           fi
 
+
   rector:
     name: Rector
     runs-on: ubuntu-latest
-    if: inputs.enable-rector
+    if: inputs['enable-rector']
     timeout-minutes: 10
     steps:
       - name: Checkout code
@@ -331,13 +375,13 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: none
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }}
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -352,30 +396,158 @@ jobs:
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Run Rector
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: |
-          if [ -n "${{ inputs.rector-config }}" ]; then
-            vendor/bin/rector process --dry-run --config ${{ inputs.rector-config }}
+          if [ -n "${{ inputs['rector-config'] }}" ]; then
+            vendor/bin/rector process --dry-run --config ${{ inputs['rector-config'] }}
           else
             vendor/bin/rector process --dry-run
           fi
 
+
+  generate-matrix:
+    name: Generate Test Matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+      - name: Generate matrix combinations
+        id: generate
+        run: |
+          cat > generate_matrix.py << 'PYTHON_SCRIPT'
+          import json
+          import sys
+          from itertools import product
+
+          # Read inputs
+          versions_matrix = json.loads('''${{ inputs['versions-matrix'] }}''')
+          matrix_include = json.loads('''${{ inputs['matrix-include'] }}''')
+          matrix_exclude = json.loads('''${{ inputs['matrix-exclude'] }}''')
+
+          # Separate PHP from other packages
+          php_versions = versions_matrix.get('php', [])
+          packages = {k: v for k, v in versions_matrix.items() if k != 'php'}
+
+          # Generate Cartesian product of all package versions
+          if not packages:
+              # If no packages, just use PHP versions
+              combinations = [
+                  {
+                      'php': php,
+                      'dependencies': 'highest',
+                      'title': f"PHP {php}"
+                  }
+                  for php in php_versions
+              ]
+          else:
+              package_names = list(packages.keys())
+              package_versions = [packages[name] for name in package_names]
+
+              combinations = []
+              for php in php_versions:
+                  for combo in product(*package_versions):
+                      combination = {
+                          'php': php,
+                          'dependencies': 'highest'
+                      }
+                      # Add each package version to the combination
+                      for i, package_name in enumerate(package_names):
+                          combination[package_name] = combo[i]
+
+                      # Generate title for this combination
+                      title_parts = [f"PHP {php}"]
+                      for i, package_name in enumerate(package_names):
+                          # Shorten package name for display (e.g., "symfony/cache" -> "cache")
+                          short_name = package_name.split('/')[-1] if '/' in package_name else package_name
+                          title_parts.append(f"{short_name} {combo[i]}")
+                      combination['title'] = ', '.join(title_parts)
+
+                      combinations.append(combination)
+
+          # Add matrix-include items and generate titles if missing
+          for include_item in matrix_include:
+              if 'title' not in include_item:
+                  # Generate title for matrix-include items
+                  title_parts = [f"PHP {include_item.get('php', '?')}"]
+                  for key, value in include_item.items():
+                      if key not in ['php', 'dependencies', 'coverage', 'title']:
+                          short_name = key.split('/')[-1] if '/' in key else key
+                          title_parts.append(f"{short_name} {value}")
+                  if include_item.get('dependencies') == 'lowest':
+                      title_parts.append('lowest deps')
+                  if include_item.get('coverage'):
+                      title_parts.append(f"coverage: {include_item['coverage']}")
+                  include_item['title'] = ', '.join(title_parts)
+              combinations.append(include_item)
+
+          # Filter out excluded combinations
+          def _normalize_version(val: str):
+              """
+              Normalize versions so that values with trailing .* behave as a prefix filter.
+              Examples:
+                rule:  "7.3.*" matches combo values "7.3", "7.3.*", "7.3.x", etc. (prefix "7.3")
+                rule:  "7.3"    requires exact match "7.3" (no wildcard semantics)
+              """
+              return val[:-2] if isinstance(val, str) and val.endswith('.*') else val
+
+          def _matches(rule_val, combo_val):
+              # Exact match when rule has no wildcard
+              if not (isinstance(rule_val, str) and rule_val.endswith('.*')):
+                  return combo_val == rule_val
+
+              # Wildcard/prefix match when rule ends with .* (treat as startswith of the prefix)
+              prefix = _normalize_version(rule_val)
+
+              if not isinstance(combo_val, str):
+                  return False
+
+              # Also normalize combo like "7.3.*" to its prefix for matching consistency
+              combo_norm = _normalize_version(combo_val)
+              return str(combo_norm).startswith(str(prefix))
+
+          def should_exclude(combo, exclude_rules):
+              for rule in exclude_rules:
+                  # All keys in rule must match the combo using wildcard-aware semantics
+                  if all(_matches(v, combo.get(k)) for k, v in rule.items()):
+                      return True
+              return False
+
+          excluded = []
+          final_combinations = []
+          for c in combinations:
+              if should_exclude(c, matrix_exclude):
+                  excluded.append(c)
+              else:
+                  final_combinations.append(c)
+
+          # Output as JSON
+          matrix_json = json.dumps({'include': final_combinations})
+          print(f"Generated {len(final_combinations)} test combinations (excluded {len(excluded)})")
+
+          # Write to GITHUB_OUTPUT
+          import os
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f"matrix={matrix_json}\n")
+          PYTHON_SCRIPT
+
+          python3 generate_matrix.py
+
+      - name: Display matrix
+        run: |
+          echo "Generated matrix:"
+          echo '${{ steps.generate.outputs.matrix }}' | jq .
+
+
   unit-tests:
-    name: Unit Tests (PHP ${{ matrix.php }})
+    name: Unit Tests (${{ matrix.title }})
     runs-on: ubuntu-latest
+    needs: generate-matrix
     timeout-minutes: 15
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     strategy:
       fail-fast: false
-      matrix:
-        php: ${{ fromJson(fromJson(inputs.versions-matrix).php) }}
-        dependencies: ['highest']
-        versions-matrix: ['${{ inputs.versions-matrix }}']
-        include:
-          - php: ${{ fromJson(fromJson(inputs.versions-matrix).php)[0] }}
-            dependencies: 'lowest'
-            coverage: ${{ inputs.enable-code-coverage && 'xdebug' || 'none' }}
-            versions-matrix: '${{ inputs.versions-matrix }}'
-        exclude: ${{ fromJson(inputs.matrix-exclude) }}
+      matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
 
     steps:
       - name: Checkout code
@@ -386,11 +558,11 @@ jobs:
         with:
           php-version: ${{ matrix.php }}
           coverage: ${{ matrix.coverage || 'none' }}
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }}${{ matrix.coverage == 'xdebug' && ', xdebug' || '' }}
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -400,60 +572,283 @@ jobs:
           key: ${{ runner.os }}-php-${{ matrix.php }}-composer-${{ hashFiles('**/composer.lock') }}
           restore-keys: ${{ runner.os }}-php-${{ matrix.php }}-composer-
 
-      - name: Apply package version constraints
+      - name: Display matrix combination
+        run: |
+          echo "Testing with following package versions:"
+          echo '${{ toJSON(matrix) }}' | jq .
+
+      - name: Apply package version constraints from matrix
+        id: apply-constraints
         working-directory: ${{ inputs.working-directory }}
         run: |
-          # Parse versions-matrix and apply constraints for all packages except PHP
-          echo "Applying version constraints from matrix..."
-          VERSIONS_JSON='${{ matrix.versions-matrix }}'
-
-          # Extract and apply Symfony constraint if present
-          SYMFONY_VERSION=$(echo "$VERSIONS_JSON" | jq -r '."symfony/framework-bundle"[0] // empty')
-          if [ ! -z "$SYMFONY_VERSION" ]; then
-            echo "Setting Symfony framework-bundle to $SYMFONY_VERSION"
-            composer require "symfony/framework-bundle:$SYMFONY_VERSION" --no-update --no-interaction
-            composer config extra.symfony.require "$SYMFONY_VERSION"
+          echo "Applying package version constraints from matrix combination..."
+
+          # Get all matrix keys except system keys
+          MATRIX_JSON='${{ toJSON(matrix) }}'
+
+          # Extract and apply each package version from matrix
+          # Skip system keys: php, dependencies, coverage, title, description
+          PACKAGES_STR=""
+          PACKAGES_JSON="{}"
+          SYMFONY_VERSION=""
+
+          for package in $(echo "$MATRIX_JSON" | jq -r 'keys[]' | grep -v -E '^(php|dependencies|coverage|title|description)$'); do
+            VERSION=$(echo "$MATRIX_JSON" | jq -r --arg pkg "$package" '.[$pkg]')
+
+            if [ ! -z "$VERSION" ] && [ "$VERSION" != "null" ] && [ "$VERSION" != "" ]; then
+              echo "Setting $package to $VERSION"
+              composer require "$package:$VERSION" --no-update --no-interaction || echo "Warning: Could not set constraint for $package"
+
+              # Set Symfony version globally if this is symfony/framework-bundle
+              if [ "$package" = "symfony/framework-bundle" ]; then
+                echo "Setting Symfony global version constraint"
+                composer config extra.symfony.require "$VERSION" || true
+                SYMFONY_VERSION="$VERSION"
+              fi
+
+              # Build outputs
+              if [ -z "$PACKAGES_STR" ]; then
+                PACKAGES_STR="$package:$VERSION"
+              else
+                PACKAGES_STR="$PACKAGES_STR $package:$VERSION"
+              fi
+              PACKAGES_JSON=$(echo "$PACKAGES_JSON" | jq --arg k "$package" --arg v "$VERSION" '. + {($k): $v}')
+            fi
+          done
+
+          # If Symfony version wasn't set via framework-bundle, try to infer from any symfony/* package in the matrix
+          if [ -z "$SYMFONY_VERSION" ]; then
+            SYMFONY_VERSION=$(echo "$MATRIX_JSON" | jq -r 'to_entries | map(select(.key|test("^symfony/"))) | (.[0].value // "")')
+            if [ -n "$SYMFONY_VERSION" ]; then
+              echo "Inferred Symfony version $SYMFONY_VERSION from symfony/* package; setting extra.symfony.require"
+              composer config extra.symfony.require "$SYMFONY_VERSION" || true
+            fi
           fi
 
-          # Apply constraints for all other packages
-          for package in $(echo "$VERSIONS_JSON" | jq -r 'keys[]' | grep -v '^php$' | grep -v '^symfony/framework-bundle$'); do
-            VERSION=$(echo "$VERSIONS_JSON" | jq -r --arg pkg "$package" '.[$pkg][0]')
-            echo "Setting $package to $VERSION"
-            composer require "$package:$VERSION" --no-update --no-interaction || echo "Warning: Could not set constraint for $package"
-          done
+          echo "✓ Package version constraints applied successfully"
 
-      - name: Install dependencies (highest)
-        if: matrix.dependencies == 'highest'
-        working-directory: ${{ inputs.working-directory }}
-        run: composer update --no-interaction --no-progress --prefer-dist
+          # Export step outputs
+          echo "composer_packages=$PACKAGES_STR" >> "$GITHUB_OUTPUT"
+          echo "composer_packages_json=$(echo "$PACKAGES_JSON" | jq -c '.')" >> "$GITHUB_OUTPUT"
+          echo "symfony_version=$SYMFONY_VERSION" >> "$GITHUB_OUTPUT"
 
-      - name: Install dependencies (lowest)
-        if: matrix.dependencies == 'lowest'
-        working-directory: ${{ inputs.working-directory }}
-        run: composer update --no-interaction --no-progress --prefer-dist --prefer-lowest --prefer-stable
+      - name: Install dependencies
+        working-directory: ${{ inputs['working-directory'] }}
+        env:
+          # Pass detected Symfony version to Composer/Symfony Flex, if any
+          SYMFONY_REQUIRE: ${{ steps.apply-constraints.outputs.symfony_version }}
+        run: |
+          # Make sure Flex is allowed/available (if not already in your workflow)
+          composer global config --no-plugins allow-plugins.symfony/flex true
+          composer global require --no-progress --no-scripts --no-plugins symfony/flex
+          if [ -n "${SYMFONY_REQUIRE}" ]; then
+            echo "Using Symfony constraint: ${SYMFONY_REQUIRE}"
+            composer update --prefer-dist --no-progress --no-interaction          
+          else
+            echo "No SYMFONY_REQUIRE set, using lock file"
+            composer install --prefer-dist --no-progress --no-interaction
+          fi
 
       - name: Run PHPUnit
         if: matrix.coverage != 'xdebug'
-        working-directory: ${{ inputs.working-directory }}
-        run: vendor/bin/phpunit --testdox
+        working-directory: ${{ inputs['working-directory'] }}
+        run: vendor/bin/phpunit --testdox --no-coverage
 
       - name: Run PHPUnit with coverage
         if: matrix.coverage == 'xdebug'
-        working-directory: ${{ inputs.working-directory }}
-        run: vendor/bin/phpunit --testdox --coverage-clover=coverage.xml
+        working-directory: ${{ inputs['working-directory'] }}
+        run: |
+          # Generate both Clover XML (for Codecov and fallback) and raw PHP coverage (for phpcov merge)
+          vendor/bin/phpunit \
+            --testdox \
+            --coverage-clover=${{ inputs['coverage-file'] }} \
+            --coverage-php=coverage.cov
 
       - name: Upload coverage to Codecov
-        if: matrix.coverage == 'xdebug' && secrets.codecov-token != ''
         uses: codecov/codecov-action@v4
+        if: matrix.coverage == 'xdebug' && env.CODECOV_TOKEN != ''
         with:
-          token: ${{ secrets.codecov-token }}
-          files: ${{ inputs.working-directory }}/coverage.xml
+          token: ${{ env.CODECOV_TOKEN }}
+          files: ${{ inputs['working-directory'] }}/${{ inputs['coverage-file'] }}
           fail_ci_if_error: false
 
+      - name: Upload coverage artifact for validation
+        if: matrix.coverage == 'xdebug'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-${{ matrix.php }}-${{ github.run_id }}
+          path: |
+            ${{ inputs['working-directory'] }}/${{ inputs['coverage-file'] }}
+            ${{ inputs['working-directory'] }}/coverage.cov
+          retention-days: 1
+          if-no-files-found: warn
+
+
+  coverage-validation:
+    name: Coverage Validation
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    if: inputs['enable-coverage-check'] && github.event_name == 'pull_request'
+    env:
+      COVERAGE_FILE: ${{ inputs['coverage-file'] }}
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Setup PHP for phpcov
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ inputs['php-version-quality-tools'] }}
+          coverage: none
+
+      - name: Install coverage tools (phpcov PHAR + phpunit-coverage-check)
+        run: |
+          set -e
+          # Download phpcov PHAR for requested version
+          PHPCOV_VERSION="${{ inputs['phpcov-version'] }}"
+          PHPCOV_URL="https://phar.phpunit.de/phpcov-${PHPCOV_VERSION}.phar"
+          echo "Downloading phpcov from ${PHPCOV_URL}"
+          wget -q -O phpcov.phar "$PHPCOV_URL"
+          chmod +x phpcov.phar
+
+          # Install phpunit-coverage-check globally via Composer
+          composer global require --no-interaction --no-progress \
+            rregeer/phpunit-coverage-check:*
+          # Add Composer global bin to PATH for both Composer 1 and 2 locations
+          echo "$HOME/.composer/vendor/bin" >> $GITHUB_PATH
+          echo "$HOME/.config/composer/vendor/bin" >> $GITHUB_PATH
+
+      - name: Download coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-report-*
+          path: coverage-artifacts
+          merge-multiple: false
+        continue-on-error: true
+
+      - name: Merge coverage reports with phpcov
+        id: phpcov-merge
+        run: |
+          set -e
+          if [ ! -d "coverage-artifacts" ] || [ -z "$(ls -A coverage-artifacts || true)" ]; then
+            echo "No coverage artifacts to merge"
+            echo "merged=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Build list of directories that contain raw PHP coverage files produced by PHPUnit (--coverage-php)
+          mapfile -t COVERAGE_DIRS < <(find coverage-artifacts -type f -name "coverage.cov" -exec dirname {} \; | sort -u)
+
+          if [ ${#COVERAGE_DIRS[@]} -eq 0 ]; then
+            echo "No raw PHP coverage files (coverage.cov) found for merging"
+            echo "merged=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          echo "Found ${#COVERAGE_DIRS[@]} coverage directories to merge"
+          printf '%s\n' "${COVERAGE_DIRS[@]}" | sed 's/^/- /'
+
+          # Try merging with phpcov; if it fails, we will fallback later
+          set +e
+          php phpcov.phar merge --clover merged-coverage.xml "${COVERAGE_DIRS[@]}"
+          EXIT_CODE=$?
+          set -e
+
+          if [ $EXIT_CODE -ne 0 ] || [ ! -s merged-coverage.xml ]; then
+            echo "phpcov merge failed or produced empty output; will continue without merged file"
+            echo "merged=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          echo "phpcov merge succeeded"
+          echo "merged=true" >> $GITHUB_OUTPUT
+
+      - name: Parse coverage and validate threshold (coverage-check)
+        id: coverage
+        env:
+          COVERAGE_THRESHOLD: ${{ inputs['coverage-threshold'] }}
+        run: |
+          set -e
+          # Ensure artifacts exist
+          if [ ! -d "coverage-artifacts" ] || [ -z "$(ls -A coverage-artifacts || true)" ]; then
+            echo "⚠️ No coverage artifacts found"
+            echo "coverage=0.0" >> $GITHUB_OUTPUT
+            echo "status=no-coverage" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Determine target files for checking
+          if [ -s "merged-coverage.xml" ]; then
+            TARGETS=("merged-coverage.xml")
+          else
+            mapfile -t TARGETS < <(find coverage-artifacts -type f -name "${{ inputs['coverage-file'] }}")
+          fi
+
+          if [ ${#TARGETS[@]} -eq 0 ]; then
+            echo "⚠️ No Clover XML files found"
+            echo "coverage=0.0" >> $GITHUB_OUTPUT
+            echo "status=no-coverage" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Run coverage-check (from rregeer/phpunit-coverage-check). If multiple files, record minimum coverage and mark failure if any fail.
+          OVERALL_STATUS=success
+          MIN_COVERAGE=""
+          for FILE in "${TARGETS[@]}"; do
+            set +e
+            coverage-check "$FILE" "${COVERAGE_THRESHOLD}" | tee coverage_check_output.txt
+            EXIT_CODE=$?
+            set -e
+            # Extract the current coverage percentage (first percentage in output) strictly from command output only.
+            # Accept optional space before % and comma decimals, normalize to dot.
+            PCT=$(grep -Eo '([0-9]+([\.,][0-9]+)?)\s*%' coverage_check_output.txt | head -n1 | sed -E 's/%//; s/,/./; s/^[[:space:]]+|[[:space:]]+$//g')
+            # If percentage not found in output, default to 0.00 (no file/XML parsing fallback by design)
+            if [ -z "$PCT" ]; then PCT="0.00"; fi
+
+            if [ -z "$MIN_COVERAGE" ]; then
+              MIN_COVERAGE="$PCT"
+            else
+              awk -v a="$MIN_COVERAGE" -v b="$PCT" 'BEGIN { exit !(a+0 > b+0) }' || MIN_COVERAGE="$PCT"
+            fi
+
+            if [ $EXIT_CODE -ne 0 ]; then
+              OVERALL_STATUS=failure
+            fi
+          done
+
+          echo "coverage=${MIN_COVERAGE:-0.00}" >> $GITHUB_OUTPUT
+          echo "status=$OVERALL_STATUS" >> $GITHUB_OUTPUT
+
+      - name: Create or update PR comment
+        uses: peter-evans/create-or-update-comment@v5
+        if: always() && steps.coverage.outputs.status != 'no-coverage'
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            <!-- coverage-validation-report -->
+            ## 📊 Code Coverage Report
+            ${{ steps.coverage.outputs.status == 'success'
+                && format('✅ Coverage: {0}% (min {1}%) — OK', steps.coverage.outputs.coverage, inputs['coverage-threshold'])
+                || format('❌ Coverage: {0}% (min {1}%) — NOT OK', steps.coverage.outputs.coverage, inputs['coverage-threshold'])
+            }}
+
+            ---
+            <sub>Generated by [Macpaw Symfony PHP Reusable Workflow](https://github.com/MacPaw/github-actions)</sub>
+          body-includes: '<!-- coverage-validation-report -->'
+          edit-mode: replace
+
+      - name: Fail if coverage below threshold
+        if: steps.coverage.outputs.status == 'failure'
+        run: |
+          echo "❌ Coverage ${{ steps.coverage.outputs.coverage }}% is below threshold ${{ inputs['coverage-threshold'] }}%"
+          exit 1
+
+
   infection:
     name: Infection Mutation Testing
     runs-on: ubuntu-latest
-    if: inputs.enable-infection
+    if: inputs['enable-infection']
     timeout-minutes: 20
     steps:
       - name: Checkout code
@@ -462,13 +857,13 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: ${{ inputs['php-version-quality-tools'] }}
           coverage: xdebug
-          extensions: ${{ inputs.php-extensions }}
+          extensions: ${{ inputs['php-extensions'] }}
 
       - name: Get Composer cache directory
         id: composer-cache
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache Composer dependencies
@@ -479,15 +874,15 @@ jobs:
           restore-keys: ${{ runner.os }}-composer-
 
       - name: Install dependencies
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Run Infection
-        working-directory: ${{ inputs.working-directory }}
+        working-directory: ${{ inputs['working-directory'] }}
         run: |
-          CMD="vendor/bin/infection --min-msi=${{ inputs.infection-min-msi }} --min-covered-msi=${{ inputs.infection-min-covered-msi }} --threads=4 --no-progress"
-          if [ -n "${{ inputs.infection-config }}" ]; then
-            CMD="$CMD --configuration=${{ inputs.infection-config }}"
+          CMD="vendor/bin/infection --min-msi=${{ inputs['infection-min-msi'] }} --min-covered-msi=${{ inputs['infection-min-covered-msi'] }} --threads=4 --no-progress"
+          if [ -n "${{ inputs['infection-config'] }}" ]; then
+            CMD="$CMD --configuration=${{ inputs['infection-config'] }}"
           fi
           $CMD
         env:
diff --git a/.releaserc.json b/.releaserc.json
new file mode 100644
index 0000000..573d429
--- /dev/null
+++ b/.releaserc.json
@@ -0,0 +1,183 @@
+{
+  "branches": [
+    "main",
+    "master",
+    {
+      "name": "next",
+      "prerelease": true
+    },
+    {
+      "name": "beta",
+      "prerelease": true
+    },
+    {
+      "name": "alpha",
+      "prerelease": true
+    },
+    {
+      "name": "[0-9]+.x",
+      "range": "${name.replace(/\\.x$/, '')}",
+      "channel": "${name}"
+    },
+    {
+      "name": "[0-9]+.[0-9]+.x",
+      "range": "${name.replace(/\\.x$/, '')}",
+      "channel": "${name}"
+    }
+  ],
+  "preset": "conventionalcommits",
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          {
+            "type": "feat",
+            "release": "minor"
+          },
+          {
+            "type": "fix",
+            "release": "patch"
+          },
+          {
+            "type": "perf",
+            "release": "patch"
+          },
+          {
+            "type": "revert",
+            "release": "patch"
+          },
+          {
+            "type": "docs",
+            "scope": "README",
+            "release": "patch"
+          },
+          {
+            "type": "refactor",
+            "release": "patch"
+          },
+          {
+            "type": "style",
+            "release": false
+          },
+          {
+            "type": "chore",
+            "release": false
+          },
+          {
+            "type": "test",
+            "release": false
+          },
+          {
+            "scope": "no-release",
+            "release": false
+          },
+          {
+            "breaking": true,
+            "release": "major"
+          }
+        ],
+        "parserOpts": {
+          "noteKeywords": [
+            "BREAKING CHANGE",
+            "BREAKING CHANGES",
+            "BREAKING"
+          ]
+        }
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            {
+              "type": "feat",
+              "section": "✨ Features"
+            },
+            {
+              "type": "fix",
+              "section": "🐛 Bug Fixes"
+            },
+            {
+              "type": "perf",
+              "section": "⚡ Performance Improvements"
+            },
+            {
+              "type": "revert",
+              "section": "⏪ Reverts"
+            },
+            {
+              "type": "docs",
+              "section": "📚 Documentation"
+            },
+            {
+              "type": "style",
+              "section": "💄 Styles",
+              "hidden": true
+            },
+            {
+              "type": "refactor",
+              "section": "♻️ Code Refactoring"
+            },
+            {
+              "type": "test",
+              "section": "✅ Tests",
+              "hidden": true
+            },
+            {
+              "type": "build",
+              "section": "🏗️ Build System"
+            },
+            {
+              "type": "ci",
+              "section": "👷 CI/CD"
+            },
+            {
+              "type": "chore",
+              "section": "🔧 Maintenance",
+              "hidden": true
+            }
+          ]
+        },
+        "writerOpts": {
+          "commitsSort": [
+            "subject",
+            "scope"
+          ]
+        }
+      }
+    ],
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md",
+        "changelogTitle": "# Changelog\n\nAll notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines."
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false,
+        "failComment": false,
+        "releasedLabels": false,
+        "addReleases": "bottom"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "CHANGELOG.md",
+          "package.json",
+          "package-lock.json",
+          "composer.json",
+          "composer.lock"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}
diff --git a/README.md b/README.md
index f23a5f5..de45a11 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,18 @@ All reusable workflows are located in `.github/workflows` folder
   - ⚡ **Performance Optimized** - Parallel execution, intelligent caching
   - [📚 Detailed Documentation](docs/workflows/symfony-php-reusable.md)
 
+- [release-reusable.yml](.github/workflows/release-reusable.yml) - Fully automated release workflow using semantic-release
+  - 🤖 **Fully Automated** - No manual version bumping or changelog writing required
+  - ✅ **Semantic Versioning** - Automatic version calculation from commit messages
+  - 🏷️ **Auto Tag & Release** - Automatically creates tags and GitHub releases
+  - 📝 **Auto-Generated Changelogs** - Beautiful, categorized release notes
+  - 🎯 **Conventional Commits** - Based on conventional commit standards
+  - 🔀 **Multi-Branch Support** - main/master, next, beta, alpha, maintenance branches
+  - 🛡️ **Safe & Idempotent** - Won't create duplicate releases
+  - 🧪 **Dry Run Mode** - Test releases without publishing
+  - 🔑 **Secure Authentication** - Uses GH_TOKEN repository secret for release operations
+  - [📚 Detailed Documentation](docs/workflows/release.md)
+
 ### Documentation
 
 - [Symfony PHP Reusable Workflow](docs/workflows/symfony-php-reusable.md) - Complete workflow documentation with:
@@ -35,6 +47,23 @@ All reusable workflows are located in `.github/workflows` folder
   - 📊 Analysis of MacPaw's Symfony repositories
   - 📈 Best practices and recommendations
 
+- [Release Workflow](docs/workflows/release.md) - Complete semantic-release documentation with:
+  - 🤖 Fully automated release process using semantic-release
+  - 📝 Conventional commits specification and examples
+  - 🏷️ Automatic version calculation (feat → minor, fix → patch, BREAKING → major)
+  - 🚀 Multiple usage examples (feature, bugfix, breaking changes, pre-releases)
+  - 🔀 Multi-branch release channels (main, beta, alpha, maintenance)
+  - 📊 Auto-generated categorized changelogs
+  - 🧪 Dry run mode for testing releases
+  - 🔑 GH_TOKEN secret configuration and setup guide
+  - 🔐 GitHub App token support for organizations
+  - 🎯 Fine-grained Personal Access Token (PAT) instructions
+  - ⚙️ Configuration via .releaserc.json
+  - 🔧 Comprehensive troubleshooting guide
+  - 📋 Best practices for conventional commits
+  - 🛠️ Advanced configuration and customization examples
+  - 🔄 Migration guide from manual releases
+
 ### Contributing
 
 Contributions are welcome! When adding new features:
@@ -58,4 +87,5 @@ For information about reporting security vulnerabilities, please see our [Securi
 - [MacPaw GitHub Organization](https://github.com/MacPaw/)
 - [GitHub Actions Documentation](https://docs.github.com/en/actions)
 - [Symfony PHP Package reusable workflow](docs/workflows/symfony-php-reusable.md)
+- [Release workflow](docs/workflows/release.md)
 - [Repository Analysis](ANALYSIS.md)
diff --git a/docs/workflows/release.md b/docs/workflows/release.md
new file mode 100644
index 0000000..a83e340
--- /dev/null
+++ b/docs/workflows/release.md
@@ -0,0 +1,785 @@
+# Release Workflow
+
+Automated release workflow using semantic-release for fully automated version management and package publishing.
+
+## Overview
+
+The release workflow uses [semantic-release](https://semantic-release.gitbook.io/) to automate the entire release process based on [Conventional Commits](https://www.conventionalcommits.org/). It automatically determines the next version number, generates release notes, creates GitHub releases, and updates the changelog - all without manual intervention.
+
+## Features
+
+- 🤖 **Fully Automated** - No manual version bumping or changelog writing
+- ✅ **Semantic Versioning** - Automatic version calculation based on commit messages
+- 📝 **Auto-Generated Changelogs** - Beautiful, categorized release notes
+- 🏷️ **Auto Tag & Release** - Automatically creates tags and GitHub releases
+- 🔀 **Multi-Branch Support** - main/master, next, beta, alpha, and maintenance branches
+- 🎯 **Conventional Commits** - Enforces commit message standards
+- 🛡️ **Safe & Idempotent** - Won't create duplicate releases
+- 🧪 **Dry Run Mode** - Test releases without publishing
+- 🔑 **Flexible Token** - Use default or custom GitHub token
+
+## How It Works
+
+1. **Analyze Commits** - Scans commits since last release using Conventional Commits format
+2. **Determine Version** - Calculates next version based on commit types:
+   - `feat:` → Minor version bump (1.0.0 → 1.1.0)
+   - `fix:` → Patch version bump (1.0.0 → 1.0.1)
+   - `BREAKING CHANGE:` → Major version bump (1.0.0 → 2.0.0)
+3. **Generate Changelog** - Creates categorized release notes
+4. **Create Tag** - Creates git tag with version number
+5. **Publish Release** - Creates GitHub release with notes
+6. **Update Files** - Commits CHANGELOG.md back to repository
+
+## Triggers
+
+### 1. Automatic (Push to Branch)
+
+The workflow automatically runs when code is pushed to release branches:
+
+```bash
+# Push to main/master branch
+git push origin main
+
+# Semantic-release will:
+# 1. Analyze commits since last release
+# 2. Determine if a release is needed
+# 3. Calculate next version
+# 4. Create tag and release automatically
+```
+
+**Supported branches:**
+- `main` or `master` - Production releases
+- `next` - Pre-releases for next major version
+- `beta` - Beta pre-releases
+- `alpha` - Alpha pre-releases
+- `N.x` or `N.N.x` - Maintenance releases (e.g., `1.x`, `1.0.x`)
+
+### 2. Manual Trigger (Workflow Dispatch)
+
+Manually trigger the workflow from GitHub Actions UI or CLI:
+
+```bash
+# Using GitHub CLI
+gh workflow run release.yml
+
+# With dry run (no release will be created)
+gh workflow run release.yml -f dry_run=true
+```
+
+## Conventional Commits
+
+Semantic-release requires commits to follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### Commit Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Commit Types and Version Impact
+
+| Type | Description | Version Bump | Example |
+|------|-------------|--------------|---------|
+| `feat` | New feature | **MINOR** (1.0.0 → 1.1.0) | `feat: add dark mode support` |
+| `fix` | Bug fix | **PATCH** (1.0.0 → 1.0.1) | `fix: resolve memory leak` |
+| `perf` | Performance improvement | **PATCH** (1.0.0 → 1.0.1) | `perf: optimize database queries` |
+| `BREAKING CHANGE` | Breaking change | **MAJOR** (1.0.0 → 2.0.0) | See below |
+| `docs` | Documentation only | No release | `docs: update README` |
+| `style` | Code style changes | No release | `style: format code` |
+| `refactor` | Code refactoring | **PATCH** (1.0.0 → 1.0.1) | `refactor: simplify auth logic` |
+| `test` | Test changes | No release | `test: add unit tests` |
+| `chore` | Maintenance tasks | No release | `chore: update dependencies` |
+| `ci` | CI/CD changes | No release | `ci: update workflow` |
+| `build` | Build system changes | No release | `build: update webpack config` |
+
+### Breaking Changes
+
+Any commit with `BREAKING CHANGE:` in the footer triggers a **MAJOR** version bump:
+
+```bash
+feat: redesign authentication API
+
+BREAKING CHANGE: The auth endpoint now requires OAuth2 instead of API keys
+```
+
+Or using the `!` shorthand:
+
+```bash
+feat!: redesign authentication API
+
+The auth endpoint now requires OAuth2 instead of API keys
+```
+
+### Examples
+
+```bash
+# Minor version bump (new feature)
+git commit -m "feat: add user profile export"
+
+# Patch version bump (bug fix)
+git commit -m "fix: resolve null pointer in user service"
+
+# Major version bump (breaking change)
+git commit -m "feat!: migrate to v2 API
+
+BREAKING CHANGE: All API endpoints now require authentication"
+
+# No release (documentation)
+git commit -m "docs: update installation guide"
+
+# No release (chore)
+git commit -m "chore: update dependencies"
+
+# With scope
+git commit -m "feat(api): add pagination support"
+git commit -m "fix(ui): correct button alignment"
+```
+
+## Workflow Configuration
+
+### Secrets
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `GH_TOKEN` | **Yes** (for workflow_dispatch) | GitHub Personal Access Token or GitHub App token for creating releases |
+
+### Workflow Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `dry_run` | No | `false` | Run in dry-run mode (no release created) |
+
+### GitHub Token Setup
+
+The workflow requires a `GH_TOKEN` secret for authentication when creating releases.
+
+**Setup Instructions:**
+
+1. **Create a Personal Access Token (PAT):**
+   - Go to GitHub **Settings → Developer settings → Personal access tokens → Tokens (classic)**
+   - Click **Generate new token (classic)**
+   - Set expiration and select scopes:
+     - ✅ `repo` - Full control of private repositories
+     - ✅ `workflow` - Update GitHub Action workflows (if needed)
+     - ✅ `write:packages` - Upload packages (if publishing)
+   - Click **Generate token** and copy it
+
+2. **Add as Repository Secret:**
+   - Go to **Repository → Settings → Secrets and variables → Actions**
+   - Click **New repository secret**
+   - Name: `GH_TOKEN`
+   - Value: Paste your token (e.g., `ghp_xxxxxxxxxxxxx`)
+   - Click **Add secret**
+
+   Or via GitHub CLI:
+   ```bash
+   gh secret set GH_TOKEN --body "ghp_xxxxxxxxxxxxx"
+   ```
+
+3. **Workflow uses it automatically:**
+   - For automatic releases (push to branch): Uses `GH_TOKEN` from repository secrets
+   - For manual releases (workflow_dispatch): Requires `GH_TOKEN` secret input
+
+**Required token permissions:**
+- `repo` - Full control of repositories (create releases, tags, commit changelog)
+- `workflow` - Update workflows (optional, only if releases trigger other workflows)
+- `write:packages` - Upload packages (optional, only if publishing packages)
+
+## Release Channels
+
+Different branches create releases on different channels:
+
+| Branch | Channel | Pre-release | Version Example |
+|--------|---------|-------------|-----------------|
+| `main` / `master` | Latest (default) | No | `1.0.0` |
+| `next` | Next | Yes | `2.0.0-next.1` |
+| `beta` | Beta | Yes | `1.1.0-beta.1` |
+| `alpha` | Alpha | Yes | `1.1.0-alpha.1` |
+| `1.x` | 1.x | No | `1.2.0` |
+| `1.0.x` | 1.0.x | No | `1.0.3` |
+
+## Generated Changelog
+
+Semantic-release automatically generates categorized changelogs:
+
+### Example Changelog
+
+```markdown
+# Changelog
+
+## [1.2.0](https://github.com/owner/repo/compare/v1.1.0...v1.2.0) (2024-01-15)
+
+### ✨ Features
+* add user authentication ([abc123](commit-link))
+* implement dark mode ([def456](commit-link))
+
+### 🐛 Bug Fixes
+* resolve memory leak in parser ([ghi789](commit-link))
+* fix typo in error message ([jkl012](commit-link))
+
+### 📚 Documentation
+* update installation guide ([mno345](commit-link))
+
+### ♻️ Code Refactoring
+* simplify authentication logic ([pqr678](commit-link))
+```
+
+## Usage Examples
+
+### Example 1: Feature Release
+
+```bash
+# Make changes and commit with conventional format
+git commit -m "feat: add export to CSV functionality"
+git push origin main
+
+# Semantic-release will:
+# ✅ Analyze commits
+# ✅ Bump minor version (e.g., 1.0.0 → 1.1.0)
+# ✅ Generate changelog
+# ✅ Create tag v1.1.0
+# ✅ Create GitHub release
+# ✅ Update CHANGELOG.md
+```
+
+### Example 2: Bug Fix Release
+
+```bash
+git commit -m "fix: resolve authentication timeout"
+git push origin main
+
+# Result: Patch version bump (e.g., 1.1.0 → 1.1.1)
+```
+
+### Example 3: Breaking Change Release
+
+```bash
+git commit -m "feat!: redesign API endpoints
+
+BREAKING CHANGE: All endpoints now use /v2/ prefix"
+git push origin main
+
+# Result: Major version bump (e.g., 1.1.1 → 2.0.0)
+```
+
+### Example 4: Multiple Commits
+
+```bash
+git commit -m "feat: add search functionality"
+git commit -m "feat: add filtering options"
+git commit -m "fix: correct search highlighting"
+git push origin main
+
+# Result: Minor version bump (1.0.0 → 1.1.0)
+# Changelog includes all three commits
+```
+
+### Example 5: Pre-release (Beta)
+
+```bash
+# Create and push to beta branch
+git checkout -b beta
+git commit -m "feat: experimental feature"
+git push origin beta
+
+# Result: Beta pre-release (e.g., 1.1.0-beta.1)
+```
+
+### Example 6: Maintenance Release
+
+```bash
+# Create maintenance branch for version 1.x
+git checkout -b 1.x
+git commit -m "fix: backport security fix"
+git push origin 1.x
+
+# Result: Patch on 1.x line (e.g., 1.5.0 → 1.5.1)
+```
+
+### Example 7: Dry Run
+
+```bash
+# Test what would be released without creating actual release
+gh workflow run release-reusable.yml -f dry_run=true
+
+# Check workflow output to see:
+# - What version would be created
+# - What commits would be included
+# - Generated changelog preview
+```
+
+### Example 8: No Release Needed
+
+```bash
+# Only non-release commits
+git commit -m "docs: update README"
+git commit -m "chore: update dependencies"
+git push origin main
+
+# Result: No release created (documentation and chores don't trigger releases)
+```
+
+## Release Workflow Process
+
+```mermaid
+graph TD
+    A[Push to Release Branch] --> B[Checkout Code]
+    B --> C[Setup Node.js]
+    C --> D[Determine GitHub Token]
+    D --> E[Run Semantic Release]
+    E --> F[Analyze Commits]
+    F --> G{Release Needed?}
+    G -->|No| H[No Release - Skip]
+    G -->|Yes| I[Calculate Next Version]
+    I --> J[Generate Changelog]
+    J --> K[Create Git Tag]
+    K --> L[Update CHANGELOG.md]
+    L --> M[Commit Changes]
+    M --> N[Create GitHub Release]
+    N --> O[✅ Release Published]
+    H --> P[ℹ️ Workflow Complete]
+```
+
+## Configuration
+
+The workflow uses `.releaserc.json` for configuration:
+
+### Default Configuration
+
+```json
+{
+  "branches": ["main", "master", "next", "beta", "alpha"],
+  "preset": "conventionalcommits",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/github",
+    "@semantic-release/git"
+  ]
+}
+```
+
+### Customization
+
+You can customize by modifying `.releaserc.json`:
+
+```json
+{
+  "branches": [
+    "main",
+    {"name": "develop", "prerelease": true}
+  ],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", {
+      "releaseRules": [
+        {"type": "docs", "scope": "README", "release": "patch"}
+      ]
+    }],
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/github",
+    "@semantic-release/git"
+  ]
+}
+```
+
+## Best Practices
+
+### 1. Always Use Conventional Commits
+
+Every commit should follow the conventional format:
+
+```bash
+# ✅ Good
+git commit -m "feat: add user authentication"
+git commit -m "fix: resolve login timeout"
+git commit -m "docs: update API documentation"
+
+# ❌ Bad
+git commit -m "added authentication"
+git commit -m "bug fix"
+git commit -m "updates"
+```
+
+### 2. Use Meaningful Scopes
+
+Scopes help organize changes:
+
+```bash
+git commit -m "feat(auth): add OAuth2 support"
+git commit -m "fix(api): correct validation logic"
+git commit -m "docs(readme): add installation steps"
+```
+
+### 3. Write Clear Commit Bodies
+
+For complex changes, add detailed descriptions:
+
+```bash
+git commit -m "feat: add advanced search
+
+- Implemented full-text search
+- Added filter by date range
+- Added sort options"
+```
+
+### 4. Test with Dry Run
+
+Before merging to main, test the release:
+
+```bash
+gh workflow run release.yml -f dry_run=true
+```
+
+### 5. Use Pre-release Branches
+
+Test major changes in beta/alpha before releasing:
+
+```bash
+# Develop in beta branch
+git checkout -b beta
+git commit -m "feat: experimental feature"
+git push origin beta  # Creates beta pre-release
+
+# When stable, merge to main
+git checkout main
+git merge beta
+git push origin main  # Creates stable release
+```
+
+### 6. Protect Release Branches
+
+Configure branch protection for `main`/`master`:
+- Require pull request reviews
+- Require status checks to pass
+- Enable conventional commit linting
+
+### 7. Use Commit Linting
+
+Install commitlint to enforce conventional commits:
+
+```bash
+npm install --save-dev @commitlint/config-conventional @commitlint/cli
+```
+
+## Permissions Required
+
+The workflow requires the following permissions:
+
+```yaml
+permissions:
+  contents: write      # Create releases, tags, and commit changelog
+  issues: write        # Comment on issues
+  pull-requests: write # Comment on PRs
+  discussions: write   # Create release discussions
+```
+
+### GitHub Token (`GH_TOKEN`)
+
+The workflow uses the `GH_TOKEN` repository secret for all release operations.
+
+**Why use `GH_TOKEN` instead of default `GITHUB_TOKEN`?**
+- ✅ Can trigger other workflow runs (default `GITHUB_TOKEN` cannot)
+- ✅ Access to organization-level resources
+- ✅ Can bypass branch protection rules if needed
+- ✅ Fine-grained control over permissions
+- ✅ No limitations on cross-repository operations
+
+**Token Scopes Required:**
+- `repo` - Full control of repositories (required)
+- `workflow` - Update workflows (optional, enables triggering other workflows)
+- `write:packages` - Upload packages (optional, only if publishing packages)
+
+## Troubleshooting
+
+### Issue: "No release published"
+
+**Cause:** No commits with release-triggering types since last release
+
+**Solution:**
+- Ensure commits use proper conventional format
+- Check that commits are `feat`, `fix`, or have `BREAKING CHANGE`
+- Review commit types that trigger releases (not `docs`, `chore`, `test`)
+
+```bash
+# Check commits since last release
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+
+# Ensure at least one commit is feat/fix/breaking
+```
+
+### Issue: "Invalid commit message format"
+
+**Cause:** Commits don't follow Conventional Commits specification
+
+**Solution:**
+- Use format: `type(scope): subject`
+- Valid types: feat, fix, docs, style, refactor, perf, test, chore, ci, build
+- Examples:
+  ```bash
+  git commit -m "feat: add new feature"
+  git commit -m "fix(auth): resolve login issue"
+  ```
+
+### Issue: "Permission denied when creating release"
+
+**Cause:** Missing or insufficient `GH_TOKEN` permissions
+
+**Solution:**
+1. Verify `GH_TOKEN` secret exists:
+   ```bash
+   # Check if secret is configured
+   gh secret list | grep GH_TOKEN
+   ```
+
+2. Ensure token has required scopes:
+   - Go to GitHub **Settings → Developer settings → Personal access tokens**
+   - Find your token and verify it has `repo` scope
+   - If not, create a new token with proper scopes
+
+3. Update the secret:
+   ```bash
+   # Via GitHub CLI
+   gh secret set GH_TOKEN --body "ghp_your_new_token_here"
+   ```
+
+4. Check repository workflow permissions:
+   - Go to **Repository → Settings → Actions → General**
+   - Under "Workflow permissions", ensure proper access is granted
+
+### Issue: "Wrong version number generated"
+
+**Cause:** Incorrect commit type or missing breaking change notation
+
+**Solution:**
+- Use `feat:` for minor bumps (1.0.0 → 1.1.0)
+- Use `fix:` for patch bumps (1.0.0 → 1.0.1)
+- Use `BREAKING CHANGE:` for major bumps (1.0.0 → 2.0.0)
+- Check `.releaserc.json` configuration
+
+### Issue: "CHANGELOG.md conflicts"
+
+**Cause:** Local CHANGELOG.md differs from auto-generated version
+
+**Solution:**
+- Don't manually edit CHANGELOG.md (semantic-release manages it)
+- Pull latest changes before pushing:
+  ```bash
+  git pull --rebase origin main
+  ```
+- If conflicts persist, delete local CHANGELOG.md and let semantic-release regenerate
+
+### Issue: "Release already exists for this tag"
+
+**Cause:** Tag already exists (workflow is idempotent and will skip)
+
+**Solution:**
+- This is normal behavior - semantic-release won't create duplicates
+- If you need to recreate, delete the tag and release first:
+  ```bash
+  gh release delete v1.0.0 --yes
+  git tag -d v1.0.0
+  git push origin :refs/tags/v1.0.0
+  ```
+
+## Advanced Configuration
+
+### Using GitHub App Tokens
+
+For organizations, you can use a GitHub App token instead of a Personal Access Token:
+
+**Benefits of GitHub App tokens:**
+- ✅ Better rate limits (5,000 requests/hour vs 1,000 for PAT)
+- ✅ More granular permissions
+- ✅ Better audit trail
+- ✅ Automatic rotation
+- ✅ Organization-wide management
+
+**Setup:**
+
+1. **Create a GitHub App:**
+   - Go to **Organization Settings → Developer settings → GitHub Apps**
+   - Click **New GitHub App**
+   - Set name and permissions:
+     - Repository permissions:
+       - Contents: Read and write
+       - Pull requests: Read and write
+       - Issues: Read and write
+       - Metadata: Read-only
+   - Generate and download private key
+
+2. **Install App on Repository:**
+   - Install the app on your repository
+   - Note the App ID and Installation ID
+
+3. **Add App Credentials as Secrets:**
+   ```bash
+   gh secret set APP_ID --body "123456"
+   gh secret set APP_PRIVATE_KEY < private-key.pem
+   ```
+
+4. **Modify Workflow to Generate Token:**
+
+   You'll need to modify the `.github/workflows/release-reusable.yml` file:
+
+   ```yaml
+   jobs:
+     release:
+       name: Semantic Release
+       runs-on: ubuntu-latest
+       steps:
+         - name: Checkout code
+           uses: actions/checkout@v4
+           with:
+             fetch-depth: 0
+             persist-credentials: false
+
+         - name: Generate GitHub App Token
+           id: generate_token
+           uses: tibdex/github-app-token@v2
+           with:
+             app_id: ${{ secrets.APP_ID }}
+             private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+         - name: Setup Node.js
+           uses: actions/setup-node@v4
+           with:
+             node-version: 'lts/*'
+
+         - name: Semantic Release
+           uses: cycjimmy/semantic-release-action@v4
+           with:
+             extra_plugins: |
+               @semantic-release/changelog@6.0.3
+               @semantic-release/git@10.0.1
+               conventional-changelog-conventionalcommits@7.0.2
+           env:
+             GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+   ```
+
+### Fine-Grained Personal Access Tokens
+
+For better security, use fine-grained tokens (beta):
+
+1. **Create Fine-Grained Token:**
+   - Go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+   - Click **Generate new token**
+   - Set repository access (only repositories you need)
+   - Set permissions:
+     - Contents: Read and write
+     - Pull requests: Read and write
+     - Issues: Read and write
+   - Set expiration (recommended: 90 days with auto-renewal reminder)
+
+2. **Add as Secret:**
+   ```bash
+   gh secret set GH_TOKEN --body "github_pat_xxxxxxxxxxxxx"
+   ```
+
+### Custom Release Rules
+
+Modify `.releaserc.json` to customize version bump rules:
+
+```json
+{
+  "plugins": [
+    ["@semantic-release/commit-analyzer", {
+      "releaseRules": [
+        {"type": "docs", "scope": "README", "release": "patch"},
+        {"type": "refactor", "release": "patch"},
+        {"type": "style", "release": "patch"}
+      ]
+    }]
+  ]
+}
+```
+
+### Disable Changelog File
+
+Remove changelog plugin if you don't want CHANGELOG.md:
+
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/github"
+  ]
+}
+```
+
+### Integration with Other Workflows
+
+Trigger deployments after release:
+
+```yaml
+# In another workflow file
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: |
+          echo "Deploying version ${{ github.event.release.tag_name }}"
+```
+
+### Monorepo Support
+
+For monorepos, use separate configurations per package:
+
+```bash
+# In each package directory
+packages/
+  package-a/
+    .releaserc.json
+  package-b/
+    .releaserc.json
+```
+
+## Migration from Manual Releases
+
+If migrating from manual versioning:
+
+1. **Create Initial Release**
+   ```bash
+   # Create a base tag for semantic-release to work from
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+2. **Start Using Conventional Commits**
+   ```bash
+   # All new commits should follow convention
+   git commit -m "feat: add new feature"
+   ```
+
+3. **Run First Automated Release**
+   ```bash
+   git push origin main
+   # Semantic-release will handle the rest
+   ```
+
+## References
+
+- [Semantic Release Documentation](https://semantic-release.gitbook.io/)
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [cycjimmy/semantic-release-action](https://github.com/cycjimmy/semantic-release-action)
+- [Semantic Release Plugins](https://semantic-release.gitbook.io/semantic-release/extending/plugins-list)
+- [Commit Message Guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)
+
+## Support
+
+For issues or questions:
+- Check the [semantic-release troubleshooting guide](https://semantic-release.gitbook.io/semantic-release/support/troubleshooting)
+- Review GitHub Actions logs for detailed error messages
+- Open an issue in this repository
+- Consult the [Conventional Commits FAQ](https://www.conventionalcommits.org/en/v1.0.0/#faq)
diff --git a/docs/workflows/symfony-php-reusable.md b/docs/workflows/symfony-php-reusable.md
index 589d7ea..73e119f 100644
--- a/docs/workflows/symfony-php-reusable.md
+++ b/docs/workflows/symfony-php-reusable.md
@@ -4,6 +4,43 @@
 
 The [`symfony-php-reusable.yml`](../../.github/workflows/symfony-php-reusable.yml) is a comprehensive reusable GitHub Actions workflow designed specifically for Symfony PHP projects. This workflow consolidates all common quality checks, testing, and validation tools used across MacPaw's public Symfony repositories, providing a complete CI/CD solution with extensive customization options.
 
+## 🎉 What's New
+
+### Dynamic Matrix Generation (Latest Version)
+
+The workflow now features **fully dynamic matrix generation** with Cartesian product support:
+
+- ✨ **No Hardcoded Packages**: Test ANY Composer packages without modifying the workflow
+- 🔢 **Cartesian Product**: Automatically generates ALL combinations of package versions
+- 📊 **Auto-Generated Titles**: Each test job shows all package versions being tested
+- 🎯 **matrix-include**: Add custom test scenarios (coverage, lowest deps)
+- 🚫 **matrix-exclude**: Filter incompatible combinations
+- 🐛 **Xdebug Auto-Configuration**: Automatically adds xdebug extension when coverage enabled
+- 🔧 **Quality Tools PHP Version**: Configure separate PHP version for static analysis tools
+- 🧩 **Symfony Minor Detection**: The workflow detects the Symfony version from your matrix and exposes it to Composer via `SYMFONY_REQUIRE` during dependency installation (no change to install commands required)
+
+**Example Matrix Output:**
+```text
+Input:
+  php: ["8.2", "8.3"]
+  symfony/cache: ["6.4.*", "7.0.*"]
+  symfony/config: ["6.4.*", "7.0.*"]
+  monolog/monolog: ["^2.9", "^3.0"]
+
+Generated Test Jobs (Cartesian Product):
+✅ Unit Tests (PHP 8.2, cache 6.4.*, config 6.4.*, monolog ^2.9)
+✅ Unit Tests (PHP 8.2, cache 6.4.*, config 6.4.*, monolog ^3.0)
+✅ Unit Tests (PHP 8.2, cache 6.4.*, config 7.0.*, monolog ^2.9)
+✅ Unit Tests (PHP 8.2, cache 6.4.*, config 7.0.*, monolog ^3.0)
+✅ Unit Tests (PHP 8.2, cache 7.0.*, config 6.4.*, monolog ^2.9)
+... (16 total combinations for 2 PHP × 2 cache × 2 config × 2 monolog)
+```
+
+### Breaking Changes
+- Matrix generation now creates Cartesian product of ALL packages (not just symfony/framework-bundle)
+- Job titles now include all package versions from matrix
+- symfony/framework-bundle is no longer treated specially - it's just another package
+
 ## 🎯 Purpose
 
 This workflow automates the complete CI process for Symfony PHP projects:
@@ -11,7 +48,7 @@ This workflow automates the complete CI process for Symfony PHP projects:
 - 🧪 **Comprehensive Testing** - PHPUnit with multi-version matrix testing
 - 📊 **Code Coverage** - Xdebug integration with Codecov reporting
 - 🔒 **Quality Assurance** - Code style, static analysis, mutation testing with configurable thresholds
-- 🏗️ **Flexible Configuration** - 22 customizable input parameters
+- 🏗️ **Flexible Configuration** - 23 customizable input parameters
 - ⚙️ **Composer Integration** - Advanced dependency management with caching
 - 🎯 **Matrix Customization** - Custom version exclusions for compatibility testing
 - 📝 **Commit Validation** - Optional commitlint integration
@@ -21,8 +58,8 @@ This workflow automates the complete CI process for Symfony PHP projects:
 
 | Input | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `versions-matrix` | string (JSON object) | ❌ | `{"php": ["8.2", "8.3", "8.4"], "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]}` | JSON object with package versions to test. Format: `{"php": [...], "package/name": [...]}` |
-| `enable-code-coverage` | boolean | ❌ | `true` | Enable code coverage reporting |
+| `matrix-include` | string (JSON array) | ❌ | `[]` | Additional matrix combinations to include. Use for custom test scenarios, lowest deps, or code coverage configurations. |
+| `versions-matrix` | string (JSON object) | ❌ | `{"php": ["8.2", "8.3", "8.4"], "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]}` | **Dynamic matrix generation**: JSON object with package versions. Creates Cartesian product of all packages. PHP versions are tested with ALL combinations of other package versions. |
 | `enable-phpstan` | boolean | ❌ | `true` | Enable PHPStan static analysis |
 | `enable-phpcs` | boolean | ❌ | `true` | Enable PHP_CodeSniffer |
 | `enable-php-cs-fixer` | boolean | ❌ | `false` | Enable PHP-CS-Fixer |
@@ -30,11 +67,15 @@ This workflow automates the complete CI process for Symfony PHP projects:
 | `enable-infection` | boolean | ❌ | `false` | Enable Infection mutation testing |
 | `enable-commitlint` | boolean | ❌ | `false` | Enable commit message linting |
 | `enable-composer-validate` | boolean | ❌ | `true` | Enable Composer validation |
-| `test-lowest-dependencies` | boolean | ❌ | `false` | Test with lowest dependencies |
+| `enable-coverage-check` | boolean | ❌ | `false` | Enable coverage validation and PR comments |
+| `coverage-threshold` | number | ❌ | `70` | Minimum code coverage percentage required (0-100) |
+| `coverage-file` | string | ❌ | `coverage.xml` | Coverage report file name (Clover XML). Used for PHPUnit generation, Codecov upload, and coverage validation. |
+| `phpcov-version` | string | ❌ | `8.2` | Version of phpcov PHAR to download from phar.phpunit.de (e.g., `8.2` downloads `phpcov-8.2.phar`). |
 | `phpstan-level` | string | ❌ | `max` | PHPStan level (0-9 or max) |
 | `working-directory` | string | ❌ | `.` | Working directory for the project |
-| `php-extensions` | string | ❌ | `mbstring, json` | Additional PHP extensions to install |
-| `matrix-exclude` | string (JSON array) | ❌ | Default Symfony 7.x exclusions | Matrix combinations to exclude. Use full package names (e.g., `symfony/framework-bundle`) |
+| `php-extensions` | string | ❌ | `mbstring, json` | Additional PHP extensions to install. xdebug auto-added when coverage enabled. |
+| `php-version-quality-tools` | string | ❌ | `8.3` | PHP version to use for quality tools (PHPStan, PHPCS, Rector, Infection, etc.) |
+| `matrix-exclude` | string (JSON array) | ❌ | Default Symfony 7.x exclusions | Matrix combinations to exclude. Supports any package from `versions-matrix`. Values ending with `.*` act as wildcards/prefixes (e.g., `"7.3.*"` matches `"7.3"` and `"7.3.*"`), while values without `.*` require exact match. |
 | `infection-min-msi` | number | ❌ | `80` | Minimum Mutation Score Indicator (MSI) for Infection |
 | `infection-min-covered-msi` | number | ❌ | `90` | Minimum Covered Code MSI for Infection |
 | `phpstan-config` | string | ❌ | `''` | Path to PHPStan configuration file (default: phpstan.neon.dist or phpstan.neon) |
@@ -48,7 +89,7 @@ This workflow automates the complete CI process for Symfony PHP projects:
 
 | Secret | Required | Description |
 |--------|----------|-------------|
-| `codecov-token` | ❌ | Codecov token for coverage upload |
+| `CODECOV_TOKEN` | ❌ | Codecov token for coverage upload |
 
 ## 🚀 Usage
 
@@ -71,11 +112,10 @@ jobs:
           "php": ["8.2", "8.3", "8.4"],
           "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]
         }
-      enable-code-coverage: true
       enable-phpstan: true
       enable-phpcs: true
     secrets:
-      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 ```
 
 ### Minimal Setup (Only Tests + PHPStan)
@@ -97,7 +137,6 @@ jobs:
         }
       enable-phpstan: true
       enable-phpcs: false
-      enable-code-coverage: false
 ```
 
 ### Full Quality Check with All Tools
@@ -128,7 +167,6 @@ jobs:
           "php": ["8.2", "8.3", "8.4"],
           "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]
         }
-      enable-code-coverage: true
       enable-phpstan: true
       enable-phpcs: true
       enable-php-cs-fixer: true
@@ -136,11 +174,10 @@ jobs:
       enable-infection: true
       enable-commitlint: true
       enable-composer-validate: true
-      test-lowest-dependencies: true
       phpstan-level: 'max'
       php-extensions: 'mbstring, json, xml, curl, redis'
     secrets:
-      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 ```
 
 ### Extended Version Matrix (Legacy Support)
@@ -160,12 +197,10 @@ jobs:
           "php": ["7.4", "8.0", "8.1", "8.2", "8.3", "8.4"],
           "symfony/framework-bundle": ["4.4.*", "5.4.*", "6.0.*", "6.4.*", "7.0.*", "7.3.*"]
         }
-      enable-code-coverage: true
       enable-phpstan: true
       enable-phpcs: true
-      test-lowest-dependencies: true
     secrets:
-      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 ```
 
 ### Testing Multiple Symfony Packages
@@ -191,7 +226,7 @@ jobs:
       enable-phpstan: true
       enable-phpcs: true
     secrets:
-      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 ```
 
 ### Testing with Doctrine ORM
@@ -245,6 +280,31 @@ jobs:
       enable-phpcs: true
 ```
 
+### Custom Matrix Include (add coverage and lowest deps)
+
+```yaml
+name: Matrix Include Example
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+    with:
+      versions-matrix: |
+        {
+          "php": ["8.2", "8.3"],
+          "symfony/framework-bundle": ["6.4.*"]
+        }
+      # Add an extra leg with lowest dependencies and coverage enabled
+      matrix-include: '[
+        {"php":"8.2","dependencies":"lowest","coverage":"xdebug"}
+      ]'
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+```
+
 ### No Exclusions (Test All Combinations)
 
 ```yaml
@@ -299,70 +359,234 @@ jobs:
       infection-min-msi: 85
       infection-min-covered-msi: 95
     secrets:
-      codecov-token: ${{ secrets.CODECOV_TOKEN }}
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+```
+
+### Custom PHP Version for Quality Tools
+
+Use a specific PHP version for static analysis and quality tools, different from your test matrix:
+
+```yaml
+name: CI with Separate Quality Tools PHP
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+    with:
+      # Test with multiple PHP versions
+      versions-matrix: |
+        {
+          "php": ["8.2", "8.3", "8.4"],
+          "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+        }
+      # But run quality tools with latest stable PHP only
+      php-version-quality-tools: '8.4'
+      enable-phpstan: true
+      enable-phpcs: true
+      enable-php-cs-fixer: true
+      enable-rector: true
+      enable-infection: true
 ```
 
+**Why use php-version-quality-tools?**
+- **Performance**: Latest PHP versions are faster for static analysis
+- **Latest Features**: Use newest PHP features in quality tool configs
+- **Consistency**: All quality tools run on same PHP version
+- **Avoid Issues**: Some tools may have issues with older PHP versions
+
+**Common Configurations:**
+```text
+# Legacy support: Test old PHP, analyze with stable
+versions-matrix: '{"php": ["7.4", "8.0", "8.1", "8.2"]}'
+php-version-quality-tools: '8.3'
+
+# Bleeding edge: Test stable, analyze with latest
+versions-matrix: '{"php": ["8.2", "8.3"]}'
+php-version-quality-tools: '8.4'
+
+# Conservative: Same PHP for all
+versions-matrix: '{"php": ["8.2", "8.3"]}'
+php-version-quality-tools: '8.2'
+```
+
+### Testing Non-Symfony Packages
+
+The workflow supports ANY Composer packages, not just Symfony:
+
+```yaml
+name: Testing Non-Symfony Packages
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+    with:
+      versions-matrix: |
+        {
+          "php": ["8.2", "8.3"],
+          "monolog/monolog": ["^2.9", "^3.0"],
+          "guzzlehttp/guzzle": ["^7.0"],
+          "league/flysystem": ["^3.0"]
+        }
+      enable-phpstan: true
+      enable-phpcs: true
+```
+
+### Complex Multi-Package Matrix
+
+Test all combinations of multiple packages:
+
+```yaml
+name: Complex Matrix Testing
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+    with:
+      versions-matrix: |
+        {
+          "php": ["8.2", "8.3"],
+          "symfony/cache": ["6.4.*", "7.0.*"],
+          "symfony/config": ["6.4.*", "7.0.*"],
+          "symfony/console": ["6.4.*", "7.0.*"],
+          "monolog/monolog": ["^2.9", "^3.0"]
+        }
+      # This creates 2 PHP × 2 cache × 2 config × 2 console × 2 monolog = 32 combinations!
+      # Consider using matrix-exclude to reduce if needed
+      matrix-exclude: |
+        [
+          {"php": "8.2", "symfony/cache": "7.0.*", "symfony/config": "6.4.*"},
+          {"php": "8.2", "symfony/console": "7.0.*", "symfony/config": "6.4.*"}
+        ]
+      enable-phpstan: true
+      php-version-quality-tools: '8.3'
+```
+
+### Coverage Validation with PR Comments
+
+Enable automatic coverage validation on pull requests:
+
+```yaml
+name: CI with Coverage Validation
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+    with:
+      versions-matrix: |
+        {
+          "php": ["8.2", "8.3"],
+          "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+        }
+      # Enable coverage on specific combination
+      matrix-include: '[
+        {"php": "8.3", "symfony/framework-bundle": "7.0.*", "coverage": "xdebug"}
+      ]'
+      # Enable coverage validation
+      enable-coverage-check: true
+      coverage-threshold: 80
+      enable-phpstan: true
+      enable-phpcs: true
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+```
+
+**Features:**
+- Posts a single PR comment with coverage results (updates existing)
+- Aggregates coverage from all test combinations
+- Fails the workflow if coverage is below threshold
+- Displays coverage percentage, threshold, and lines covered
+
+**Requirements:**
+- Workflow must run on `pull_request` event
+- At least one matrix combination must have `"coverage": "xdebug"`
+- Requires `pull-requests: write` permission (automatically granted in most cases)
+
 ## 🔄 Workflow Diagram
 
 ```mermaid
 graph TD
-    A[🚀 Trigger: Pull Request / Push / Schedule] --> B[📋 Parallel Job Execution]
+    A[🚀 Trigger: Pull Request / Push / Schedule] --> A1[🎯 Generate Matrix Job]
+    A1 --> A2[📊 Parse versions-matrix JSON]
+    A2 --> A3[🔢 Create Cartesian Product]
+    A3 --> A4[🎯 Generate Job Titles]
+    A4 --> A5[🚫 Apply matrix-exclude]
+    A5 --> A6[➕ Apply matrix-include]
+    A6 --> B[📋 Parallel Job Execution]
 
     B --> C1{📝 Commitlint Enabled?}
-    C1 -->|Yes| C2[📝 Validate Commits]
+    C1 -->|Yes| C2[📝 Validate Commits<br/>PHP 8.3]
     C1 -->|No| D
     C2 --> D
 
     B --> D{🔧 Composer Validate Enabled?}
-    D -->|Yes| D1[🔧 Validate composer.json]
+    D -->|Yes| D1[🔧 Validate composer.json<br/>PHP 8.3]
     D -->|No| E
     D1 --> E
 
     B --> E{🎨 PHPCS Enabled?}
-    E -->|Yes| E1[🎨 Code Style Check]
+    E -->|Yes| E1[🎨 Code Style Check<br/>php-version-quality-tools]
     E -->|No| F
     E1 --> F
 
     B --> F{✨ PHP-CS-Fixer Enabled?}
-    F -->|Yes| F1[✨ Code Format Check]
+    F -->|Yes| F1[✨ Code Format Check<br/>php-version-quality-tools]
     F -->|No| G
     F1 --> G
 
     B --> G{🔍 PHPStan Enabled?}
-    G -->|Yes| G1[🔍 Static Analysis]
+    G -->|Yes| G1[🔍 Static Analysis<br/>php-version-quality-tools]
     G -->|No| H
     G1 --> H
 
     B --> H{🏗️ Rector Enabled?}
-    H -->|Yes| H1[🏗️ Code Modernization Check]
+    H -->|Yes| H1[🏗️ Code Modernization Check<br/>php-version-quality-tools]
     H -->|No| I
     H1 --> I
 
-    B --> I[🧪 Unit Tests Matrix]
-    I --> I1[📦 Setup PHP Matrix]
-    I1 --> I2[🔧 Install Dependencies]
-    I2 --> I3[⚙️ Configure Symfony Version]
+    B --> I[🧪 Unit Tests Matrix<br/>depends on: generate-matrix]
+    I --> I1[📦 Setup PHP from Matrix]
+    I1 --> I1A{🐛 Coverage in Matrix?}
+    I1A -->|Yes| I1B[➕ Add xdebug extension]
+    I1A -->|No| I2
+    I1B --> I2
+    I2[🔧 Install Dependencies]
+    I2 --> I3[⚙️ Apply Package Constraints<br/>Loop through matrix keys]
     I3 --> I4{💾 Dependencies Type?}
-    I4 -->|Highest| I5[📦 Install Latest]
-    I4 -->|Lowest| I6[📦 Install Oldest]
+    I4 -->|Highest| I5[📦 composer update]
+    I4 -->|Lowest| I6[📦 composer update --prefer-lowest]
     I5 --> I7[🧪 Run PHPUnit]
     I6 --> I7
     I7 --> I8{📊 Coverage Enabled?}
-    I8 -->|Yes| I9[📊 Generate Coverage]
+    I8 -->|Yes| I9[📊 Generate Coverage<br/>with xdebug]
     I8 -->|No| J
     I9 --> I10[☁️ Upload to Codecov]
     I10 --> J
 
     B --> J{🦠 Infection Enabled?}
-    J -->|Yes| J1[🦠 Mutation Testing]
+    J -->|Yes| J1[🦠 Mutation Testing<br/>php-version-quality-tools]
     J -->|No| K
     J1 --> K
 
     K[✅ All Jobs Complete]
 
     style A fill:#e1f5fe
+    style A1 fill:#fff3e0
+    style A3 fill:#ffe0b2
     style K fill:#c8e6c9
     style I fill:#e8f5e8
+    style I3 fill:#fff8e1
     style I9 fill:#fff8e1
     style C2 fill:#f3e5f5
     style G1 fill:#fff3e0
@@ -420,12 +644,72 @@ graph TD
 
 ### 4. 🧪 Testing Matrix Phase
 
+#### Dynamic Matrix Generation with Cartesian Product
+
+The workflow uses a **generate-matrix** job that creates a Cartesian product of all package versions:
+
+**How it Works:**
+
+1. **Parse Input**: Reads `versions-matrix` JSON
+   ```json
+   {
+     "php": ["8.2", "8.3"],
+     "symfony/cache": ["6.4.*", "7.0.*"],
+     "symfony/config": ["6.4.*", "7.0.*"]
+   }
+   ```
+
+2. **Extract Dimensions**:
+   - PHP versions: `["8.2", "8.3"]`
+   - Packages: `{"symfony/cache": ["6.4.*", "7.0.*"], "symfony/config": ["6.4.*", "7.0.*"]}`
+
+3. **Generate Cartesian Product**:
+   - For each PHP version
+   - Create ALL combinations of package versions
+   - Result: 2 PHP × 2 cache × 2 config = **8 total combinations**
+
+4. **Generate Job Titles**:
+   - Each combination gets descriptive title
+   - Example: `"PHP 8.2, cache 6.4.*, config 6.4.*"`
+   - Short package names (last segment after `/`)
+
+5. **Apply Filters**:
+   - Apply `matrix-exclude` to remove incompatible combinations
+   - Add `matrix-include` for custom scenarios (coverage, lowest deps)
+
+6. **Output Matrix**: JSON array passed to unit-tests job
+
+**Example Generation:**
+```text
+Input:
+  php: ["8.2", "8.3"]
+  symfony/cache: ["6.4.*", "7.0.*"]
+  symfony/config: ["6.4.*", "7.0.*"]
+
+Generated Combinations:
+1. {"php": "8.2", "symfony/cache": "6.4.*", "symfony/config": "6.4.*", "dependencies": "highest", "title": "PHP 8.2, cache 6.4.*, config 6.4.*"}
+2. {"php": "8.2", "symfony/cache": "6.4.*", "symfony/config": "7.0.*", "dependencies": "highest", "title": "PHP 8.2, cache 6.4.*, config 7.0.*"}
+3. {"php": "8.2", "symfony/cache": "7.0.*", "symfony/config": "6.4.*", "dependencies": "highest", "title": "PHP 8.2, cache 7.0.*, config 6.4.*"}
+4. {"php": "8.2", "symfony/cache": "7.0.*", "symfony/config": "7.0.*", "dependencies": "highest", "title": "PHP 8.2, cache 7.0.*, config 7.0.*"}
+5. {"php": "8.3", "symfony/cache": "6.4.*", "symfony/config": "6.4.*", "dependencies": "highest", "title": "PHP 8.3, cache 6.4.*, config 6.4.*"}
+6. {"php": "8.3", "symfony/cache": "6.4.*", "symfony/config": "7.0.*", "dependencies": "highest", "title": "PHP 8.3, cache 6.4.*, config 7.0.*"}
+7. {"php": "8.3", "symfony/cache": "7.0.*", "symfony/config": "6.4.*", "dependencies": "highest", "title": "PHP 8.3, cache 7.0.*, config 6.4.*"}
+8. {"php": "8.3", "symfony/cache": "7.0.*", "symfony/config": "7.0.*", "dependencies": "highest", "title": "PHP 8.3, cache 7.0.*, config 7.0.*"}
+```
+
+**Important Notes:**
+- Matrix grows **exponentially**: N packages with M versions each = `PHP_versions × M^N` combinations
+- Use `matrix-exclude` to reduce large matrices
+- Consider testing only critical combinations for many packages
+- Each combination runs in parallel (up to GitHub Actions concurrent job limit)
+
 #### Matrix Configuration
 - **Versions Matrix**: JSON object with PHP and package versions
 - **PHP Versions**: Extracted from `versions-matrix.php` array
-- **Package Versions**: All non-PHP keys in versions-matrix
+- **Package Versions**: All non-PHP keys in versions-matrix (any Composer package)
 - **Dependencies**: Tests both highest and lowest (if enabled)
 - **Exclusions**: Custom exclusions via `matrix-exclude` input
+- **Additions**: Custom additions via `matrix-include` input
 
 #### Version Compatibility
 - **Symfony 7.0+**: Requires PHP 8.2+
@@ -434,16 +718,29 @@ graph TD
 - **Symfony 7.3+**: Requires PHP 8.2+
 
 #### Dynamic Package Constraint Application
-The workflow automatically applies version constraints for **all packages** in versions-matrix:
+The workflow automatically applies version constraints for **all packages** in versions-matrix and detects Symfony minor for Flex:
 
 **Process:**
-1. Parse versions-matrix JSON
-2. Extract and apply Symfony framework-bundle constraint (if present)
-   - Sets version constraint: `composer require "symfony/framework-bundle:{version}" --no-update`
-   - Configures Symfony require: `composer config extra.symfony.require "{version}"`
-3. Loop through all other packages
-   - Apply constraint for each: `composer require "{package}:{version}" --no-update`
-4. Install dependencies (highest or lowest)
+1. **Parse Matrix**: Each test job receives matrix combination (e.g., `{"php": "8.3", "symfony/cache": "7.0.*", "symfony/config": "6.4.*"}`)
+2. **Setup PHP**: Install PHP version from matrix
+3. **Loop Through Matrix Keys**: For each key that's not `php`, `dependencies`, `coverage`, `title`, `description`:
+   - Extract package name and version from matrix
+   - Apply constraint: `composer require "{package}:{version}" --no-update --no-interaction`
+   - Detect Symfony version and set Composer extra: If the package is `symfony/framework-bundle`, set `composer config extra.symfony.require "{version}"`. If not provided, the workflow will try to infer Symfony version from the first `symfony/*` package in the matrix and set it accordingly.
+4. **Install Dependencies**:
+   - The job exports `SYMFONY_REQUIRE` environment variable for this step using the detected Symfony version. This lets Symfony Flex align all `symfony/*` packages to the same minor automatically.
+   - Highest: `composer update --no-interaction --no-progress --prefer-dist`
+   - Lowest: `composer update --prefer-lowest --prefer-stable --no-interaction --no-progress`
+
+#### Step Outputs (for debugging/inspection)
+
+The "Apply package version constraints from matrix" step now exposes useful outputs within the job:
+
+- `composer_packages` — space-separated list like `vendor/package:version vendor2/package2:version`
+- `composer_packages_json` — JSON map of applied constraints
+- `symfony_version` — detected Symfony version used for `extra.symfony.require` (if any)
+
+These are echoed before installation to aid troubleshooting.
 
 **Example:**
 ```yaml
@@ -455,19 +752,24 @@ versions-matrix: |
     "doctrine/orm": ["3.0.*"]
   }
 
-# Applied constraints:
+# Applied constraints in each test job:
 # - symfony/framework-bundle:7.0.*
 # - symfony/console:7.0.*
 # - doctrine/orm:3.0.*
+# extra.symfony.require: 7.0.*
+# SYMFONY_REQUIRE env (Install dependencies step): 7.0.*
 ```
 
+**Key Feature**: NO hardcoded package names! The workflow dynamically detects and applies constraints for any packages in the matrix.
+
 #### Dependency Installation
 - **Highest Dependencies**: `composer update --no-interaction --no-progress --prefer-dist`
 - **Lowest Dependencies**: `composer update --prefer-lowest --prefer-stable`
 
 #### Testing Execution
-- **Without Coverage**: `vendor/bin/phpunit --testdox`
+- **Without Coverage**: `vendor/bin/phpunit --testdox --no-coverage`
 - **With Coverage**: `vendor/bin/phpunit --testdox --coverage-clover=coverage.xml`
+  - Note: The coverage file name is configurable via the `coverage-file` input (default: `coverage.xml`).
 - **Coverage Upload**: Automatic upload to Codecov (if token provided)
 
 ### 5. 🦠 Mutation Testing Phase (Optional)
@@ -538,6 +840,16 @@ with:
     ]
 ```
 
+#### Exclusion Matching Semantics
+
+- Wildcard match: A rule value ending with `.*` is treated as a prefix. For example:
+  - `{ "symfony/framework-bundle": "7.3.*" }` will match matrix values `"7.3"`, `"7.3.*"`, `"7.3.x"`, etc.
+- Exact match: A rule value without `.*` must equal the matrix value exactly. For example:
+  - `{ "php": "8.2" }` matches only `"8.2"`, not `"8.2.1"`.
+- Mixed rules: All keys in a rule must match (AND behavior). This lets you target precise combinations like `{ "php": "8.2", "symfony/framework-bundle": "7.2.*" }`.
+
+This behavior ensures that exclusions like `"7.2.*"` and `"7.3.*"` properly skip jobs even if your `versions-matrix` lists values as `"7.2"` or `"7.3"` without the trailing `.*`.
+
 **Disable All Exclusions:**
 ```yaml
 with:
@@ -553,7 +865,7 @@ with:
 ### 📊 Matrix Examples
 
 **Example 1: Basic Symfony Testing**
-```yaml
+```text
 # Input:
 versions-matrix: |
   {
@@ -577,7 +889,7 @@ versions-matrix: |
 ```
 
 **Example 2: Multiple Packages**
-```yaml
+```text
 # Input:
 versions-matrix: |
   {
@@ -596,7 +908,7 @@ versions-matrix: |
 ```
 
 **Example 3: PHP Only (No Package Constraints)**
-```yaml
+```text
 # Input:
 versions-matrix: |
   {
@@ -624,12 +936,59 @@ The workflow implements efficient Composer caching:
 
 ### 📊 Code Coverage Strategy
 
-Coverage is enabled for one matrix combination to balance performance and reporting:
-- **Coverage Job**: First matrix combination (lowest dependencies)
-- **Coverage Mode**: Xdebug
-- **Output Format**: Clover XML (`coverage.xml`)
+Coverage is enabled per matrix combination by adding `"coverage": "xdebug"` via `matrix-include`:
+- **Enable Coverage**: Add to specific matrix combination: `matrix-include: '[{"php": "8.3", "coverage": "xdebug"}]'`
+- **Coverage Mode**: Xdebug (automatically configured when `coverage: xdebug` is in matrix)
+- **Xdebug Extension**: Automatically added to PHP extensions when coverage is enabled
+- **Output Format**: Clover XML (default file name: `coverage.xml`, configurable via `coverage-file`)
 - **Upload**: Automatic upload to Codecov if token provided
 - **Failure Handling**: `fail_ci_if_error: false` - won't block CI on upload failures
+- **Best Practice**: Enable coverage on one or few combinations to balance performance and reporting
+
+### ✅ Coverage Validation
+
+Automatically validate code coverage on pull requests and post a concise PR comment. The workflow merges coverage where possible and validates with `rregeer/phpunit-coverage-check` only — no Python or XML parsing is used for the percentage value.
+
+**Features:**
+- ✅ **Merged Coverage (phpcov)**: Attempts to merge raw coverage (`coverage.cov`) from all coverage-enabled test jobs into a single Clover report
+- 🧰 **Threshold Check (phpunit-coverage-check)**: Validates coverage against your threshold on the merged Clover; if no merged file, validates a single Clover file; if multiple files exist, each is checked and the lowest reported coverage is shown
+- 💬 **Simple PR Comment**: Posts a single line message: `Coverage: <pct>% (min <threshold>%) — OK/NOT OK`
+- 📈 **Percentage Source**: The `<pct>` shown is parsed strictly from the `coverage-check` command output. There are no fallbacks to parse Clover/XML files.
+- 🎯 **Configurable Threshold**: Set minimum required coverage percentage
+- ❌ **Fail on Low Coverage**: Workflow fails if coverage is below threshold
+
+**Configuration:**
+```yaml
+enable-coverage-check: true      # Enable validation (default: false)
+coverage-threshold: 80           # Minimum coverage % (default: 70)
+```
+
+**How It Works:**
+1. Unit tests with coverage generate Clover XML (`coverage.xml` by default) and raw coverage (`coverage.cov`).
+2. Coverage files are uploaded as artifacts (one artifact per matrix job).
+3. `coverage-validation` job:
+   - Downloads `phpcov` as a PHAR from phar.phpunit.de using `phpcov-version` input and installs `rregeer/phpunit-coverage-check` globally
+   - Downloads all coverage artifacts to `coverage-artifacts/`
+   - Attempts to merge raw coverage with `php phpcov.phar merge --clover merged-coverage.xml <dirs>`
+   - Runs `coverage-check <file> <min>` on the merged Clover (or each single Clover if no merge). The reported percentage in the PR comment is taken directly from the command output. No XML parsing or other fallbacks are used to derive the coverage value.
+4. Posts or updates a PR comment with a simple OK/NOT OK message and the current coverage value
+5. Fails job if coverage < threshold
+
+**PR Comment Example:**
+```markdown
+Coverage: 85.50% (min 80%) — OK
+```
+
+**Requirements:**
+- Must run on `pull_request` event (validation only runs on PRs)
+- At least one matrix combination must have `"coverage": "xdebug"`
+- Requires `pull-requests: write` permission (auto-granted in most workflows)
+- `phpcov` is downloaded as a PHAR (`phpcov-<version>.phar`) and `rregeer/phpunit-coverage-check` is installed automatically in the coverage validation job
+
+**Edge Cases:**
+- **No coverage artifacts**: Job succeeds with status "no-coverage" (no comment posted)
+- **Multiple coverage files**: All files are aggregated for comprehensive coverage
+- **Coverage exactly at threshold**: Passes (>= threshold)
 
 ### 🔄 Concurrency Management
 
@@ -710,8 +1069,10 @@ All quality tools support custom configuration file paths. If not specified, too
 - **Infection**: 20 minutes
 
 ### 🎯 Selective Coverage
-- Coverage enabled only for one matrix job
-- All other jobs run without coverage for speed
+- Coverage enabled per-combination via `matrix-include` with `"coverage": "xdebug"`
+- Control which combinations run with coverage
+- Recommended to enable on one or few combinations for speed
+- All other jobs run without coverage overhead
 - Balanced approach for performance and reporting
 
 ## 🚨 Prerequisites
@@ -809,52 +1170,325 @@ Create `.commitlintrc.json`:
 }
 ```
 
+## 🔄 Migration Guide
+
+### Upgrading to Dynamic Matrix Version
+
+If you're upgrading from a previous version that didn't have dynamic matrix generation, here's what you need to know:
+
+#### Breaking Changes
+
+1. **Matrix Generation Creates Cartesian Product**
+   - **Old Behavior**: Only tested against first package version
+   - **New Behavior**: Tests ALL combinations of package versions
+   - **Impact**: More test jobs will run
+
+   ```text
+   # Old version (only tested symfony/framework-bundle 6.4.*)
+   versions-matrix: |
+     {
+       "php": ["8.2", "8.3"],
+       "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+     }
+   # Result: 2 jobs (PHP 8.2 + 6.4.*, PHP 8.3 + 6.4.*)
+
+   # New version (tests ALL combinations)
+   versions-matrix: |
+     {
+       "php": ["8.2", "8.3"],
+       "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+     }
+   # Result: 4 jobs (8.2+6.4.*, 8.2+7.0.*, 8.3+6.4.*, 8.3+7.0.*)
+  ```
+
+2. **Job Titles Now Include All Package Versions**
+   - **Old**: "Unit Tests (PHP 8.2, Symfony 6.4.*)"
+   - **New**: "Unit Tests (PHP 8.2, framework-bundle 6.4.*)"
+   - Titles show ALL packages from matrix
+
+3. **symfony/framework-bundle No Longer Special**
+   - Treated like any other package
+   - No special handling or priority
+
+#### What Stays the Same
+
+- ✅ Input parameters unchanged (fully backward compatible)
+- ✅ Default values unchanged
+- ✅ Secrets handling unchanged
+- ✅ Quality tools behavior unchanged
+- ✅ Composer caching unchanged
+
+#### Migration Steps
+
+**Step 1: Review Your versions-matrix**
+
+Check how many combinations your current matrix will create:
+
+```bash
+# Calculate combinations: PHP_versions × Package1_versions × Package2_versions × ...
+# Example: 3 PHP × 3 Symfony = 9 combinations
+```
+
+**Step 2: Add matrix-exclude if Needed**
+
+If you have too many combinations, exclude incompatible or unnecessary ones:
+
+```yaml
+versions-matrix: |
+  {
+    "php": ["8.2", "8.3", "8.4"],
+    "symfony/framework-bundle": ["6.4.*", "7.0.*", "7.3.*"]
+  }
+# This creates 9 combinations (3 × 3)
+
+# Add exclusions to reduce:
+matrix-exclude: |
+  [
+    {"php": "8.2", "symfony/framework-bundle": "7.3.*"},
+    {"php": "8.4", "symfony/framework-bundle": "6.4.*"}
+  ]
+# Now only 7 combinations
+```
+
+**Step 3: Test the Update**
+
+1. Create a test branch
+2. Update the workflow
+3. Open a PR to trigger CI
+4. Review which jobs run
+5. Adjust matrix-exclude if needed
+
+**Step 4: Optimize for CI Minutes**
+
+If you're concerned about CI minutes:
+
+```text
+# Option 1: Test fewer PHP versions
+versions-matrix: |
+  {
+    "php": ["8.2", "8.3"],  # Only test min and max
+    "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+  }
+
+# Option 2: Test only critical combinations
+versions-matrix: |
+  {
+    "php": ["8.3"],  # Only latest stable
+    "symfony/framework-bundle": ["7.0.*"]
+  }
+matrix-include: '[
+  {"php": "8.2", "symfony/framework-bundle": "6.4.*", "dependencies": "lowest"}
+]'
+
+# Option 3: Use matrix-exclude aggressively
+matrix-exclude: |
+  [
+    # Exclude all but critical combinations
+    {"php": "8.2", "symfony/framework-bundle": "7.0.*"},
+    {"php": "8.3", "symfony/framework-bundle": "6.4.*"}
+  ]
+```
+
+#### New Features to Adopt
+
+**1. Use php-version-quality-tools**
+
+Run quality tools on a single PHP version for faster analysis:
+
+```yaml
+with:
+  versions-matrix: '{"php": ["8.2", "8.3", "8.4"], ...}'
+  php-version-quality-tools: '8.4'  # ← Add this
+```
+
+**2. Test Multiple Packages**
+
+Now you can test any Composer packages:
+
+```yaml
+versions-matrix: |
+  {
+    "php": ["8.3"],
+    "symfony/framework-bundle": ["7.0.*"],
+    "doctrine/orm": ["3.0.*"],        # ← Add any packages
+    "monolog/monolog": ["^3.0"]       # ← They all work!
+  }
+```
+
+**3. Use matrix-include for Coverage**
+
+Add coverage to specific combinations:
+
+```yaml
+matrix-include: '[
+  {"php": "8.3", "symfony/framework-bundle": "7.0.*", "coverage": "xdebug"}
+]'
+```
+
+#### Example: Before & After
+
+**Before (Old Version):**
+```yaml
+uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@v1
+with:
+  versions-matrix: |
+    {
+      "php": ["8.2", "8.3"],
+      "symfony/framework-bundle": ["6.4.*", "7.0.*"]
+    }
+# Only tested: PHP 8.2+6.4.*, PHP 8.3+6.4.*
+```
+
+**After (New Version - Minimal Changes):**
+```yaml
+uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+with:
+  versions-matrix: |
+    {
+      "php": ["8.2", "8.3"],
+      "symfony/framework-bundle": ["6.4.*"]  # ← Reduce to 1 version if needed
+    }
+  # Add new features:
+  php-version-quality-tools: '8.3'
+# Tests all combinations: PHP 8.2+6.4.*, PHP 8.3+6.4.*
+```
+
+**After (New Version - Full Featured):**
+```yaml
+uses: MacPaw/github-actions/.github/workflows/symfony-php-reusable.yml@main
+with:
+  versions-matrix: |
+    {
+      "php": ["8.2", "8.3"],
+      "symfony/framework-bundle": ["6.4.*", "7.0.*"],
+      "doctrine/orm": ["3.0.*"]  # ← Add more packages
+    }
+  matrix-exclude: |
+    [
+      {"php": "8.2", "symfony/framework-bundle": "7.0.*"}
+    ]
+  php-version-quality-tools: '8.3'
+# Tests: 8.2+6.4.*, 8.3+6.4.*, 8.3+7.0.* (all with doctrine 3.0.*)
+```
+
+#### Troubleshooting Migration Issues
+
+**Issue: Too many test jobs**
+- **Solution**: Use matrix-exclude or reduce package versions
+
+**Issue: CI takes too long**
+- **Solution**: Test only min/max PHP versions, use php-version-quality-tools
+
+**Issue: Job names confusing**
+- **Solution**: Titles now show all packages - this is expected and provides better clarity
+
+**Issue: Coverage not uploading**
+- **Solution**: Ensure CODECOV_TOKEN is set, check coverage is enabled in matrix
+
 ## 🔧 Troubleshooting
 
 ### Common Issues
 
-#### 1. **Matrix Job Failures**
-   - **Symptom**: Specific PHP/Symfony combinations fail
+#### 1. **Matrix Generation Issues**
+   - **Symptom**: generate-matrix job fails or produces unexpected results
+   - **Solutions**:
+     - Verify `versions-matrix` is valid JSON
+     - Ensure `php` key exists in versions-matrix
+     - Check that package names are in `vendor/package` format
+     - Verify matrix-exclude and matrix-include are valid JSON arrays
+   - **Debug**:
+     ```yaml
+     # Check the generate-matrix job output in GitHub Actions
+     # It shows the generated matrix JSON
+     ```
+
+#### 2. **Too Many Matrix Combinations**
+   - **Symptom**: Workflow creates hundreds of test jobs
+   - **Calculation**: Jobs = PHP versions × Package1 versions × Package2 versions × ...
+   - **Solutions**:
+     ```text
+       # Option 1: Reduce package versions
+       versions-matrix: |
+         {
+           "php": ["8.3"],  # Only test one PHP version
+           "symfony/cache": ["7.0.*"]  # Only test one version per package
+         }
+
+       # Option 2: Use matrix-exclude aggressively
+       matrix-exclude: |
+         [
+           {"php": "8.2", "symfony/cache": "7.0.*"},
+           {"php": "8.3", "symfony/cache": "6.4.*"}
+         ]
+
+       # Option 3: Use matrix-include instead (whitelist approach)
+       versions-matrix: '{"php": ["8.3"]}'  # Base matrix
+       matrix-include: '[
+         {"php": "8.3", "symfony/cache": "7.0.*", "symfony/config": "7.0.*"},
+         {"php": "8.2", "symfony/cache": "6.4.*", "symfony/config": "6.4.*"}
+       ]'
+       ```
+
+#### 3. **Matrix Job Failures**
+   - **Symptom**: Specific PHP/package combinations fail
    - **Solution**: Review compatibility and add to `matrix-exclude`
    - **Example**:
      ```yaml
      matrix-exclude: |
        [
-         {"php": "8.1", "symfony": "7.0.*"}
+         {"php": "8.1", "symfony/framework-bundle": "7.0.*"}
        ]
      ```
+   - **Important**: Use exact package names as they appear in versions-matrix
 
-#### 2. **Composer Installation Failures**
+#### 4. **Composer Installation Failures**
    - **Symptom**: `composer install` or `composer update` fails
    - **Solutions**:
      - Check `composer.json` syntax
      - Verify PHP version compatibility
-     - Review Symfony version constraints
+     - Review package version constraints
      - Check for conflicting dependencies
+     - Ensure packages exist in versions-matrix are valid Composer packages
+   - **Debug**:
+     ```bash
+     # Test locally with same constraints
+     composer require "symfony/cache:7.0.*" --no-update
+     composer update -vvv
+     ```
 
-#### 3. **Coverage Upload Failures**
+#### 5. **Coverage Upload Failures**
    - **Symptom**: Codecov upload fails
    - **Solutions**:
      - Verify `CODECOV_TOKEN` secret is set
-     - Check coverage file is generated: `coverage.xml`
+     - Check coverage file is generated: defaults to `coverage.xml` (or your custom `coverage-file`)
      - Review PHPUnit coverage configuration
+     - Ensure coverage is enabled in matrix (add `"coverage": "xdebug"` to matrix combination via `matrix-include`)
+     - Verify xdebug is working
      - Note: Workflow continues even if upload fails
 
-#### 4. **Tool Configuration Missing**
+#### 6. **Tool Configuration Missing**
    - **Symptom**: PHPStan, PHPCS, or other tools fail
    - **Solutions**:
      - Ensure configuration files exist
      - Verify tools are in `composer.json` require-dev
-     - Check configuration file paths
+     - Check configuration file paths with custom config parameters
      - Validate configuration syntax
+     - Check php-version-quality-tools is compatible with tool versions
 
-#### 5. **Version Compatibility Issues**
+#### 7. **Version Compatibility Issues**
    - **Symptom**: Tests pass locally but fail in CI
    - **Solutions**:
      - Check PHP version differences
-     - Verify Symfony version constraints
+     - Verify package version constraints from matrix are being applied
      - Test with `composer update --prefer-lowest`
      - Review deprecation warnings
+     - Check the "Apply package version constraints" step output in CI logs
+
+#### 8. **Job Titles Not Showing Package Versions**
+   - **Symptom**: Job titles show "Unit Tests ()" or incomplete information
+   - **Solution**: This is expected if no packages in versions-matrix (PHP-only matrix)
+   - **For PHP-only**: Titles will be "Unit Tests (PHP X.Y)"
+   - **With packages**: Titles will be "Unit Tests (PHP X.Y, package1 version, package2 version, ...)"
 
 ### Debug Mode
 
@@ -927,20 +1561,28 @@ To add a new quality tool:
 
 ### 1. **Start Minimal**
 Begin with basic configuration and enable tools progressively:
-```yaml
+```text
 # Phase 1: Testing only
-enable-phpstan: true
-enable-phpcs: false
-enable-code-coverage: false
+with:
+  versions-matrix: '{"php": ["8.3"], "symfony/framework-bundle": ["7.0.*"]}'
+  enable-phpstan: true
+  enable-phpcs: false
 
-# Phase 2: Add quality checks
-enable-phpcs: true
-enable-code-coverage: true
+# Phase 2: Add quality checks and coverage
+with:
+  versions-matrix: '{"php": ["8.2", "8.3"], "symfony/framework-bundle": ["6.4.*", "7.0.*"]}'
+  enable-phpstan: true
+  enable-phpcs: true
+  # Add coverage to one combination
+  matrix-include: '[{"php": "8.3", "symfony/framework-bundle": "7.0.*", "coverage": "xdebug"}]'
 
 # Phase 3: Advanced tools
-enable-php-cs-fixer: true
-enable-rector: true
-enable-infection: true
+with:
+  enable-phpstan: true
+  enable-phpcs: true
+  enable-php-cs-fixer: true
+  enable-rector: true
+  enable-infection: true
 ```
 
 ### 2. **Version Matrix Strategy**
@@ -950,8 +1592,11 @@ enable-infection: true
 - Use exclusions for known incompatibilities
 
 ### 3. **Code Coverage**
-- Enable coverage on at least one matrix job
-- Set realistic minimum thresholds
+- Enable coverage on specific matrix combinations via `matrix-include`
+- Add `"coverage": "xdebug"` to the desired test combination
+- Example: `matrix-include: '[{"php": "8.3", "symfony/framework-bundle": "7.0.*", "coverage": "xdebug"}]'`
+- xdebug extension is automatically added when coverage is enabled
+- Set realistic minimum thresholds for mutation testing
 - Review coverage trends in PRs
 - Use Codecov for historical tracking