1.7.0

Release Notes - Version 1.7.0

🎉 New Features

✨ Renamed DependencyConstraintsRule to ForbiddenDependenciesRule

Breaking Change (with full Backward Compatibility!)

• New Class: Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule
• Deprecated Class: Phauthentic\PHPStanRules\Architecture\DependencyConstraintsRule
• Purpose: The new name better reflects the rule's purpose - forbidding specific dependencies between namespaces
• Migration: The old DependencyConstraintsRule class is kept for backward compatibility but will be removed in a future major version. Please update your configuration to use ForbiddenDependenciesRule instead.

✨ New allowedDependencies Feature for ForbiddenDependenciesRule

Enhancement: Whitelist Override for Forbidden Dependencies

• Class: Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule
• Purpose: Allows creating a "forbid everything except X" pattern without complex regex
• Key Features:
  • New allowedDependencies parameter that overrides forbidden dependencies
  • Dependencies matching both a forbidden pattern and an allowed pattern will be allowed
  • Enables clean domain layer isolation while permitting specific exceptions
• Configuration: New optional parameter:
  • allowedDependencies (array, default: []) - Whitelist patterns that override forbidden dependencies
• Use Case Example: Forbid all namespaced dependencies in the domain layer, except for App\Shared, App\Capability, and Psr\*:

services:
    -
        class: Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule
        arguments:
            forbiddenDependencies: [
                '/^App\\Capability\\.*\\Domain$/': [
                    '/.*\\\\.*/'  # Match anything with a backslash (namespaced)
                ]
            ]
            checkFqcn: true
            allowedDependencies: [
                '/^App\\Capability\\.*\\Domain$/': [
                    '/^App\\Shared\\/',
                    '/^App\\Capability\\/',
                    '/^Psr\\/'
                ]
            ]
        tags:
            - phpstan.rules.rule

✨ Required Methods Feature for MethodSignatureMustMatchRule

Enhancement: Enforce Method Implementation in Matching Classes

• Class: Phauthentic\PHPStanRules\Architecture\MethodSignatureMustMatchRule
• Purpose: Ensures that classes matching a pattern actually implement a required method with the specified signature
• Key Features:
  • New required parameter (boolean, default: false)
  • When true, enforces that matching classes must implement the specified method
  • Reports clear error messages with the expected signature when a required method is missing
• Use Case Example: Ensure all controllers implement an execute method:

services:
    -
        class: Phauthentic\PHPStanRules\Architecture\MethodSignatureMustMatchRule
        arguments:
            signaturePatterns:
                -
                    pattern: '/^.*Controller::execute$/'
                    minParameters: 1
                    maxParameters: 1
                    signature:
                        -
                            type: 'Request'
                            pattern: '/^request$/'
                    visibilityScope: 'public'
                    required: true
        tags:
            - phpstan.rules.rule

🔧 Code Quality Improvements

🏗️ PHPStan Level 8 Compliance

• Enhancement: All rule classes now pass PHPStan level 8 analysis
• Improvements:
  • Updated error handling to use IdentifierRuleError instead of generic RuleError
  • Enhanced method signatures with explicit type hints for better clarity and type safety
  • Added parameter type annotations in processNode methods for improved documentation
  • Removed unnecessary instance checks in processNode methods to streamline logic
  • Improved error handling and reporting consistency across all rules

🔧 CI Pipeline Enhancements

• New Jobs: Added dedicated PHPStan and PHPCS jobs to CI configuration
• Configuration:
  • Both jobs run on Ubuntu 24.04 with PHP 8.4
  • Ensures static analysis and coding standards are enforced on every push and pull request
• Benefits:
  • Catches type errors and coding standard violations early
  • Maintains consistent code quality across contributions

📚 Documentation Improvements

📚 New Extending Rules Documentation

• New File: docs/ExtendingRules.md
• Purpose: Comprehensive guide for creating domain-specific, self-documenting rules by extending base rules
• Contents:
  • Benefits of extending rules (self-documenting code, reusability, IDE support, testability)
  • Multiple examples including:
    • Forbidding DateTime in module namespaces
    • Enforcing final classes in domain layer
    • Preventing legacy namespace usage
  • How to customize error messages and identifiers
  • Best practices for organizing custom rules

📚 Updated README

• New Section: "Domain Specific Rules / Extending Rules" with link to new documentation
• Enhancement: Clearer explanation of the extensibility features

📚 Enhanced Dependency Constraints Rule Documentation

• Deprecation Notice: Clear warning about the renamed class
• New Section: Detailed documentation for the allowedDependencies parameter
• Diagram: Added Mermaid flowchart explaining the allow/forbid logic
• Examples: Comprehensive configuration examples for the whitelist feature

📚 Enhanced Method Signature Must Match Rule Documentation

• New Section: Documentation for the required parameter
• Example: Complete configuration example for enforcing required methods

🚀 Migration Guide

For Existing Users

No immediate action required! All existing configurations continue to work without changes due to backward compatibility.

Recommended Updates

1. Rename DependencyConstraintsRule to ForbiddenDependenciesRule:

   Before:

   class: Phauthentic\PHPStanRules\Architecture\DependencyConstraintsRule

   After:

   class: Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule

2. Consider using allowedDependencies for cleaner "forbid everything except X" patterns instead of complex negative regex.

3. Consider using the required parameter for MethodSignatureMustMatchRule to enforce method implementation in matching classes.

💡 Why This Matters

Clearer Naming

The rename from DependencyConstraintsRule to ForbiddenDependenciesRule makes the rule's purpose immediately clear - it forbids specific dependencies. This follows the principle of self-documenting code.

Flexible Dependency Control

The new allowedDependencies feature provides a powerful yet simple way to implement "whitelist" patterns. Instead of crafting complex negative lookahead regex patterns, you can now simply:

1. Forbid everything with a broad pattern
2. Allow specific exceptions with simple patterns

This significantly simplifies configuration for common architectural patterns like clean architecture domain layers.

Enforce Architectural Contracts

The required parameter for MethodSignatureMustMatchRule enables enforcement of architectural contracts. For example, ensuring all controllers implement a specific execute method guarantees consistency across your application without relying on abstract classes or interfaces.

Extensibility

The new documentation on extending rules encourages creating domain-specific, self-documenting rules. A class named DomainClassesMustBeFinalRule is far more readable than a configuration block with regex patterns.

---

This release significantly improves the usability and flexibility of the PHPStan rules while maintaining 100% backward compatibility. We recommend updating to the new class names and exploring the new features to improve your architectural enforcement.

Full Changelog: 1.6.0...1.7.0