Object Calisthenics Sniffs Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package enforces Object Calisthenics principles (e.g., single responsibility, no getters/setters, no inheritance, etc.) via PHP_CodeSniffer, making it a static analysis tool rather than a runtime dependency. This aligns well with quality-focused Laravel projects where maintainability and clean architecture are priorities.
• Non-Invasive: Since it’s a sniffer, it doesn’t modify runtime behavior but instead flags violations in code reviews/CI, reducing technical debt without disrupting existing workflows.
• Complementary to Laravel: Laravel’s dependency injection (DI), service containers, and eloquent models could benefit from stricter object design, but some patterns (e.g., getters/setters in models) may conflict with Object Calisthenics. A gradual adoption approach is recommended.

Integration Feasibility

• Low Coupling: The package integrates via PHP_CodeSniffer, which Laravel projects may already use (e.g., for PSR-12, security checks). Adding this as an additional rule set is straightforward.
• Toolchain Compatibility:
  • Works with PHPStan, Psalm, or PHPUnit if configured in CI/CD.
  • Can be embedded in IDEs (PhpStorm, VSCode) via CodeSniffer plugins.
• Customization: Rules can be toggled or extended via phpcs.xml configuration, allowing team-specific adjustments.

Technical Risk

• False Positives/Negatives:
  • Some Laravel conventions (e.g., getX() in controllers) may trigger false positives.
  • Risk Mitigation: Start with a subset of rules (e.g., "No Getters/Setters") and refine based on feedback.
• Performance Overhead:
  • Running sniffs in CI may slow down pipelines if not cached (e.g., using phpcs --cache).
  • Mitigation: Run only on changed files or in parallel.
• Developer Resistance:
  • Enforcing strict OOP rules may require refactoring (e.g., replacing getters with methods).
  • Mitigation: Frame it as a long-term quality investment and provide refactoring guidance.

Key Questions

1. Which Object Calisthenics rules are most critical for our team? (Prioritize based on pain points.)
2. How will we handle conflicts with Laravel’s conventions (e.g., Eloquent getters)?
3. What’s the CI/CD integration strategy? (Dedicated job? Pre-commit hook?)
4. How will we measure success? (Reduction in technical debt? Faster onboarding?)
5. Do we need custom rules to align with our architecture (e.g., allowing certain getters)?

Integration Approach

Stack Fit

• PHP_CodeSniffer Integration:
  • Install via Composer:

    composer require --dev instaclick/object-calisthenics-sniffs
    

  • Configure in phpcs.xml:

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

• IDE Support:
  • PhpStorm: Enable via Settings > PHP > Quality Tools > PHP_CodeSniffer.
  • VSCode: Use the PHP_CodeSniffer extension with the same config.
• CI/CD:
  • GitHub Actions/GitLab CI: Run as a step:

    - name: Run Object Calisthenics Sniffs
      run: vendor/bin/phpcs --standard=instaclick.ObjectCalisthenics src/
    

Migration Path

1. Phase 1: Audit & Baseline
   • Run sniffs on the entire codebase to identify violations.
   • Document high-impact findings (e.g., classes with >1 responsibility).
2. Phase 2: Pilot with a Team
   • Apply to one module (e.g., a service layer) and gather feedback.
   • Adjust rules or exceptions as needed.
3. Phase 3: Gradual Enforcement
   • Add to pre-commit hooks (e.g., via husky or pre-commit).
   • Enforce in CI with a warning threshold, then blocking.
4. Phase 4: Full Adoption
   • Integrate into onboarding docs and code reviews.
   • Refine rules based on team maturity.

Compatibility

• Laravel-Specific Considerations:
  • Eloquent Models: May need to replace getters with query methods or traits.
  • Controllers: Avoid getX() methods; use resource classes instead.
  • Service Providers: Ensure single responsibility (e.g., split monolithic providers).
• Tooling Conflicts:
  • PHPStan/Psalm: May flag similar issues; coordinate rule sets to avoid redundancy.
  • Laravel Pint: Ensure formatting doesn’t break sniffing (e.g., method ordering).

Sequencing

Operational Impact

Maintenance

• Rule Updates:
  • Monitor the package for updates (e.g., new Object Calisthenics rules).
  • Customize or fork if upstream rules don’t fit (e.g., Laravel-specific exceptions).
• Configuration Drift:
  • Maintain a central phpcs.xml to avoid team-specific overrides.
  • Deprecate old rules gradually (e.g., via deprecated attribute in config).

Support

• Onboarding:
  • Provide a cheat sheet for common violations (e.g., "How to replace a getter").
  • Pair programming for junior devs during refactoring.
• Escalation Path:
  • False positives: Log and triage in a dedicated issue tracker (e.g., GitHub project).
  • Rule conflicts: Document exceptions in phpcs.xml with comments.

Scaling

• Performance:
  • Cache results in CI (e.g., phpcs --cache).
  • Parallelize sniffing across files/modules.
• Team Adoption:
  • Gamify compliance (e.g., leaderboards for "cleanest PRs").
  • Celebrate milestones (e.g., "Module X is now 90% compliant!").
• Legacy Code:
  • Use gradual enforcement (e.g., allow exceptions for legacy classes with // @todo comments).

Failure Modes

Ramp-Up

• Time to Value:
  • Week 1: Install + baseline audit (~2 days).
  • Week 2-4: Pilot + first CI integration (~2 weeks).
  • Month 3+: Full enforcement (~ongoing).
• Key Metrics:
  • Compliance Rate: % of files passing sniffs.
  • Refactoring Velocity: Lines changed per sprint.
  • Developer Satisfaction: Survey feedback on usability.
• Training:
  • Workshop: 1-hour session on Object Calisthenics principles.
  • Docs: Runbook for common violations and fixes.
  • Examples: Show "before/after" refactors for Laravel code.