PHPStan task incompatible with baseline functionality - hangs when processing individual files

[tormi]

Problem Description

The Wunderio PHPStan task (Wunderio\GrumPHP\Task\PhpStan\PhpStanTask) is incompatible with PHPStan's baseline functionality, causing the task to hang or fail during execution.

Technical Details

Root Cause:
The Wunderio PHPStan task extends AbstractMultiPathProcessingTask and processes files individually by adding each file as a separate argument to the PHPStan command:

// From PhpStanTask.php lines 34-36
foreach ($files as $file) {
  $arguments->add($file);
}

Why This Breaks Baselines:

• PHPStan baselines require the tool to analyze all configured paths together as a cohesive project
• Individual file analysis prevents PHPStan from understanding the full context needed for baseline matching
• The baseline file contains project-wide error patterns that only make sense when analyzing the complete codebase

Observed Behavior:

• PHPStan task hangs indefinitely when baseline is configured
• No error output or completion status
• Other GrumPHP tasks complete successfully

Current Workaround

Users must:

1. Remove the Wunderio PHPStan extension from grumphp.yml:

   extensions:
     # - Wunderio\GrumPHP\Task\PhpStan\PhpStanExtensionLoader  # Remove this

2. Use the standard GrumPHP PHPStan task instead:

   tasks:
     phpstan:  # Note: 'phpstan' not 'php_stan'
       configuration: phpstan.neon
       memory_limit: "1G"
       use_grumphp_paths: false  # Let PHPStan use its own path config

Suggested Solutions

Option 1: Configuration Flag

Add a configuration option to the Wunderio PHPStan task:

tasks:
  php_stan:
    use_individual_files: false  # Default: true for backward compatibility
    configuration: phpstan.neon

When use_individual_files: false, the task should rely on PHPStan's configuration file for paths instead of processing individual files.

Option 2: Documentation

Provide clear guidance on when to use:

• Wunderio PHPStan task: For file-by-file analysis without baselines
• Standard GrumPHP PHPStan task: For project-wide analysis with baseline support

Option 3: Auto-detection

Detect if a baseline file is configured and automatically switch to project-wide analysis mode.

Impact

This issue affects:

• Projects implementing PHPStan level 9 with baseline files for gradual code quality improvement
• Teams wanting to establish quality gates while managing technical debt
• CI/CD pipelines that hang due to the PHPStan task not completing

Environment

• wunderio/code-quality: Latest version
• PHPStan: Level 9 with baseline file
• GrumPHP: Via wunderio/code-quality
• Use case: Drupal projects with custom modules

Example Configuration That Fails

# grumphp.yml
tasks:
  php_stan:
    configuration: phpstan.neon
    memory_limit: "1G"
extensions:
  - Wunderio\GrumPHP\Task\PhpStan\PhpStanExtensionLoader

# phpstan.neon
includes:
  - phpstan-baseline.neon
parameters:
  level: 9
  paths:
    - web/modules/custom

This configuration causes the PHPStan task to hang indefinitely.

---

Would appreciate guidance on the preferred approach for resolving this incompatibility. Happy to contribute a PR once the direction is clarified!

[tormi]

Additional Issue: Task Name Conflict

While implementing the workaround, I encountered an additional error that others might face:

Error Encountered

PHP Fatal error: Uncaught Symfony\Component\OptionsResolver\Exception\InvalidOptionsException: 
The testsuite option "tasks" contains the unknow task "php_stan". 
Expected one of git_commit_message,php_compatibility,check_file_permissions,php_check_syntax,phpcs,phpstan,phpunit,yaml_lint,json_lint

Root Cause

The error occurs when you have:

1. Wunderio PHPStan extension loaded → provides php_stan task
2. Standard GrumPHP PHPStan task configured → provides phpstan task
3. Testsuites referencing the wrong task name

Complete Solution

To fully resolve the baseline incompatibility, you need to:

1. Remove the Wunderio PHPStan extension:

   extensions:
     # - Wunderio\GrumPHP\Task\PhpStan\PhpStanExtensionLoader  # Remove this line

2. Configure the standard PHPStan task:

   tasks:
     phpstan:  # Note: 'phpstan' not 'php_stan'
       configuration: phpstan.neon
       memory_limit: "1G"
       use_grumphp_paths: false

3. Update testsuites to use correct task name:

   testsuites:
     git_pre_commit:
       tasks:
         - phpstan  # Changed from 'php_stan' to 'phpstan'

This ensures you're using the standard GrumPHP PHPStan task that's compatible with baseline files, rather than the Wunderio version that processes files individually.

[tormi]

✅ Real-World Implementation Example

We've successfully implemented this workaround in a production Drupal project. Here's the complete implementation:

Commit: feat(FSD-344): Implement PHPStan level 9 with baseline for code quality gate

Key Changes Made

1. Removed Wunderio PHPStan Extension:

   - Wunderio\GrumPHP\Task\PhpStan\PhpStanExtensionLoader
   + # - Wunderio\GrumPHP\Task\PhpStan\PhpStanExtensionLoader  # Removed: incompatible with baseline

2. Switched to Standard GrumPHP PHPStan Task:

   tasks:
     phpstan:  # Changed from 'php_stan'
       configuration: phpstan.neon
       memory_limit: "1G"
       use_grumphp_paths: false  # Let PHPStan use its own config

3. Updated Testsuites:

   - php_stan
   + phpstan

4. PHPStan Configuration with Baseline:

   # phpstan.neon
   includes:
     - phpstan-baseline.neon
   parameters:
     level: 9
     paths:
       - web/modules/custom
       - web/themes/custom

Results

• ✅ PHPStan Level 9: Successfully running with xxx baseline issues
• ✅ Quality Gate: New code must pass level 9 analysis (0 errors allowed)
• ✅ CI/CD Integration: All GrumPHP tasks complete without hanging
• ✅ Developer Experience: Custom ddev phpstan command for direct execution

Production Benefits

• Gradual Improvement: Existing technical debt is baselined, new code meets high standards
• No Disruption: Development workflow continues smoothly
• Quality Enforcement: Prevents introduction of new code quality issues
• Team Adoption: Easy integration with existing DDEV/GrumPHP workflow

This implementation demonstrates that the workaround is production-ready and provides significant value for teams wanting to establish strict code quality standards while managing existing technical debt.