Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Low architectural impact: This package is a PHP_CodeSniffer standard, meaning it enforces coding conventions rather than altering core Laravel/PHP functionality. It does not introduce new dependencies, modify runtime behavior, or require database changes.
• Complementary to Laravel: Aligns with Laravel’s existing PSR-12/PSR-2 standards but adds Instaclick-specific rules (e.g., blank lines before if statements). Useful for teams enforcing consistent, opinionated coding styles.
• Extensible: Built on top of Symfony2 and Object Calisthenics standards, suggesting modularity for future rule additions.

Integration Feasibility

• Minimal setup: Requires only:
  • PHP_CodeSniffer (squizlabs/php_codesniffer).
  • Package installation (composer require instaclick/coding-standard).
  • Configuration in .phpcs.xml or .phpcs.ruleset.xml.
• No breaking changes: Rules are static analysis (linting), so they won’t affect production behavior.
• CI/CD friendly: Can be integrated into Git hooks, PR checks (GitHub Actions/GitLab CI), or pre-commit tools (Husky, PHP-CS-Fixer).

Technical Risk

Key Questions

1. Alignment with team standards:
   • Does this standard complement or conflict with existing PSR-12/PSR-2 rules?
   • Are Object Calisthenics principles (e.g., small methods, no getters/setters) desirable for the team?
2. Enforcement strategy:
   • Should this be mandatory (blocking CI) or advisory (warnings only)?
   • How will conflicts with PHP-CS-Fixer (auto-fixing) be handled?
3. Tooling integration:
   • Will this replace or augment existing linters (e.g., laravel-pint, psalm)?
   • Should it be opt-in per project or enforced globally?
4. Long-term viability:
   • Is Instaclick a trusted source for PHP standards, or should rules be forked/customized?
   • How will updates to the standard be managed (e.g., major version bumps)?

Integration Approach

Stack Fit

• PHP/Laravel ecosystems:
  • CodeSniffer is a de facto standard for PHP linting (used by Laravel, Symfony, Drupal).
  • Works alongside:
    • PHP-CS-Fixer (auto-fixing).
    • Psalm (static analysis).
    • Pint (Laravel’s opinionated formatter).
• Toolchain compatibility:
  • Integrates with:
    • Git hooks (pre-commit).
    • CI pipelines (GitHub Actions, GitLab CI).
    • IDE plugins (PHPStorm, VSCode via php-cs-fixer).

Migration Path

1. Assessment Phase:
   • Audit existing codebase for conflicts with Instaclick’s rules.
   • Identify high-priority rules (e.g., blank lines before if) vs. optional ones.
2. Pilot Integration:
   • Add to composer.json:

     "require-dev": {
         "instaclick/coding-standard": "^1.0"
     }
     

   • Configure .phpcs.xml:

     <config name="instaclick" extension=".php">
         <rule ref="Instaclick"/>
     </config>
     

   • Run locally:

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

3. CI/CD Integration:
   • Add to .github/workflows/lint.yml:

     - name: Run PHP_CodeSniffer
       run: vendor/bin/phpcs --standard=Instaclick --warning-severity=0 src/
     

4. Gradual Enforcement:
   • Start as warnings, then transition to failures in CI.
   • Use PHP-CS-Fixer to auto-fix compatible rules.

Compatibility

• Laravel-specific considerations:
  • Some Laravel conventions (e.g., use App\Models\...) may conflict with Object Calisthenics (e.g., no long namespaces).
  • Solution: Exclude vendor/Laravel files or override rules.
• Tool conflicts:
  • PHP-CS-Fixer vs. CodeSniffer:
    • Some rules may overlap (e.g., blank lines). Decide which tool owns the rule.
  • Pint vs. CodeSniffer:
    • Pint is Laravel’s formatter; ensure no duplication of efforts.

Sequencing

Operational Impact

Maintenance

• Low ongoing effort:
  • Rules are static; updates only required if Instaclick modifies their standard.
  • Dependency: PHP_CodeSniffer (already maintained by the community).
• Customization needs:
  • May require forking if Instaclick’s rules become too opinionated.
  • Rule overrides in .phpcs.xml may need updates over time.

Support

• Developer ramp-up:
  • Pros: Enforces consistency, reducing "why is this formatted differently?" questions.
  • Cons: May frustrate developers if rules feel arbitrary (e.g., blank lines before if).
• Onboarding:
  • Add to developer docs with examples of compliant code.
  • Provide a cheat sheet for common rule violations.
• Troubleshooting:
  • False positives: Some rules may flag Laravel-specific patterns (e.g., if ($request->has(...))).
  • Solution: Use --ignore or custom rulesets.

Scaling

• Performance:
  • CodeSniffer runs during development/test phases; negligible impact on production.
  • Large codebases: May slow down CI if not cached (use --cache flag).
• Team adoption:
  • Small teams: Easy to enforce uniformly.
  • Large teams: May need phased rollout to avoid resistance.
• Multi-repo environments:
  • Can be shared via Composer or custom ruleset repos.

Failure Modes

Ramp-Up

• Time to implement: 1–3 days (setup + CI integration).
• Training required:
  • 15–30 mins for team alignment on new rules.
  • Focus on high-impact rules (e.g., blank lines, method length).
• Key metrics for success:
  • % of PRs passing CodeSniffer checks.
  • Reduction in formatting-related code review comments.
  • Developer feedback on rule usefulness.