Object Calisthenics Sniffs Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer in your Laravel project:

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

   Ensure phpcs (PHP_CodeSniffer) is installed globally or via Composer:

   composer global require squizlabs/php_codesniffer
   

2. First Use Case Run a basic sniff check on your Laravel app’s app/ directory:

   phpcs --standard=./vendor/instaclick/object-calisthenics-sniffs app/
   

   This enforces Object Calisthenics principles (e.g., no getters/setters, no literals, etc.) by default.

3. Where to Look First

   • Ruleset File: Check ./vendor/instaclick/object-calisthenics-sniffs/ruleset.xml for customizable rules.
   • Documentation: Review Object Calisthenics principles to understand constraints.
   • Laravel-Specific Adjustments: Override defaults in phpcs.xml (e.g., exclude app/Providers/ if needed).

Implementation Patterns

Usage Patterns

1. Integrate into CI/CD Add a phpcs step to your GitHub Actions/GitLab CI:

   - name: Run Object Calisthenics Sniffs
     run: phpcs --standard=./vendor/instaclick/object-calisthenics-sniffs --report=json app/ > phpcs-results.json
   

   Fail the build if violations exceed thresholds (e.g., phpcs --warning-severity=5).

2. Laravel-Specific Workflows

   • Service Classes: Enforce "no getters/setters" for DTOs or domain objects (e.g., app/Domain/Entities/).
   • Repositories/Patterns: Use constructor injection instead of setters for dependencies.
   • Config/Helpers: Replace static literals (e.g., return 42;) with injected constants or config files.

3. Custom Rulesets Extend the default ruleset in phpcs.xml:

   <config name="instaclick_object_calisthenics" value="./vendor/instaclick/object-calisthenics-sniffs/ruleset.xml"/>
   <arg name="extensions" value="php" />
   <arg name="tab-width" value="4" />
   <arg name="encoding" value="utf-8" />
   

4. Pair with Other Tools

   • PHPStan: Combine with phpstan/extension-installer to catch type-related violations.
   • PSR-12: Use alongside squizlabs/php_codesniffer for broader standards.

Integration Tips

• Exclude Directories: Temporarily exclude legacy code:

  phpcs --ignore=app/OldCode app/
  

• Partial Adoption: Start with critical paths (e.g., app/Http/Controllers/) before full enforcement.
• IDE Integration: Configure PHPStorm/VSCode to run phpcs on save using the phpcs.xml ruleset.

Gotchas and Tips

Pitfalls

1. Overly Strict Defaults

   • Issue: Rules like "no getters/setters" may conflict with Laravel’s Eloquent models or Facades.
   • Fix: Override specific sniffs in phpcs.xml:

     <rule ref="ObjectCalisthenics.Sniffs.NamingConventions.NoGetterSetterMethodsSniff" severity="0"/>
     

2. False Positives in Legacy Code

   • Issue: Existing setters/getters trigger violations even if refactoring isn’t feasible.
   • Fix: Use --ignore or annotate code with @phpcs:disable:

     // @phpcs:disable ObjectCalisthenics.Sniffs.NamingConventions.NoGetterSetterMethodsSniff
     public function getName() { ... }
     

3. Performance Overhead

   • Issue: Running phpcs on large codebases (e.g., 10K+ files) can be slow.
   • Fix: Parallelize checks or limit to changed files:

     phpcs --parallel=4 app/
     

4. Laravel-Specific Exceptions

   • Issue: Facades (e.g., Route::get()) or magic methods (e.g., __get()) may violate rules.
   • Fix: Exclude app/Providers/ or use @phpcs:ignore for Facades.

Debugging

• Verbose Output: Use --verbose to identify which files/rules are failing:

  phpcs --standard=./vendor/instaclick/object-calisthenics-sniffs --verbose app/
  

• Rule-Specific Help: Check individual sniff docs (e.g., NoGetterSetterMethodsSniff) for exceptions.

Extension Points

1. Custom Sniffs Extend the package by creating your own sniffs in app/CodeSniffer/ and reference them in phpcs.xml:

   <rule ref="app/CodeSniffer/Custom/NoMagicMethodsSniff"/>
   

2. Dynamic Rules Use PHP_CodeSniffer’s processFile to skip files conditionally (e.g., based on namespace):

   // In a custom sniff
   if (strpos($file, 'app/Tests/') !== false) {
       return;
   }
   

3. Severity Tuning Adjust severity per rule (e.g., warning instead of error) for gradual adoption:

   <rule ref="ObjectCalisthenics.Sniffs.NamingConventions.NoGetterSetterMethodsSniff">
       <severity>3</severity> <!-- Warning -->
   </rule>
   

4. Laravel Artisan Integration Create a custom Artisan command to run phpcs with Laravel’s bootstrapped environment:

   // app/Console/Commands/RunCalisthenics.php
   public function handle() {
       $this->call('phpcs', [
           '--standard' => base_path('vendor/instaclick/object-calisthenics-sniffs/ruleset.xml'),
           'app/'
       ]);
   }