Yii2 Coding Standards Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: This package is a coding standards enforcer (PHP_CodeSniffer ruleset) tailored for Yii2, a legacy PHP framework. While Laravel follows its own conventions (PSR-12 + Laravel-specific rules), this package is not natively Laravel-compatible but could be adapted for cross-framework PHP standard enforcement in a Laravel monorepo or polyglot environment.
• Core Value: Enforces Yii2-specific rules (e.g., naming conventions, array syntax, Yii helper usage) that may conflict with Laravel’s PSR-12/PSR-4 standards. Useful if:
  • Migrating from Yii2 to Laravel and needing gradual standardization.
  • Maintaining a legacy Yii2 codebase alongside Laravel (e.g., in a microservices or hybrid app).
  • Enforcing consistent PHP practices across a team with mixed framework experience.

Integration Feasibility

• Tooling Compatibility:
  • Works with PHP_CodeSniffer (v3+), which Laravel teams already use (e.g., squizlabs/php_codesniffer).
  • Can be integrated into Laravel’s CI/CD (GitHub Actions, GitLab CI) via custom sniffer rules.
  • No direct Laravel service provider (unlike Laravel packages), so integration requires manual setup.
• Rule Conflicts:
  • Yii2 rules (e.g., yiisoft.array-syntax, yiisoft.naming-conventions) may clash with Laravel’s PSR-12. Mitigation: Override or disable conflicting rules via .phpcs.xml configuration.
  • Example conflict: Yii2 prefers Yii::$app->request over Laravel’s $request dependency injection.

Technical Risk

• Low-Medium Risk:
  • False Positives/Negatives: Rules may flag Laravel idioms as violations (e.g., facades, Blade templates).
  • Maintenance Overhead: Requires custom rule overrides to align with Laravel’s ecosystem.
  • Dependency Bloat: Adds Yii2-specific rules to a Laravel project, which may not be needed long-term.
• Mitigations:
  • Use conditional rule application (e.g., apply only to /legacy/ directories).
  • Extend the ruleset (via PHP_CodeSniffer’s extend config) to add Laravel-specific exceptions.

Key Questions

1. Why adopt this?
   • Are you enforcing Yii2-style consistency in a Laravel project, or is this for a legacy migration?
   • Do you need cross-framework PHP standards, or is PSR-12 sufficient?
2. Conflict Resolution:
   • How will you handle rule clashes (e.g., Yii2’s yiisoft.array-syntax vs. Laravel’s array() vs. [])?
3. Tooling Integration:
   • Will this replace or supplement existing tools (e.g., phpstan, psalm, laravel-pint)?
4. Long-Term Viability:
   • Is this a temporary standard (e.g., during migration) or a permanent requirement?

Integration Approach

Stack Fit

• PHP_CodeSniffer Integration:
  • Install via Composer:

    composer require --dev yiisoft/yii2-coding-standards
    

  • Configure in .phpcs.xml:

    <config name="installedPackages" value="yiisoft/yii2-coding-standards"/>
    <rule ref="yiisoft"/>
    

• CI/CD Pipeline:
  • Add to Laravel’s CI (e.g., GitHub Actions):

    - name: Run PHP_CodeSniffer
      run: vendor/bin/phpcs --standard=yiisoft src/ tests/
    

• IDE Support:
  • Integrate with PHPStorm or VSCode via CodeSniffer plugins.

Migration Path

1. Assessment Phase:
   • Audit existing Laravel codebase for Yii2 rule conflicts.
   • Identify critical vs. non-critical rules (e.g., naming conventions may matter less than security rules).
2. Pilot Integration:
   • Apply rules to a subset of files (e.g., /legacy/ or /shared/).
   • Use --ignore to exclude Laravel-specific files initially.
3. Gradual Adoption:
   • Phase 1: Enforce Yii2 rules in CI (fail builds on violations).
   • Phase 2: Override conflicting rules (e.g., disable yiisoft.naming-conventions for Laravel models).
   • Phase 3: Extend ruleset with Laravel-specific exceptions.
4. Fork/Extend:
   • If heavy customization is needed, fork the ruleset and host it privately.

Compatibility

• Laravel-Specific Considerations:
  • Facades: Yii2 rules may flag Route::get() as "non-static" (incorrectly). Add exceptions.
  • Blade Templates: Exclude .blade.php files from PHP_CodeSniffer checks.
  • Dependency Injection: Yii2 rules may penalize Laravel’s $request injection. Document overrides.
• Toolchain Conflicts:
  • Avoid mixing with laravel-pint (formatting) or phpstan (static analysis). Use separate tools for clarity.

Sequencing

1. Pre-Integration:
   • Run phpcs on a sample of Laravel code to identify false positives.
   • Decide on rule whitelisting/blacklisting strategy.
2. Initial Setup:
   • Install package, configure .phpcs.xml, and test locally.
3. CI Integration:
   • Add to pull request checks (start as "warn" mode, then enforce).
4. Developer Onboarding:
   • Document allowed exceptions (e.g., "Laravel facades are exempt from static analysis").
5. Iterative Refinement:
   • Adjust rules based on real-world violations and false positives.

Operational Impact

Maintenance

• Ongoing Effort:
  • Rule Updates: Yii2 rules may evolve separately from Laravel’s needs. Monitor upstream changes.
  • Custom Overrides: Maintain a custom .phpcs.xml with Laravel-specific exceptions (e.g., exclude-patterns).
• Dependency Management:
  • Pin yiisoft/yii2-coding-standards to a specific version to avoid breaking changes.
  • Watch for Yii2 deprecations that could affect rules.

Support

• Developer Experience:
  • Learning Curve: Teams familiar with PSR-12 may need training on Yii2-specific rules.
  • Tooling Familiarity: Ensure devs know how to ignore violations or request rule changes.
• Debugging:
  • False positives may require manual review of rule logic (e.g., why a Laravel helper is flagged).
  • Documentation Gap: Lack of Laravel-specific guidance in Yii2’s ruleset.

Scaling

• Performance:
  • PHP_CodeSniffer can be slow on large codebases. Optimize with:
    • Parallel execution (e.g., parallel flag in phpcs).
    • Excluding non-PHP files (e.g., vendor/, node_modules/).
• Team Adoption:
  • Enforcement Fatigue: Overly strict rules may lead to rule fatigue. Start with a subset of critical rules.
  • Toolchain Bloat: Adding another linter may slow down CI. Benchmark impact.

Failure Modes

• False Enforcement:
  • Build Blockers: Strict rules may halt PRs due to non-critical violations (e.g., naming conventions).
  • Tooling Collisions: Conflicts with phpstan or psalm if rules overlap (e.g., type hints).
• Maintenance Rot:
  • If the ruleset is not actively maintained, custom overrides may become unsustainable.
• Cultural Resistance:
  • Laravel teams may resist Yii2-specific rules, leading to workarounds (e.g., disabling checks).

Ramp-Up

• Onboarding Steps:
  1. Training: Hold a session on Yii2 rules vs. Laravel conventions.
  2. Pilot Group: Assign a small team to test rules in a non-critical branch.
  3. Feedback Loop: Collect violations and adjust rules before full enforcement.
• Documentation:
  • Create a README or wiki page with:
    • List of allowed exceptions (e.g., "Facades are exempt").
    • Steps to ignore violations temporarily.
    • Contact for rule customization requests.
• Phased Rollout:
  • Phase 1: Optional local checks (no CI enforcement).
  • Phase 2: CI warnings (non-blocking).
  • Phase 3: CI failures (enforced).