Grumphp Fractor Task Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package integrates Fractor (a static analysis tool for PHP/TYPO3) into GrumPHP, aligning with Laravel’s need for pre-commit static analysis to enforce type safety, naming conventions, and structural consistency. It complements Laravel’s existing toolchain (PHPStan, PHP-CS-Fixer) without disrupting core architecture.
• Modularity: As a GrumPHP extension, it integrates seamlessly into Laravel’s CI/CD pipelines and pre-commit hooks, running asynchronously to avoid blocking workflows. The task’s configurable triggers (triggered_by) and ignore patterns allow granular control, critical for Laravel’s monorepo or multi-package setups (e.g., ignoring vendor/, node_modules/).
• Extensibility: The package’s customizable Fractor config enables adaptation to Laravel-specific needs (e.g., overriding TYPO3-centric rules for Laravel’s service container, dynamic properties, or strict typing enforcement).

Integration Feasibility

• Low Coupling: Requires only Composer and GrumPHP, both already standard in Laravel ecosystems. No Laravel-specific dependencies, though Fractor’s TYPO3 focus may necessitate custom rule overrides for vanilla Laravel projects.
• Configuration Overhead: Minimal—primarily YAML config for GrumPHP. However, Fractor’s default rules (e.g., TYPO3-specific) may require customization for Laravel (e.g., adjusting declare(strict_types=1) enforcement or class naming conventions).
• Dependency Risks:
  • Fractor’s Maturity: New package (2026) with no active community or dependents. Risk of abandonware or breaking changes.
  • License Compatibility: GPL-3.0 may conflict with Laravel’s MIT/License. Audit dependencies for compliance.
  • PHP Version: Confirm Fractor supports Laravel’s PHP 8.1+ requirements.

Technical Risk

• Rule Conflicts:
  • Strict Typing: Fractor’s declare(strict_types=1) enforcement may clash with Laravel’s legacy code or dynamic properties (e.g., __get() magic methods).
  • Naming Conventions: Rules like class_naming may conflict with Laravel’s PSR-4 or service container conventions.
  • Mitigation: Customize fractor.php to override defaults or ignore specific patterns (e.g., ignore_patterns: ["app/Providers/AppServiceProvider.php"]).
• Performance:
  • Local Dev: Static analysis can slow down pre-commit hooks. Mitigate with caching (clear_cache: false) and parallel task execution.
  • CI: Uncached runs may increase build times (10–30s). Benchmark and optimize with file filtering (ignore_patterns).
• Toolchain Synergy:
  • Overlap with PHPStan/Psalm: Risk of redundant checks (e.g., duplicate strict_types validation).
  • Mitigation: Align rules between tools or disable overlapping checks in one tool.

Key Questions

1. Use Case Justification:
   • Does Laravel’s codebase require Fractor’s specific rules (e.g., TYPO3 extensions) or can existing tools (PHPStan, Psalm, Rector) suffice?
   • Are there custom Fractor rules already defined for Laravel (e.g., service container naming, dynamic property handling)?
2. Rule Customization:
   • How will Fractor’s defaults be overridden for Laravel (e.g., relaxing strict_types in non-PHP 8.1 files, ignoring magic methods)?
   • Example: Define a fractor.php config to exclude Laravel-specific edge cases:

     return [
         'rules' => [
             'strict_types' => ['active' => true, 'level' => 'warning', 'ignore_files' => ['app/Helpers/*.php']],
             'class_naming' => ['prefix' => 'App\\', 'suffix' => '', 'ignore' => ['*ServiceProvider']],
         ],
     ];
     

3. CI/CD Impact:
   • Will Fractor’s exit codes integrate with Laravel’s CI (GitHub Actions/GitLab CI) failure thresholds?
   • Example: Configure GitHub Actions to fail fast on Fractor errors:

     - name: Run GrumPHP
       run: ./vendor/bin/grumphp run --strict --exit-code-env GRUMPHP_EXIT_CODE
     - name: Check exit code
       if: env.GRUMPHP_EXIT_CODE != '0'
       run: exit 1
     

4. Toolchain Synergy:
   • How will this complement/exclude existing tools (e.g., laravel-pint, rector, phpstan) to avoid redundancy?
   • Example: Run Fractor after phpcsfixer (formatting) but before phpstan (type checking):

     tasks:
       phpcs_fixer: ~
       fractor: ~
       phpstan: ~
     

5. License Compliance:
   • GPL-3.0 may conflict with Laravel’s MIT/License. Audit dependencies for compatibility. Consider forking if licensing is a blocker.
6. Maintenance Burden:
   • Who will maintain custom Fractor rules and update configs as Laravel evolves?
   • Example: Assign a tech lead to own fractor.php and document rule changes in ADRs.

Integration Approach

Stack Fit

• GrumPHP Integration:
  • Native Fit: GrumPHP is already used in Laravel for pre-commit hooks (e.g., grumphp.yml in .github/). This package extends that workflow without reinvention.
  • Toolchain Placement:
    • Local Dev: Run in pre-commit (fast feedback) with cached results (clear_cache: false).
    • CI: Run in build phase (uncached, strict mode) alongside PHPStan/Pint.
  • Complementary Tools:
    • PHPStan: Handles type checking; Fractor handles structural rules (e.g., class naming, method ordering).
    • Rector: Handles refactoring; Fractor handles static analysis.
    • PHP-CS-Fixer: Handles formatting; Fractor handles code structure.
• Fractor’s Role:
  • Unique Value: Enforces TYPO3/Laravel-specific conventions (e.g., declare(strict_types=1), class naming) not covered by PHPStan or Psalm.
  • Overlap: Avoid duplicate checks (e.g., strict_types) by disabling in one tool.

Migration Path

1. Pilot Phase:
   • Add to composer.json:

     composer require --dev andersundsehr/grumphp-fractor-task
     

   • Configure GrumPHP (grumphp.yml):

     grumphp:
       tasks:
         fractor:
           config: "config/fractor.php"  # Custom Laravel-specific config
           ignore_patterns: ["vendor/", "tests/", "node_modules/", "storage/"]
           clear_cache: false  # Enable caching for local dev
           no_diffs: true      # Disable diffs in CI for cleaner output
       extensions:
         - Andersundsehr\GrumPHPFractorTask\ExtensionLoader
     

   • Define fractor.php (override defaults for Laravel):

     return [
         'rules' => [
             'strict_types' => [
                 'active' => true,
                 'level' => 'warning',
                 'ignore_files' => ['app/Helpers/*.php', 'app/Exceptions/Handler.php'],
             ],
             'class_naming' => [
                 'prefix' => 'App\\',
                 'suffix' => '',
                 'ignore' => ['*ServiceProvider', '*Factory', '*Repository'],
             ],
             'method_ordering' => ['active' => true, 'order' => ['public', 'protected', 'private']],
         ],
         'paths' => ['app/', 'src/', 'packages/'],  # Scope to Laravel-specific paths
     ];
     

2. Gradual Rollout:
   • Local Testing: Run ./vendor/bin/grumphp run manually to validate. Use --no-cache to test CI behavior locally.
   • CI Integration: Add to .github/workflows/ci.yml as a separate job (fail-fast):

     - name: Run Fractor
       run: ./vendor/bin/grumphp run --test --exit-code-env GRUMPHP_EXIT_CODE
     - name: Check Fractor
       if: env.GRUMPHP_EXIT_CODE != '0'
       run: exit 1
     

   • Opt-in Teams: Roll out to **