Coding Style Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • PSR-12 Alignment: Extends PSR-12 with custom Laravel-specific rules, ensuring consistency with modern PHP/Laravel standards.
  • Toolchain Integration: Bundles ECS, PHPStan, and Rector, enabling static analysis, type checking, and automated refactoring—critical for maintainable Laravel codebases.
  • Laravel-Specific Enforcement: Custom rules (e.g., DisallowEnvUsageSniff, DisallowHasFactorySniff) enforce best practices tailored to Laravel’s ecosystem (e.g., preferring factories over HasFactory, discouraging env() helpers).
  • Automation-Ready: Designed for CI/CD pipelines with auto-fixable rules (via ECS) and strict type enforcement (PHPStan).
  • Customizability: Allows overriding defaults (e.g., event listener suffixes, enum casing) via configuration.

• Gaps:

  • Laravel Version Lock: No explicit Laravel version compatibility matrix (risk of breaking changes if using older/new Laravel versions).
  • Opinionated Rules: Some rules (e.g., DisallowPHPUnit, DisallowEnvUsage) may conflict with legacy codebases or team preferences.
  • Blade-Specific Rules: Limited Blade linting (only directory enforcement), which may require additional tools (e.g., laravel-pint) for full Blade compliance.

Integration Feasibility

• Composer-Based: Zero friction—installs via composer require --dev and generates configs via a single CLI command.
• Laravel Native: Works seamlessly with Laravel’s project structure (e.g., resources/ for Blade files, app/ for business logic).
• Toolchain Synergy:
  • ECS: Replaces or augments php-cs-fixer with stricter rules.
  • PHPStan: Enhances Laravel’s built-in type safety (e.g., declare(strict_types=1) enforcement).
  • Rector: Enables safe, automated refactoring (e.g., migrating from env() to config).
• CI/CD Friendly: Scripts (composer ecs, composer phpstan) are pre-configured for GitHub Actions, GitLab CI, etc.

Technical Risk

• High:
  • Breaking Changes: Custom rules (e.g., DisallowHasFactorySniff) may require significant refactoring in existing codebases.
  • Toolchain Conflicts: Potential overlaps with existing tools (e.g., laravel-pint, pint, or custom PHPStan configs).
  • Performance Overhead: PHPStan and Rector add runtime overhead during development (mitigated by caching).
• Medium:
  • Laravel Version Drift: Rules may assume newer Laravel features (e.g., enums, modern migrations).
  • Blade Limitations: Blade-specific rules are minimal; advanced Blade linting requires additional tools.
• Low:
  • MIT License: No legal barriers.
  • Documentation: README is clear, though custom rules lack detailed rationale.

Key Questions

1. Compatibility:
   • What Laravel version is the target project using? (Rules may assume Laravel 9+ features like enums or modern migrations.)
   • Are there existing tools (e.g., pint, custom PHPStan configs) that could conflict?
2. Adoption Impact:
   • How will the team react to opinionated rules (e.g., DisallowPHPUnit, DisallowEnvUsage)?
   • Are there legacy patterns (e.g., HasFactory, env() helpers) that need grandfathering?
3. Toolchain Integration:
   • Should ECS/PHPStan/Rector replace or supplement existing tools?
   • How will caching (e.g., PHPStan’s result cache) be managed in CI vs. local dev?
4. Customization:
   • Are there rules that need overriding (e.g., event listener suffixes, enum casing)?
   • Should the package’s configs be forked or extended?
5. Performance:
   • Will PHPStan/Rector runs slow down local development? (Mitigate with phpstan --generate-baseline.)
6. Blade Support:
   • Are there additional Blade-specific rules needed (e.g., directive validation, component naming)?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Laravel 9+ projects prioritizing code quality, type safety, and automated refactoring.
• Stack Synergy:
  • PHP 8.1+: Leverages modern PHP features (enums, attributes, strict typing).
  • Laravel Ecosystem: Aligns with Laravel’s conventions (e.g., app/, resources/, migration patterns).
  • DevOps: Integrates with GitHub Actions/GitLab CI via Composer scripts.
• Anti-Patterns:
  • Avoid in legacy Laravel (pre-8.x) or projects using custom toolchains (e.g., custom PHPStan configs).
  • Not suitable for non-Laravel PHP projects (rules are Laravel-specific).

Migration Path

1. Assessment Phase:
   • Audit existing code for conflicts (e.g., HasFactory, env() usage, Blade files outside resources/).
   • Check for overlapping tools (e.g., pint, php-cs-fixer).
2. Pilot Phase:
   • Install in a feature branch or monorepo:

     composer require --dev worksome/coding-style
     composer generate-coding-style-stubs
     

   • Run in dry mode first:

     composer ecs --dry-run
     composer phpstan analyse --no-progress
     composer rector process --dry-run
     

3. Incremental Adoption:
   • Phase 1: Enforce ECS rules (auto-fixable) in CI.
   • Phase 2: Add PHPStan to CI (fail builds on errors).
   • Phase 3: Introduce Rector for safe refactoring (e.g., env() → config).
4. Legacy Handling:
   • Use PHPStan’s baseline to ignore existing violations temporarily.
   • Override rules via .phpstan.neon or ecs.php:

     includes:
       - vendor/worksome/coding-style/phpstan/laravel.neon
       - vendor/worksome/coding-style/phpstan/generic.neon
     

Compatibility

Sequencing

1. Pre-Integration:
   • Backup existing .php-cs-fixer.dist.php, phpstan.neon, and Rector configs.
   • Document current toolchain (e.g., pint, custom sniffs).
2. Installation:
   • Run composer require --dev worksome/coding-style.
   • Generate stubs: composer generate-coding-style-stubs.
3. Configuration:
   • Merge custom rules into ecs.php/phpstan.neon if needed.
   • Update composer.json scripts:

     "scripts": {
       "lint": "composer ecs && composer phpstan analyse --no-progress",
       "fix": "composer ecs:fix && composer rector:fix"
     }
     

4. CI Setup:
   • Add to CI pipeline (e.g., GitHub Actions):

     - name: Lint
       run: composer lint
     - name: Fix (optional)
       run: composer fix
     

5. Post-Integration:
   • Train team on new rules (e.g., DisallowEnvUsageSniff).
   • Monitor false positives in PHPStan (adjust baseline as needed).

Operational Impact

Maintenance

• Pros:
  • Reduced Cognitive Load: Enforces consistent style across the team.
  • Automated Fixes: ECS and Rector handle many violations automatically.
  • Type Safety: PHPStan catches bugs early (e.g., incorrect method signatures).
• Cons:
  • Rule Maintenance: Custom rules (e.g., DisallowHasFactorySniff) may need updates for Laravel releases.
  • Config Drift: Overriding defaults requires ongoing management of `ecs.php