Php Cs Fixer Config Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: This package is a PHP CS Fixer configuration preset tailored for prooph components, which are built on Laravel/PHP but follow a Domain-Driven Design (DDD) and Event Sourcing/CQRS architecture. While not a runtime dependency, it enforces consistent code style—critical for maintainability in large-scale DDD projects.
• Non-Invasive: Since it’s purely a linting/configuration tool, it doesn’t alter core functionality but ensures adherence to prooph’s coding standards, reducing friction in collaborative environments.
• Laravel Compatibility: Laravel’s default PHP CS Fixer rules may conflict with prooph’s conventions (e.g., PSR-12 vs. prooph’s DDD-specific formatting). This package bridges that gap.

Integration Feasibility

• Low Effort: Integration involves adding a single config file (prooph.php-cs-fixer-config) to a project’s PHP CS Fixer setup (via rules or config).
• Toolchain Dependency: Requires PHP CS Fixer (v3.x+) and Composer—both are standard in Laravel ecosystems.
• CI/CD Readiness: Can be gated in PR pipelines (e.g., GitHub Actions) to enforce consistency pre-merge.

Technical Risk

• Rule Conflicts: Potential clashes with existing Laravel/PHP CS Fixer configs (e.g., array_syntax, class_attributes). Mitigation: Merge configs or override specific rules.
• Maintenance Overhead: If prooph updates its config, local overrides may break. Solution: Pin to a stable version or fork if needed.
• False Positives: Some rules may flag prooph-specific patterns (e.g., event sourcing annotations) as violations. Document exceptions in team guidelines.

Key Questions

1. Does the team already use PHP CS Fixer? If not, adoption requires toolchain setup.
2. Are there existing style guides? Overlap with Laravel’s default rules (e.g., psr12) may need resolution.
3. How strict should enforcement be? Should this be mandatory (blocking CI) or advisory (linter-only)?
4. Will prooph’s config evolve? Plan for version pinning or custom forks if needed.
5. Does the team use DDD/CQRS? If not, some rules (e.g., event naming) may feel irrelevant.

Integration Approach

Stack Fit

• PHP CS Fixer Integration:
  • Option 1: Replace or extend existing .php-cs-fixer.dist.php with prooph’s config.
  • Option 2: Merge configs using RuleSet or Config composition.
  • Example:

    use Prooph\PhpCsFixerConfig\Config;
    
    $finder = PhpCsFixer\Finder::create()->in(__DIR__);
    $config = new Config();
    $rules = $config->getRules();
    $configurator = new PhpCsFixer\Config();
    $configurator->setRules($rules)->setFinder($finder);
    

• Laravel-Specific: If using Laravel Mix/Pint, ensure compatibility by excluding prooph-specific rules that conflict with Laravel’s defaults.

Migration Path

1. Audit Current Setup:
   • Run php-cs-fixer fix --dry-run with current rules to identify conflicts.
2. Incremental Adoption:
   • Start with non-breaking rules (e.g., indentation, line breaks).
   • Gradually introduce prooph-specific rules (e.g., event naming).
3. CI/CD Rollout:
   • Add as a pre-commit hook (via php-cs-fixer or robo.phar).
   • Enforce in PR checks before merging.

Compatibility

• PHP Version: Requires PHP 8.0+ (check prooph’s composer.json).
• Laravel Version: No direct dependency, but Laravel 9+ (PHP 8.0+) is recommended for compatibility.
• Tooling:
  • Works with PHP CS Fixer v3.x, Pint, or Laravel Valet/Sail.
  • Avoid conflicts with PSR-12 by whitelisting exceptions (e.g., prooph/event-store annotations).

Sequencing

1. Phase 1: Configure prooph’s rules in development environments.
2. Phase 2: Enforce in CI pipelines (e.g., GitHub Actions).
3. Phase 3: Integrate with pre-commit hooks (e.g., Husky + simple-php-unit).
4. Phase 4: Document custom overrides for prooph-specific patterns.

Operational Impact

Maintenance

• Low Ongoing Cost: Once configured, no runtime maintenance is needed.
• Config Updates: Monitor prooph’s releases for rule changes; update semantically (e.g., minor version bumps).
• Forking Strategy: If prooph’s config becomes incompatible, maintain a fork with pinned rules.

Support

• Developer Onboarding: Reduces style-related bugs by standardizing formatting.
• Debugging: Clear error messages from PHP CS Fixer help quickly identify violations.
• Tooling Support: Leverage VS Code/PHPStorm plugins for real-time feedback.

Scaling

• Team Growth: Scales well with new contributors by enforcing consistency.
• Monorepo Impact: If used across multiple Laravel services, ensure shared config or service-specific overrides.
• Performance: PHP CS Fixer runs locally, so no runtime overhead.

Failure Modes

• False Positives: Rules may flag legitimate prooph patterns (e.g., EventInterface implementations). Document exceptions in a STYLE_GUIDE.md.
• Toolchain Breakage: If PHP CS Fixer or Composer updates deprecate APIs, test backward compatibility.
• Over-Restrictiveness: Too many rules may hinder productivity. Start with a subset and expand gradually.

Ramp-Up

• Training: Hold a 30-minute session on:
  • How to run PHP CS Fixer locally.
  • Common prooph-specific rules (e.g., event naming, DDD terminology).
• Documentation:
  • Add a .all-contributors-ready/ badge for style compliance.
  • Example .php-cs-fixer.dist.php in the repo.
• Feedback Loop: Collect rule suggestions from the team and propose updates to prooph’s config.