Php Arguments Detector Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev degraciamathieu/php-arguments-detector
   

   Register the provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       DeGraciaMathieu\ArgumentsDetector\ArgumentsDetectorServiceProvider::class,
   ],
   

2. Basic Usage Run the detector on your project:

   php artisan arguments:detect
   

   This will scan your codebase and report methods exceeding your configured argument limit.

3. First Use Case

   • Define a threshold in .php-arguments-detector.php (auto-generated in project root):

     return [
         'max_arguments' => 4, // Default: 4
         'exclude_paths' => [
             'vendor/*',
             'tests/*',
         ],
     ];
     

   • Run the detector and review violations in the console output or generated report.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add the detector to your CI pipeline (e.g., GitHub Actions) to fail builds on violations:

   - name: Check method arguments
     run: php artisan arguments:detect --fail-on-violations
   

2. Pre-Commit Hooks Use tools like PHP-CS-Fixer or custom scripts to run the detector before commits:

   composer require --dev php-cs-fixer
   composer cs-fix
   php artisan arguments:detect --format=json > arguments_report.json
   

3. IDE Integration

   • Parse the JSON output (--format=json) to highlight violations in your IDE (e.g., PHPStorm via custom inspections).
   • Example JSON output:

     {
         "violations": [
             {
                 "file": "app/Services/UserService.php",
                 "method": "createUser",
                 "line": 42,
                 "arguments": 5,
                 "max_allowed": 4
             }
         ]
     }
     

Common Patterns

• Refactoring Violations Use the output to identify methods needing refactoring (e.g., extract parameters into objects or classes):

  // Before (5 args)
  public function processOrder($userId, $productId, $quantity, $discountCode, $shippingAddress) { ... }
  
  // After (1 arg)
  public function processOrder(OrderRequest $request) { ... }
  

• Configuring Exceptions Exclude specific methods/classes from checks in .php-arguments-detector.php:

  return [
      'excluded_methods' => [
          'App\Services\LegacyService::migrateData', // Legacy code
      ],
  ];
  

• Custom Rules Extend the detector by creating a custom rule (e.g., for constructors):

  // app/Rules/ConstructorArgumentsRule.php
  namespace App\Rules;
  use DeGraciaMathieu\ArgumentsDetector\Rules\AbstractRule;
  
  class ConstructorArgumentsRule extends AbstractRule {
      protected $maxArguments = 3;
  
      public function check($method) {
          return $method->isConstructor() && $method->getParameters()->count() > $this->maxArguments;
      }
  }
  

  Register it in the config:

  'custom_rules' => [
      App\Rules\ConstructorArgumentsRule::class,
  ],
  

Gotchas and Tips

Pitfalls

1. False Positives

   • Static Methods: The detector may flag static methods with many arguments. Exclude them in config:

     'exclude_static_methods' => true,
     

   • Magic Methods: Override __call or __callStatic to avoid noise.

2. Performance

   • Large codebases may slow down the detector. Use --parallel for faster scans (if supported in future versions).
   • Cache results in CI by storing the report and comparing against it:

     php artisan arguments:detect --format=json > report.json
     git add report.json
     

3. Configuration Overrides

   • The .php-arguments-detector.php file is auto-generated but may be overwritten. Commit it to version control to preserve settings.
   • Use environment variables to override settings dynamically:

     'max_arguments' => env('ARGUMENTS_DETECTOR_MAX', 4),
     

Debugging

• Verbose Output Run with --verbose to debug skipped files or methods:

  php artisan arguments:detect --verbose
  

• Dry Run Use --dry-run to see what would be checked without running the full analysis.

Extension Points

1. Custom Formatters Extend the DeGraciaMathieu\ArgumentsDetector\Formatters\FormatterInterface to create custom output formats (e.g., Slack notifications):

   // app/Formatters/SlackFormatter.php
   namespace App\Formatters;
   use DeGraciaMathieu\ArgumentsDetector\Formatters\FormatterInterface;
   
   class SlackFormatter implements FormatterInterface {
       public function format(array $violations) {
           $message = "🚨 Arguments Detector Violations:\n";
           foreach ($violations as $violation) {
               $message .= "- {$violation['file']}::{$violation['method']} (Line {$violation['line']})\n";
           }
           return $message;
       }
   }
   

   Register it in config:

   'formatter' => App\Formatters\SlackFormatter::class,
   

2. Hooks for Refactoring Integrate with tools like Rector to auto-fix violations:

   composer require rector/rector
   vendor/bin/rector process src --dry-run
   

3. Git Blame Integration Combine with git blame to identify who introduced violations:

   php artisan arguments:detect --format=json | jq -r '.violations[] | "git blame -L /\(.line),\(.line) \(.file)"' | xargs -I{} sh -c '{}'