Phpspec Phpcq Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your project via Composer:

   composer require --dev netzmacht/phpspec-phpcq-plugin
   

2. Configuration Ensure php-cq (PHP Code Quality) is installed and configured in your project. The plugin integrates with php-cq to enforce quality rules during PHPSpec tests.

3. First Use Case Run PHPSpec with the plugin to enforce code quality checks during test execution:

   vendor/bin/phpspec run --format=php-cq
   

   This will execute your specs while validating code quality against php-cq rules.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Integrate the plugin into your CI pipeline to fail builds if code quality rules are violated during spec execution:

   # Example GitHub Actions step
   - name: Run PHPSpec with PHP-CQ
     run: vendor/bin/phpspec run --format=php-cq
   

2. Pre-Commit Hooks Use the plugin in pre-commit hooks (e.g., via husky or pre-commit) to catch quality issues early:

   vendor/bin/phpspec run --format=php-cq --stop-on-failure
   

3. Custom Formatting Extend the plugin’s output format to include custom php-cq rules or annotations:

   // In your PHPSpec config (phpspec.yml)
   extensions:
       PhpSpec\Extension\PhpCqPlugin:
           rules: ['CustomRule1', 'CustomRule2']
   

Testing Patterns

• Spec-Driven Quality Write specs that implicitly enforce quality rules. For example, if a spec requires a method to return a DateTime, ensure php-cq rules validate the return type.

  describe('MyClass', function() {
      it('should return a DateTime', function() {
          $result = $this->object->getDate();
          expect($result)->toBeInstanceOf(DateTime::class);
          // php-cq will validate this during execution
      });
  });
  

• Rule Validation in Context Use the plugin to validate specific parts of your codebase during targeted spec runs:

  vendor/bin/phpspec run --filter="MyClass" --format=php-cq
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts php-cq rules may conflict with existing PHPSpec expectations. Ensure rules are mutually compatible or adjust expectations to align with php-cq constraints.

   • Debug Tip: Run php-cq standalone to isolate rule violations:

     vendor/bin/php-cq check
     

2. Performance Overhead The plugin adds overhead to spec execution. Use it selectively in CI or pre-commit hooks rather than local development.

   • Tip: Cache php-cq results if your project supports it.

3. Configuration Mismatch Ensure php-cq is configured in php-cq.yml or php-cq.php before running the plugin. Misconfigurations may lead to silent failures.

   • Tip: Validate php-cq config separately:

     vendor/bin/php-cq validate
     

Debugging

• Verbose Output Enable verbose logging for the plugin to diagnose issues:

  vendor/bin/phpspec run --format=php-cq --verbose
  

• Isolate Rules Test individual php-cq rules by disabling others in the config:

  # php-cq.yml
  rules:
      enabled: ['TypeHinting', 'Naming']
      disabled: ['Complexity']
  

Extension Points

1. Custom Rules Extend php-cq with custom rules and integrate them into the plugin via the rules config:

   // phpspec.yml
   extensions:
       PhpSpec\Extension\PhpCqPlugin:
           rules: ['vendor/package/CustomRule']
   

2. Post-Processing Hook into the plugin’s lifecycle to post-process php-cq results (e.g., format output for Slack notifications):

   // Example using events (if supported)
   PhpSpec\EventDispatcher\Events::specStarted->addListener(function() {
       // Custom logic here
   });
   

3. Integration with Other Tools Combine with tools like PHPStan or Psalm for layered quality checks. Use the plugin to enforce php-cq rules while other tools handle static analysis.