Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Built on EasyCodingStandard (ECS) and PHPStan, two industry-standard tools for enforcing PHP coding standards and static analysis.
  • Aligns with BitBag’s "Coding Bible" (linked in the README), which provides a structured, opinionated standard for maintainable PHP/Laravel/Sylius code.
  • Supports Laravel/Sylius ecosystems (evident from Sylius-specific fixes in changelogs, e.g., src/EntityListener handling).
  • Modular: Can be extended via custom ECS fixers or PHPStan rules, making it adaptable to team-specific needs.
  • Lightweight: No runtime overhead; runs as a dev dependency for pre-commit or CI checks.

• Cons:

  • Opinionated: Enforces BitBag’s standards, which may conflict with existing team conventions (e.g., PSR-12 vs. BitBag’s rules).
  • Tight coupling to ECS/PHPStan: Requires these tools to be already in the stack (or willingness to adopt them).
  • Sylius-specific quirks: Some fixes (e.g., final keyword handling in EntityListener) may not apply to vanilla Laravel projects.

Integration Feasibility

• Low-risk for Laravel/Sylius:
  • ECS: Plug-and-play via composer require and config file import. No Laravel-specific dependencies.
  • PHPStan: Similarly, integrates via NEON config inclusion. Works with Laravel’s dependency injection if configured.
  • CI/CD: Easy to integrate into GitHub Actions/GitLab CI for pre-push or PR checks.
• Potential Conflicts:
  • If the project already uses custom ECS/PHPStan configs, merging BitBag’s rules may require manual resolution.
  • PHP version: Requires PHP 8.1+ (per ECS/PHPStan compatibility). Check project’s PHP version first.

Technical Risk

• Minimal:
  • Installation: Zero runtime risk; only affects static analysis.
  • Backward Compatibility: BitBag actively maintains the package (releases every 1–2 months). Changelogs show focus on dependency updates (e.g., PHPStan 2.x, ECS 8.x).
  • Performance: ECS/PHPStan runs during development or CI; no impact on production.
• Mitigations:
  • Dry run: Use ecs check --dry-run to preview violations before enforcing.
  • Customization: Override specific rules in ecs.php/phpstan.neon if needed.
  • Gradual adoption: Start with tests/ or src/ subsets before full project enforcement.

Key Questions for TPM

1. Alignment with Team Standards:
   • Does the team already use ECS/PHPStan? If so, how do BitBag’s rules compare to existing configs?
   • Are there exceptions (e.g., legacy code, vendor libraries) that should be excluded?
2. Tooling Maturity:
   • Is the team comfortable with static analysis tools? Will this require training?
   • How will violations be handled (e.g., auto-fix vs. manual review)?
3. CI/CD Integration:
   • Should this block merges (fail-fast) or run as a warning?
   • Will it integrate with existing linters (e.g., PSalm, Pest)?
4. Long-Term Maintenance:
   • Who will update the coding standard as BitBag releases new versions?
   • How will custom rules be managed if the team extends the standard?
5. Performance Impact:
   • For large codebases, will ECS/PHPStan runs become a bottleneck in CI?
   • Should parallelization (e.g., ecs --parallel) be enabled?

Integration Approach

Stack Fit

• Primary Fit:
  • Laravel/Sylius: Optimized for these frameworks (Sylius-specific fixes in changelogs).
  • PHP 8.1+: Requires modern PHP; aligns with Laravel 9+/10+.
  • Composer-based: Works seamlessly with Laravel’s dependency management.
• Secondary Fit:
  • Generic PHP: Can be used in any PHP project, but Sylius/Laravel-specific rules may be irrelevant.
  • Non-Laravel Frameworks: Symfony, Nette, etc., but may need rule adjustments.

Migration Path

1. Assessment Phase:
   • Audit existing codebase for violations using ecs check --dry-run.
   • Compare BitBag’s rules with current standards (e.g., PSR-12, custom team rules).
2. Pilot Phase:
   • Apply to a subset (e.g., tests/ or a single module) to test integration.
   • Configure CI to run on PRs for the pilot scope.
3. Full Rollout:
   • Update ecs.php/phpstan.neon to include all relevant paths (src/, config/, etc.).
   • Train developers on common violations and how to fix them.
4. Customization:
   • Extend ecs.php with project-specific fixers (e.g., services->set(MyCustomFixer::class)).
   • Override PHPStan levels per directory (e.g., stricter for src/, lenient for tests/).

Compatibility

• Dependencies:
  • ECS: Compatible with v8.3+ (per changelog). Laravel’s default ECS version should work.
  • PHPStan: Supports v1.x and v2.x. Laravel projects typically use PHPStan 1.x; upgrade may be needed.
  • PHPUnit: Sylius 1.12+ requires PHPUnit 9.5+ (per troubleshooting section).
• Conflict Resolution:
  • Rule Overrides: Use ECS’s skip or exclude to bypass specific rules.
  • PHPStan Levels: Adjust level: max to level: 8 if the project isn’t ready for strict analysis.
  • IDE Support: Ensure IDEs (PHPStorm, VSCode) are configured to use the same ECS/PHPStan versions.

Sequencing

1. Pre-requisites:
   • Upgrade PHP to 8.1+ (if not already).
   • Update ECS (symplify/ecs) and PHPStan to compatible versions.
   • Ensure Composer is up-to-date (composer self-update).
2. Installation:

   composer require --dev bitbag/coding-standard bitbag/bitbag-bible  # Optional: for reference
   

3. Configuration:
   • Create ecs.php with BitBag’s import.
   • Merge phpstan.neon includes (handle conflicts manually).
4. Testing:
   • Run ./vendor/bin/ecs check src --dry-run.
   • Fix critical violations (e.g., type safety, PSR-12) before enforcing.
5. CI/CD Setup:
   • Add to .github/workflows/lint.yml:

     - name: Run ECS
       run: ./vendor/bin/ecs check src --fix
     - name: Run PHPStan
       run: ./vendor/bin/phpstan analyse src --level=8
     

Operational Impact

Maintenance

• Proactive:
  • Dependency Updates: BitBag releases monthly; pin versions in composer.json to avoid surprises:

    "require-dev": {
        "bitbag/coding-standard": "^3.0",
        "symplify/easy-coding-standard": "^8.3",
        "phpstan/phpstan": "^1.10"
    }
    

  • Rule Updates: Review changelogs for breaking changes (e.g., PHPStan 2.x migration).
• Reactive:
  • Violation Triage: Designate a team member to review new rule additions (e.g., BitBag’s OS header).
  • Custom Rule Maintenance: Document any project-specific extensions to ecs.php.

Support

• Developer Onboarding:
  • Add a coding standards doc to the project wiki with:
    • Common violation examples (e.g., missing @param tags).
    • How to run checks locally (./vendor/bin/ecs check src).
    • Exceptions (e.g., "Vendor code is excluded").
  • IDE Plugins: Recommend ECS/PHPStan IDE integrations (e.g., PHPStorm plugins).
• Troubleshooting:
  • Debugging: Use ecs check --debug for unclear violations.
  • PHPStan Errors: Check phpstan.neon for misconfigured paths/levels.
  • BitBag Support: Offer limited support via GitHub issues or their contact form.

Scaling

• Performance:
  • Large Codebases: Use ECS’s --parallel flag or split paths (e.g., src/, tests/).
  • CI Timeouts: Cache ECS/PHPStan dependencies in CI (e.g., GitHub Actions `actions