Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• PHPCS Integration: The package is a PHP_CodeSniffer (PHPCS) custom coding standard, designed to enforce consistent coding practices across Laravel/PHP projects. It aligns well with Laravel’s ecosystem, where PHPCS is commonly used (e.g., via php-cs-fixer or standalone PHPCS).
• Rule Customization: Forked from doctrine/coding-standard with Tideways-specific tweaks, suggesting it enforces strict but pragmatic rules (e.g., property hooks syntax support, PHP 8+ compatibility). This could complement Laravel’s PSR-12 baseline or replace it entirely if stricter rules are desired.
• Laravel-Specific Gaps: No explicit Laravel ruleets (e.g., Blade template checks, Eloquent naming conventions). A TPM must assess whether the standard’s rules conflict with Laravel’s idioms (e.g., __construct vs. constructor in PHP 8).

Integration Feasibility

• Low Friction: PHPCS is a standard tool in PHP/Laravel workflows (e.g., vendor/bin/phpcs). Integration requires:
  • Adding the package to composer.json (require-dev).
  • Configuring PHPCS to use the Gyro standard (via ruleset.xml or CLI flags).
• Toolchain Compatibility:
  • Works with PHP 8.1+ (per CI changes in v1.2).
  • Compatible with Laravel Mix/Webpack (if enforcing JS/TS rules separately).
  • May need pre-commit hooks (e.g., Husky + phpcs) or CI gates (GitHub Actions/GitLab CI).

Technical Risk

• Rule Overlap/Conflict:
  • Risk of false positives if Laravel-specific patterns (e.g., Route::get() callbacks) violate Gyro’s rules.
  • Example: Gyro may enforce public visibility for properties, conflicting with Laravel’s protected/private conventions for model attributes.
• Maintenance Burden:
  • No active community (0 stars, 0 dependents). Updates may lag behind Laravel/PHPCS changes.
  • Forked from Doctrine: Future rule updates from upstream may require manual syncing.
• Performance Impact:
  • PHPCS runs add CI/CD overhead (especially for large codebases). Mitigate with caching (e.g., phpcs --cache-file).

Key Questions

1. Rule Alignment:
   • Does Gyro’s standard replace or supplement existing Laravel PSR-12 rules?
   • Are there Laravel-specific exceptions needed (e.g., for Blade templates, Facade classes)?
2. Adoption Strategy:
   • Phased rollout: Start with a subset of rules (e.g., only Basic or PSR12 subsets)?
   • Opt-in vs. Mandatory: Enforce via CI (blocking) or pre-commit (warning-only)?
3. Tooling Integration:
   • How to integrate with Laravel Forge/Envoyer (if used) for deployment-time checks?
   • Compatibility with PHPStan or Psalm for static analysis?
4. Long-Term Viability:
   • Is there a maintainer commitment to sync with Laravel/PHPCS updates?
   • Should this be a temporary standard until a more Laravel-native solution emerges?

Integration Approach

Stack Fit

• Primary Use Case: Code Quality Gates (CI/CD) and Developer Workflow (pre-commit/IDE).
• Laravel Ecosystem Fit:
  • PHPCS: Native support via phpcs CLI or Laravel packages like laravel-phpcs.
  • IDE Integration: VS Code/PHPStorm plugins for real-time feedback.
  • CI/CD: Plugins for GitHub Actions (phpcs action), GitLab CI, or custom scripts.
• Alternatives Considered:
  • PHP-CS-Fixer: More opinionated on auto-fixing; Gyro is PHPCS-only (no fixes).
  • Custom Ruleset: If Gyro’s rules are too restrictive, a hybrid ruleset (mixing Gyro + PSR-12) may be better.

Migration Path

1. Assessment Phase:
   • Run PHPCS with Gyro’s standard on a sample of critical files to identify conflicts.
   • Compare output with existing PSR-12 checks (e.g., phpcs --standard=PSR12).
2. Pilot Integration:
   • Add to composer.json:

     "require-dev": {
         "gyro/coding-standard": "^1.2"
     }
     

   • Configure PHPCS in phpcs.xml:

     <config name="standard" value="Gyro"/>
     

   • Test via CLI:

     vendor/bin/phpcs --standard=Gyro src/
     

3. Gradual Enforcement:
   • Phase 1: Add to CI as a warning-only check.
   • Phase 2: Enforce in pre-commit hooks (e.g., Husky).
   • Phase 3: Block PR merges if checks fail (CI gate).

Compatibility

• PHP Version: Confirmed PHP 8.1+ support (PHP 7.4 dropped in v1.2).
• Laravel Version: No explicit Laravel versioning, but rules should work with Laravel 9+ (PHP 8.1+).
• Dependency Conflicts: Low risk (PHPCS is a dev dependency; Gyro adds no runtime code).

Sequencing

Operational Impact

Maintenance

• Rule Updates:
  • Proactive: Monitor Gyro’s GitHub for updates; test before adopting.
  • Reactive: If Gyro lags (e.g., no PHP 8.2 support), consider forking or switching to php-cs-fixer.
• Custom Rules:
  • Extend via PHPCS’s custom_rules.xml if Gyro lacks Laravel-specific rules.
  • Example: Add a rule to allow protected $fillable in models.

Support

• Developer Onboarding:
  • Training: Document common rule violations (e.g., "Gyro requires public properties").
  • IDE Setup: Provide .phpcs.xml templates for VS Code/PHPStorm.
• Troubleshooting:
  • False Positives: Maintain a list of exceptions (e.g., Blade templates).
  • Performance: Cache PHPCS results in CI (e.g., GitHub Actions cache).

Scaling

• Large Codebases:
  • Parallelization: Use phpcs --parallel for faster CI runs.
  • Incremental Checks: Run PHPCS only on changed files (e.g., --diff flag).
• Distributed Teams:
  • Consistency: Enforce via CI to avoid "works on my machine" issues.
  • Tooling: Standardize IDE setups (e.g., PHPStorm PHPCS plugin).

Failure Modes

Ramp-Up

• Time Estimate:
  • Assessment: 2–4 hours (running PHPCS on sample code).
  • Integration: 1–2 days (CI + pre-commit setup).
  • Stabilization: 1–2 weeks (resolving edge cases).
• Key Metrics:
  • Adoption Rate: % of PRs passing PHPCS checks.
  • False Positive Rate: Track exceptions documented.
  • CI Duration: Measure impact on build times.
• Success Criteria:

  • 90% of PRs pass PHPCS checks within 3 months.

  • No critical rule conflicts