Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The phpyh/coding-standard package enforces PHP coding standards (likely PSR-12 or custom rules) via PHP_CodeSniffer. It is a static analysis tool, not a runtime dependency, making it ideal for pre-commit hooks, CI/CD pipelines, or developer workflows in Laravel.
• Leverage Points:
  • Quality Gates: Integrate into CI (GitHub Actions, GitLab CI) to block non-compliant code.
  • IDE Integration: Use with PHPStorm/VSCode via PHP_CodeSniffer plugins for real-time feedback.
  • Onboarding: Enforce consistency for new/legacy Laravel teams.
• Misalignment Risks:
  • Not a framework-specific tool (unlike Laravel-specific packages like laravel-shift/blueprint).
  • Overhead if team already uses Laravel-specific tools (e.g., Pest for testing, Laravel Pint for formatting).

Integration Feasibility

• Low-Coupling: Pure PHP_CodeSniffer rules → no Laravel core dependencies.
• Compatibility:
  • Works with PHP 8.1+ (check Laravel’s min PHP version).
  • Rules may conflict with existing tools (e.g., laravel-shift/blueprint or dealerdirect/phpcodesniffer-composer-installer).
• Customization:
  • Extendable via custom rules (PHP_CodeSniffer’s Sniff classes).
  • Can override default rules via phpcs.xml config.

Technical Risk

• Rule Collisions: Existing tools (e.g., rector/rector, phpstan/phpstan) may duplicate or conflict with this package’s rules.
• Performance: Running in CI adds ~1–5s per job (negligible but worth benchmarking).
• Maintenance Burden:
  • Rules may become outdated if not actively maintained (last release: 2025-10-21).
  • Requires explicit configuration to avoid false positives/negatives.

Key Questions

1. Does the team already use PHP_CodeSniffer or similar tools? (Avoid redundancy.)
2. Are the rules PSR-compliant or custom? (Custom rules may need justification.)
3. How will violations be handled? (Block in CI vs. warn developers?)
4. Will this replace or supplement existing tools? (e.g., Laravel Pint for formatting.)
5. What’s the migration path for legacy code? (Gradual enforcement vs. strict gate.)

Integration Approach

Stack Fit

• Best For:
  • Monorepos with mixed PHP/Laravel codebases.
  • Teams adopting PSR-12 or custom standards.
  • Projects using PHP_CodeSniffer (e.g., for legacy codebases).
• Less Ideal For:
  • Teams already using Laravel-specific tools (e.g., laravel-shift/blueprint).
  • Projects where developer experience (DX) trumps strict enforcement.

Migration Path

1. Assessment Phase:
   • Run ./vendor/bin/phpcs --standard=phpyh on a sample of code to identify violations.
   • Compare with existing tools (e.g., phpstan, rector).
2. Pilot:
   • Integrate into local development (via IDE plugins or pre-commit hooks).
   • Use --ignore for known legacy issues.
3. CI Integration:
   • Add to Laravel’s CI pipeline (e.g., GitHub Actions):

     - name: PHP Coding Standards
       run: ./vendor/bin/phpcs --standard=phpyh --error-severity=5 src/
     

4. Gradual Enforcement:
   • Start with --warning-severity → escalate to --error-severity.
   • Exclude third-party/vendor code initially.

Compatibility

• Dependencies:
  • Requires PHP_CodeSniffer (squizlabs/php_codesniffer).
  • Conflict risk with:
    • dealerdirect/phpcodesniffer-composer-installer (if both manage sniffers).
    • laravel-shift/blueprint (overlapping rules).
• Laravel-Specific:
  • No direct Laravel hooks, but can target app/, config/, etc., via --paths.
  • Example config snippet:

    <config name="installed_paths" value="./vendor/phpyh/coding-standard"/>
    <arg name="extensions" value="php,blade"/>
    

Sequencing

1. Pre-Requirements:
   • Install PHP_CodeSniffer globally or via Composer.
   • Align with team on rule priorities (e.g., PSR-12 vs. custom).
2. Parallel Efforts:
   • Run alongside phpstan/rector (but avoid duplicate checks).
3. Post-Integration:
   • Document allowed exceptions in phpcs.xml.
   • Train team on fixing violations (e.g., via --diff flag).

Operational Impact

Maintenance

• Pros:
  • Self-contained: No Laravel core updates required.
  • Configurable: Rules can be tweaked without package updates.
• Cons:
  • Rule Drift: Custom rules may need updates if PHP/Laravel evolves.
  • Dependency Management: PHP_CodeSniffer itself may require updates.
• Mitigations:
  • Pin phpyh/coding-standard and php_codesniffer versions in composer.json.
  • Schedule quarterly rule audits.

Support

• Developer Onboarding:
  • Pro: Clear standards reduce "why is this code formatted like this?" questions.
  • Con: Initial ramp-up for developers unfamiliar with PHP_CodeSniffer.
• Tooling Support:
  • Integrate with Slack/Teams alerts for CI failures.
  • Provide cheat sheets for common violations (e.g., "How to fix PSR12.Classes.ClassDeclaration.MissingNamespace").
• Escalation Path:
  • False positives → adjust phpcs.xml.
  • Rule conflicts → evaluate toolchain consolidation.

Scaling

• Performance:
  • Local: Negligible overhead (runs on save via IDE).
  • CI: ~1–5s per job (scale by parallelizing or caching results).
• Team Growth:
  • Scales well for distributed teams (enforces consistency).
  • May need rule exceptions for legacy codebases.
• Multi-Repo:
  • Reuse config via Composer scripts or shared phpcs.xml.

Failure Modes

Ramp-Up

• For Developers:
  • Training: 30-min session on PHP_CodeSniffer + package rules.
  • Tooling: Pre-configure IDE plugins (e.g., PHPStorm’s PHP_CodeSniffer).
  • Feedback Loop: Collect false positives to refine rules.
• For TPM:
  • Metrics: Track violation trends (e.g., "Did this reduce technical debt?").
  • ROI: Measure code review time saved and consistency improvements.
• Timeline:
  • Week 1: Install + local testing.
  • Week 2: CI integration (warning mode).
  • Week 4: Enforce in CI (error mode).