Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Alignment: The package is not Laravel-specific but enforces modern PHP best practices (e.g., @template* annotations, trait ordering) that align with Laravel’s PHP 8.5+ ecosystem. However, it lacks native Laravel-specific rules (e.g., Blade syntax, Facade patterns, Eloquent conventions), making it incompatible with Laravel’s idiomatic patterns without custom overrides.
• Monolithic vs. Modular: Designed as a pre-configured, rigid ruleset for ShipMonk’s internal ecosystem, not as a modular or extensible tool. This limits its adaptability for projects requiring partial adoption or custom rule adjustments.
• PHP Version Dependency: Explicitly supports PHP 8.5 (via slevomat/coding-standard@^8.25.0) and drops backward compatibility (e.g., removed RequireSelfReference). Projects using older PHP versions or tools (e.g., PHPStan <8.0) may encounter integration issues or rule conflicts.
• Toolchain Conflicts:
  • Auto-fix Risks: phpcbf could break Laravel-specific patterns (e.g., reordering use statements for Facades, altering exception handling in middleware).
  • Overlap with Other Tools: No built-in conflict resolution with tools like PHPStan, Rector, or Laravel Pint. For example, PHPCS’s ReturnTypeDeclaration may conflict with PHPStan’s expectations or Rector’s refactoring rules.
  • CI/CD Integration: While designed for automated enforcement, the package’s strictness could block merges if not paired with pre-commit hooks or gradual adoption strategies.

Integration Feasibility

• Composer Dependency: Simple to install (composer require --dev shipmonk/coding-standard) but no Laravel-specific installation hooks (e.g., service provider, package discovery).
• Configuration Overhead: Requires manual phpcs.xml.dist setup, which is straightforward but not self-documenting for new teams. The provided template assumes ShipMonk’s directory structure (src/, tests/), which may not match all Laravel projects (e.g., app/, database/).
• Rule Customization: Not designed for modification—ShipMonk’s note in the README explicitly discourages external customization. Overrides would require forking the package or excluding rules, increasing maintenance burden.
• Laravel-Specific Workarounds: To mitigate conflicts (e.g., Facade ordering, exception handling), teams would need to:
  • Exclude directories (e.g., app/Exceptions, app/Http/Middleware) from PHPCS.
  • Disable conflicting sniffs (e.g., CatchExceptionsOrder) in phpcs.xml.
  • Use phpcbf --dry-run to test auto-fixes before applying them.

Technical Risk

• False Positives/Negatives: Rules like ThrowsAnnotationsOrder or TraitUseOrder may flag Laravel-specific patterns as violations (e.g., middleware exception handling, Facade trait usage).
• Auto-fix (phpcbf) Danger: Could alter Laravel’s implicit behavior (e.g., reordering use statements for Facades, modifying exception hierarchies in middleware).
• Dependency Bloat: Pulls in slevomat/coding-standard (a large dependency) even if only a subset of rules is needed. For lightweight projects, this may be overkill.
• Maintenance Risk: Since the package is ShipMonk-specific, future updates may break compatibility with non-ShipMonk Laravel projects (e.g., if ShipMonk introduces Laravel-specific rules).
• Performance: PHPCS caching (var/phpcs.cache) helps, but large Laravel monorepos (e.g., with many Facades or middleware) could experience slow analysis due to the package’s strict rule set.

Key Questions for Adoption

1. Laravel-Specific Conflicts:
   • Which Laravel patterns (e.g., Facades, middleware, Eloquent) might conflict with this package’s rules?
   • How will we exclude or override problematic sniffs (e.g., CatchExceptionsOrder) without forking?
2. Auto-fix Safety:
   • Has phpcbf been tested on a Laravel codebase to ensure it doesn’t break critical functionality?
   • Should we disable auto-fix for Laravel projects and rely on manual review?
3. Toolchain Integration:
   • How will this interact with PHPStan, Rector, or Laravel Pint? Are there known conflicts with these tools?
   • Should we run PHPCS in CI only (not pre-commit) to avoid blocking development?
4. Customization Needs:
   • Are we willing to fork the package if we need Laravel-specific rules (e.g., Blade linting)?
   • How will we document exceptions for ShipMonk’s internal rules (e.g., @template* annotations)?
5. Backward Compatibility:
   • If our project uses PHP <8.5, how will we handle dropped rules (e.g., RequireSelfReference)?
   • Will we need to maintain a parallel PHPCS config for older PHP versions?
6. Performance Impact:
   • How will PHPCS caching (var/phpcs.cache) perform on a large Laravel codebase (e.g., 10K+ lines)?
   • Should we exclude certain directories (e.g., vendor/, node_modules/) to speed up analysis?

Integration Approach

Stack Fit

• Laravel Compatibility: The package is PHP-agnostic and not Laravel-aware, so it does not natively support:
  • Blade template syntax.
  • Laravel Facades (e.g., use Illuminate\Support\Facades\Log;).
  • Eloquent/Query Builder conventions.
  • Artisan command or middleware patterns.
• Toolchain Synergy:
  • PHPStan/Rector: No built-in rule alignment—may require custom PHPCS sniffs to avoid conflicts (e.g., ReturnTypeDeclaration vs. PHPStan’s expectations).
  • Laravel Pint: If using Pint for Laravel-specific formatting, PHPCS could duplicate effort or override Pint’s rules.
  • CI/CD: Works with GitHub Actions, GitLab CI, etc., but strict rules may increase flakiness (e.g., false positives in Laravel-specific code).
• PHP Version Lock-in: Explicitly requires PHP 8.5—projects using older versions will need alternative solutions (e.g., slevomat/coding-standard@^7.0).

Migration Path

1. Assessment Phase:
   • Run vendor/bin/phpcs --sniffs=ShipMonkCodingStandard --report=full on a sample Laravel project to identify conflicts (e.g., Facade ordering, exception handling).
   • Test phpcbf --dry-run to simulate auto-fixes and check for breaking changes.
2. Pilot Adoption:
   • Start with non-critical ShipMonk packages (e.g., internal libraries) to validate the ruleset.
   • Gradually introduce to Laravel projects with excluded directories (e.g., app/Http/Middleware, app/Exceptions).
3. Configuration Hardening:
   • Customize phpcs.xml.dist to:
     • Disable conflicting sniffs (e.g., CatchExceptionsOrder).
     • Exclude Laravel-specific paths (e.g., <exclude-pattern>app/Http/Middleware</exclude-pattern>).
     • Add custom rules (if needed) via <rule> overrides.
4. Toolchain Alignment:
   • If using PHPStan/Rector, run PHPCS after static analysis to avoid redundant checks.
   • Pair with Laravel Pint for Laravel-specific formatting (e.g., Blade, Facade imports).
5. CI/CD Integration:
   • Add PHPCS to pre-merge checks (e.g., GitHub Actions):

     - name: PHPCS
       run: vendor/bin/phpcs --standard=ShipMonkCodingStandard --warning-severity=3
     

   • Consider gradual enforcement (e.g., --ignore=* initially, then tighten rules).

Compatibility