Imbo Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Leverage for Laravel/PHP Projects: This package enforces a consistent, opinionated coding standard tailored for Imbo’s PHP/Laravel ecosystem. While not Laravel-specific, it aligns with modern PHP best practices (e.g., strict typing, PSR-12 compliance, and Imbo’s internal conventions).
• Complementary to Laravel’s Tooling: Integrates seamlessly with Laravel’s existing workflows (Composer, GitHub Actions, PHP-CS-Fixer) without requiring architectural changes.
• Rule Customization: The standard is extensible—teams can override specific rules via PHP-CS-Fixer’s config while adhering to Imbo’s baseline.

Integration Feasibility

• Low-Coupling: Purely a linting/fixing tool—no runtime dependencies or Laravel service provider requirements.
• Dependency Overhead: Minimal (php-cs-fixer + this package), with no breaking changes to existing Laravel core or third-party packages.
• CI/CD Readiness: Designed for pre-commit hooks and GitHub Actions, fitting Laravel’s CI pipelines (e.g., Laravel’s default phpunit workflows).

Technical Risk

• Rule Conflicts: Potential clashes with:
  • Team-specific PSR-12/PHP-CS-Fixer rules (e.g., custom line lengths, naming conventions).
  • Laravel’s own coding standards (e.g., laravel-shift/php-coding-standard).
  • Mitigation: Audit rules via php-cs-fixer fix --dry-run before full adoption.
• Performance: Parallel execution is supported, but large codebases (e.g., monorepos) may require tuning --parallel config.
• Tooling Ecosystem: Assumes PHP-CS-Fixer v3+ and Composer 2.x. Older Laravel projects (pre-8.x) may need minor adjustments.

Key Questions

1. Alignment with Team Standards:
   • Does Imbo’s standard conflict with existing team rules (e.g., laravel-shift or custom PSR-12 overrides)?
   • Are there Laravel-specific rules (e.g., Facade usage, Blade templates) not covered here?
2. Adoption Scope:
   • Should this replace or supplement existing linters (e.g., phpstan, psalm)?
   • Will it be enforced only in CI or also via pre-commit hooks (e.g., Husky)?
3. Customization Needs:
   • Are there Imbo-specific rules (e.g., naming conventions for Laravel services) that require extension?
4. Performance:
   • How will this scale for large Laravel apps (e.g., 50K+ LOC)?
   • Should --parallel be configured per environment (local vs. CI)?

Integration Approach

Stack Fit

• Native Compatibility:
  • Laravel: Works out-of-the-box with Laravel’s Composer-based workflows.
  • PHP-CS-Fixer: Already a dependency in many Laravel projects (via laravel-shift or manual setup).
  • GitHub Actions: Directly compatible with Laravel’s CI templates.
• Tooling Synergy:
  • Pairs well with:
    • Laravel Pint (if team prefers Symfony’s alternative).
    • PHPStan/Psalm for static analysis (this package focuses on style, not logic).
  • Avoid Redundancy: If using laravel-shift/php-coding-standard, evaluate overlap before adoption.

Migration Path

1. Pilot Phase:
   • Install in a non-critical branch (e.g., feature/coding-standards).
   • Run composer require --dev imbo/imbo-coding-standard friendsofphp/php-cs-fixer.
   • Configure .php-cs-fixer.dist.php and test with:

     vendor/bin/php-cs-fixer fix --dry-run
     

2. Incremental Enforcement:
   • Add to CI (GitHub Actions) as a warning first, then blocking.
   • Gradually introduce pre-commit hooks (e.g., Husky) for local enforcement.
3. Rule Customization:
   • Extend the config to override specific rules (e.g., line lengths) if needed:

     $config->setRules([
         '@Imbo' => true,
         'phpcsrisky:risky' => false, // Example: Disable a rule
     ]);
     

Compatibility

• Laravel Versions:
  • Laravel 8+: Full compatibility (PHP 8.0+).
  • Laravel 7.x: May require PHP-CS-Fixer v2.x adjustments (deprecated in this package).
• PHP Versions:
  • Requires PHP 8.0+ (strict types enforced). Older Laravel apps may need upgrades.
• Package Conflicts:
  • Low risk unless another coding standard (e.g., laravel-shift) is already enforced.

Sequencing

1. Pre-Integration:
   • Audit existing codebase for violations:

     vendor/bin/php-cs-fixer fix --allow-risky=yes --diff
     

   • Document exceptions for custom rules.
2. CI Integration:
   • Add to GitHub Actions after tests pass (fail-fast principle).
   • Example workflow snippet:

     jobs:
       coding-standards:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: shivammathur/setup-php@v2
             with:
               php-version: '8.2'
           - run: composer install
           - run: vendor/bin/php-cs-fixer fix --diff --dry-run
     

3. Local Development:
   • Add Composer scripts:

     {
       "scripts": {
         "cs-check": "php-cs-fixer check --diff",
         "cs-fix": "php-cs-fixer fix"
       }
     }
     

   • Integrate with Husky for pre-commit checks:

     {
       "husky": {
         "hooks": {
           "pre-commit": "composer cs-check"
         }
       }
     }
     

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Rules are static (no runtime maintenance).
  • Updates to the package require Composer updates and re-auditing.
• Rule Updates:
  • Monitor imbo/imbo-coding-standard for new rules (e.g., PHP 8.3 compatibility).
  • Strategy: Pin to a minor version (e.g., ^3.0) to avoid breaking changes.

Support

• Troubleshooting:
  • Common issues:
    • False positives: Customize rules or exclude files:

      $finder->exclude(['storage', 'tests/Feature/BrokenTest.php']);
      

    • Performance: Adjust --parallel or exclude large directories.
  • Debugging: Use --verbose flag for detailed output.
• Team Adoption:
  • Training: Document key rules (e.g., strict typing, method ordering).
  • Onboarding: Add a CONTRIBUTING.md section for new devs.

Scaling

• Large Codebases:
  • Parallel Execution: Enable by default (config auto-detects CPU cores).
  • Incremental Fixing: Use --path-mode=diff to only fix changed files in CI.
  • Exclusions: Skip generated files (e.g., bootstrap/cache):

    $finder->exclude(['bootstrap/cache', 'vendor']);
    

• Monorepos:
  • Configure $finder->in([__DIR__.'/packages/*']) to target specific paths.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Documentation: Add a CODE_STYLE.md with:
    • Key rules (e.g., "Use declare(strict_types=1)").
    • How to run checks locally (composer cs-fix).
  • IDE Integration:
    • Configure PHPStorm/VSCode to use this standard via:

      // .editorconfig (optional, but recommended)
      [*.php]
      php_cs_fixer = vendor/bin/php-cs-fixer
      

• Training:
  • Workshop: Run a 30-minute session on:
    • Why this standard matters (consistency, tooling).
    • How to fix common violations (e.g., array() vs `[]