Enhanced Max Line Length Rule

Release Notes - Version 1.6.0

🎉 New Features

✨ Enhanced Max Line Length Rule

Enhancement: Flexible Line Type Ignoring

• Class: Phauthentic\PHPStanRules\CleanCode\MaxLineLengthRule

• Purpose: Extended to support ignoring multiple types of lines beyond just use statements, providing more granular control over line length checking

• Key Features:

  • New Array-Based API: Introduced ignoreLineTypes parameter for flexible configuration
  • Multiple Line Types: Support for ignoring use statements, namespace declarations, and docblocks
  • Backward Compatible: Existing ignoreUseStatements parameter continues to work unchanged
  • Selective Control: Choose which line types to ignore independently

• Supported Line Types:

  • useStatements - Ignore lines containing use statements (e.g., use Some\Very\Long\Namespace\Path\ClassName;)
  • namespaceDeclaration - Ignore lines containing namespace declarations (e.g., namespace App\Some\Very\Long\Namespace\Path;)
  • docBlocks - Ignore lines that are part of docblock comments (e.g., /** This is a very long docblock comment that exceeds the line length limit */)

• Configuration: Supports new optional parameter:

  • ignoreLineTypes (array, default: []) - Array of line types to ignore with boolean values
  • ignoreUseStatements (boolean, default: false) - Maintained for backward compatibility, takes precedence when set

• Backward Compatibility:

  • The existing ignoreUseStatements parameter remains fully functional
  • When both ignoreUseStatements and ignoreLineTypes['useStatements'] are set, ignoreUseStatements takes precedence
  • All existing configurations continue to work without modification

📚 Documentation Improvements

📚 Enhanced Max Line Length Rule Documentation

• Comprehensive Examples: Added detailed configuration examples for:

  • New array-based API (recommended approach)
  • Legacy parameter usage (backward compatible)
  • Selective line type ignoring
  • Combined configurations

• Parameter Documentation: Complete documentation of all parameters including:

  • maxLineLength - Maximum allowed line length
  • excludePatterns - File exclusion patterns
  • ignoreUseStatements - Legacy parameter for backward compatibility
  • ignoreLineTypes - New array-based configuration option

• Use Cases Section: Examples showing:

  • Ignoring only use statements
  • Ignoring namespace declarations and docblocks
  • Ignoring all supported line types
  • Combining with file exclusions

🚀 Migration Guide

For Existing Users

No Action Required! All existing configurations continue to work without any changes. The new ignoreLineTypes parameter is optional and disabled by default, so your current setup will behave exactly as before.

For New Configurations

Recommended: Use the new array-based API for better flexibility:

ignoreLineTypes:
    useStatements: true
    namespaceDeclaration: true
    docBlocks: true

Legacy: The ignoreUseStatements parameter still works and is fully supported:

ignoreUseStatements: true

💡 Why This Matters

The previous version only supported ignoring use statements. Many codebases have long namespace declarations or detailed docblocks that exceed line length limits but are acceptable for readability. This release provides the flexibility to ignore these line types while still enforcing line length limits for actual code logic.

Before (1.5.1): Only use statements could be ignored
After (1.6.0): You can now ignore:

• Use statements
• Namespace declarations
• Docblock comments
• Any combination of the above

This significantly improves the rule's usability in real-world scenarios where certain types of long lines are acceptable or even preferred for code clarity.

---

This release represents a major enhancement to the Max Line Length Rule while maintaining 100% backward compatibility with existing configurations. We recommend gradually adopting the new array-based API for better flexibility and future-proofing your configuration.

Full Changelog: 1.5.1...1.6.0

Fixed Max Line Length Rule - Use Statement Ignoring

Release Notes - Version 1.5.1

🐛 Bug Fixes

🔧 Fixed Max Line Length Rule - Use Statement Ignoring

Bug Fix: Use Statement Ignoring Not Working Correctly

• Class: Phauthentic\PHPStanRules\CleanCode\MaxLineLengthRule

• Issue: When ignoreUseStatements was set to true, the rule was not properly ignoring long use statement lines. The check only examined the node type during initial processing, but didn't account for cases where the same line could be processed multiple times or where use statements appeared on lines that exceeded the maximum length.

• Solution:

  • Implemented a caching mechanism to track which lines contain use statements per file
  • Added proper line-level checking to ensure use statements are consistently ignored regardless of processing order
  • Enhanced the rule to check both the node type and the cached line information

• Impact:

  • Use statements that exceed the maximum line length are now correctly ignored when ignoreUseStatements: true is configured
  • Other long lines in the same file continue to be detected as expected
  • No breaking changes - existing configurations continue to work as intended

• Testing:

  • Added comprehensive test cases to verify use statements are properly ignored
  • Added test cases to ensure non-use statement lines are still detected when use statements are ignored
  • Ensures the fix doesn't break the default behavior of detecting long use statements

💡 Why This Matters

Previously, developers who configured the rule to ignore use statements might have still received false positives for long use statement lines. This fix ensures that when you configure the rule to ignore use statements, those lines are consistently and reliably ignored, allowing you to focus on enforcing line length limits for actual code logic rather than import statements.

Before (1.5.0): Long use statements could still trigger errors even when ignoreUseStatements: true
After (1.5.1): Long use statements are properly ignored when configured, while other long lines are still detected

---

This is a bug fix release that improves the reliability of the Max Line Length Rule's use statement ignoring feature. All existing configurations continue to work without any changes required.

Full Changelog: 1.5.0...1.5.1

1.5.0

Release Notes - Version 1.5.0

🎉 New Features

✨ Enhanced Dependency Constraints Rule

Enhancement: FQCN (Fully Qualified Class Name) Checking

• Class: Phauthentic\PHPStanRules\Architecture\DependencyConstraintsRule

• Purpose: Extended to check not only use statements but also fully qualified class names throughout your codebase

• Key Features:

  • Backward Compatible: Existing configurations continue to work unchanged (FQCN checking is opt-in)
  • Comprehensive Coverage: Detects forbidden dependencies in 11 different contexts
  • Selective Checking: Configure which reference types to check for optimal performance
  • Flexible Configuration: Enable FQCN checking with a simple boolean flag

• Supported Reference Types:

  • new - Class instantiations (e.g., new \DateTime())
  • param - Parameter type hints (e.g., function foo(\DateTime $date))
  • return - Return type hints (e.g., function foo(): \DateTime)
  • property - Property type hints (e.g., private \DateTime $date)
  • static_call - Static method calls (e.g., \DateTime::createFromFormat())
  • static_property - Static property access (e.g., \DateTime::ATOM)
  • class_const - Class constant (e.g., \DateTime::class)
  • instanceof - instanceof checks (e.g., $x instanceof \DateTime)
  • catch - catch blocks (e.g., catch (\Exception $e))
  • extends - class inheritance (e.g., class Foo extends \DateTime)
  • implements - interface implementation (e.g., class Foo implements \DateTimeInterface)

• Configuration: Supports new optional parameters:

  • checkFqcn (boolean, default: false) - Enable FQCN checking
  • fqcnReferenceTypes (array, default: all types) - Select specific reference types to check

📚 Documentation Improvements

📚 Enhanced Dependency Constraints Rule Documentation

• Comprehensive Examples: Added detailed configuration examples for basic usage, FQCN checking, and selective reference types
• Use Cases Section: Added real-world examples including:
  • Preventing DateTime usage in domain layers
  • Selective checking for performance optimization
• Reference Types Documentation: Complete list and explanation of all 11 supported reference types
• Backward Compatibility Notes: Clear explanation of how existing configurations are unaffected

📚 README Improvements

• New Section: "What if I need to ignore a Rule in a certain Place?"
  • Explains how to use PHPStan inline annotations
  • Emphasizes keeping rule exceptions documented close to the code
  • Encourages adding comments explaining why a rule is broken

🚀 Migration Guide

For Existing Users

No Action Required! All existing configurations continue to work without any changes. The new FQCN checking feature is disabled by default (checkFqcn: false), so your current setup will behave exactly as before.

💡 Why This Matters

The previous version only checked use statements, which meant developers could bypass dependency constraints by using fully qualified class names. This release closes that loophole while maintaining backward compatibility.

Before (1.4.0): Only use DateTime; would be caught
After (1.5.0): All of these are now caught when checkFqcn: true:

• use DateTime;
• new \DateTime()
• function process(\DateTime $date)
• function get(): \DateTime
• private \DateTime $createdAt
• And 6 more reference types!

This significantly strengthens your architecture enforcement capabilities and helps maintain clean boundaries between layers and modules.

---

This release represents a major enhancement to the Dependency Constraints Rule while maintaining 100% backward compatibility with existing configurations. We recommend gradually enabling FQCN checking in your projects to ensure complete dependency constraint enforcement.

Full Changelog: 1.4.0...1.5.0

1.4.0

🎉 New Features

✨ Modular Architecture Rules

New Rule: Modular Architecture Rule

• Class: Phauthentic\PHPStanRules\Architecture\ModularArchitectureRule
• Purpose: Enforces strict dependency rules for modular hexagonal (Ports and Adapters) architecture with capabilities/modules
• Key Features:
  • Enforces intra-module layer dependencies (Domain, Application, Infrastructure, Presentation)
  • Enforces cross-module dependencies using configurable regex patterns
  • Supports custom layer dependency rules
  • Configurable base namespace for capabilities/modules
• Configuration: Supports baseNamespace, layerDependencies, and allowedCrossModulePatterns parameters
• Example: Perfect for modular monoliths where each capability/module follows a layered architecture pattern

New Rule: Circular Module Dependency Rule

• Class: Phauthentic\PHPStanRules\Architecture\CircularModuleDependencyRule
• Purpose: Detects circular dependencies between modules in a modular architecture
• Key Features:
  • Tracks module-to-module dependencies
  • Reports circular dependency chains (e.g., Module A → Module B → Module C → Module A)
  • Configurable base namespace for capabilities/modules
• Configuration: Requires baseNamespace parameter

✨ Specification Docblock Rule

New Rule: Class Must Have Specification Docblock Rule

• Class: Phauthentic\PHPStanRules\Architecture\ClassMustHaveSpecificationDocblockRule
• Purpose: Ensures that classes, interfaces, and/or methods matching specified patterns have a properly formatted docblock with a "Specification:" section
• Key Features:
  • Validates classes and interfaces using regex patterns
  • Validates methods using FQCN::methodName format with regex patterns
  • Configurable specification header text (default: "Specification:")
  • Optional requirement for blank line after header
  • Optional requirement for list items to end with periods
  • Supports annotations after specification section
• Configuration: Supports classPatterns, methodPatterns, specificationHeader, requireBlankLineAfterHeader, and requireListItemsEndWithPeriod parameters

✨ Enhanced Clean Code Rules

Too Many Arguments Rule - Pattern Support

• Enhancement: Added optional patterns parameter to apply rule only to classes matching specific regex patterns
• Backward Compatible: Existing configurations without patterns continue to work (applies to all classes)
• Example: Can now configure to only check specific classes like '/.*Service$/' or '/App\\Service\\/'

Max Line Length Rule - Use Statement Ignoring

• Enhancement: Added ignoreUseStatements parameter to optionally ignore use statement lines
• Configuration: Boolean flag (default: false) to exclude use statements from line length checking

📚 Documentation Improvements

📚 New Documentation Files

• Modular Architecture Rule: Complete documentation with examples for modular monolith architectures
• Circular Module Dependency Rule: Full documentation with configuration examples
• Class Must Have Specification Docblock Rule: Comprehensive documentation with multiple configuration examples for classes, interfaces, and methods
• Too Many Arguments Rule: Updated documentation with pattern support examples
• Max Line Length Rule: Updated documentation with ignoreUseStatements parameter

📚 Documentation Structure Improvements

• Refactored Documentation: Moved all individual rule documentation from docs/Rules.md to individual files in docs/rules/ directory
• Improved Navigation: Each rule now has its own dedicated documentation file for better discoverability
• Enhanced Examples: Added comprehensive configuration examples for all new rules
• Real-world Use Cases: Added practical examples for modular architecture setup

🚀 Migration Guide

For Existing Users

All existing configurations continue to work without changes. The new rules are opt-in and require explicit configuration.

For New Modular Architecture Features

To use the new modular architecture rules:

services:
    -
        class: Phauthentic\PHPStanRules\Architecture\ModularArchitectureRule
        arguments:
            baseNamespace: 'App\\Capability'
            layerDependencies:
                Domain: []
                Application: [Domain]
                Infrastructure: [Domain, Application]
                Presentation: [Application]
            allowedCrossModulePatterns:
                - '/Facade$/'
                - '/FacadeInterface$/'
                - '/Input$/'
                - '/Result$/'
        tags:
            - phpstan.rules.rule
    
    -
        class: Phauthentic\PHPStanRules\Architecture\CircularModuleDependencyRule
        arguments:
            baseNamespace: 'App\\Capability'
        tags:
            - phpstan.rules.rule

For Specification Docblock Validation

To enforce specification docblocks:

services:
    -
        class: Phauthentic\PHPStanRules\Architecture\ClassMustHaveSpecificationDocblockRule
        arguments:
            classPatterns:
                - '/.*Facade$/'
                - '/.*Command$/'
            methodPatterns:
                - '/.*Repository::find.*/'
            specificationHeader: 'Specification:'
            requireBlankLineAfterHeader: true
            requireListItemsEndWithPeriod: false
        tags:
            - phpstan.rules.rule

For Enhanced Clean Code Rules

To use pattern matching with Too Many Arguments Rule:

services:
    -
        class: Phauthentic\PHPStanRules\CleanCode\TooManyArgumentsRule
        arguments:
            maxArguments: 3
            patterns: ['/.*Service$/', '/App\\Controller\\/']
        tags:
            - phpstan.rules.rule

To ignore use statements in Max Line Length Rule:

services:
    -
        class: Phauthentic\PHPStanRules\CleanCode\MaxLineLengthRule
        arguments:
            maxLineLength: 80
            ignoreUseStatements: true
        tags:
            - phpstan.rules.rule

This release significantly expands the capabilities of phpstan-rules, especially for teams working with modular monolith architectures and clean code practices, while maintaining full backward compatibility with existing configurations.

1.2.1

Release Notes

🐛 Bug Fixes

Final Class Rule

• Fixed: Abstract classes are now properly ignored by default to prevent false positives
• Added: Configurable ignoreAbstractClasses parameter (default: true) for users who want to enforce final declaration on abstract classes

Configuration

-
    class: Phauthentic\PHPStanRules\Architecture\ClassMustBeFinalRule
    arguments:
        patterns: ['/^App\\Service\\/']
        ignoreAbstractClasses: true  # Default behavior
    tags:
        - phpstan.rules.rule

Backward Compatible: All existing configurations continue to work without changes.

1.2.0: Improving the MethodMustReturnType to support unions (#7)

Release Notes

🎉 New Features

✨ Enhanced Method Must Return Type Rule

• New Feature: Added support for "void" as a type in addition to the legacy void: true approach
• New Feature: Added oneOf functionality for union types - allows specifying an array of types where one must match
• New Feature: Added allOf functionality for union types - allows specifying an array of types where all must be present
• New Feature: Added anyOf as an alias for oneOf for better readability
• New Feature: Added regex pattern support in oneOf, allOf, and anyOf arrays using regex: prefix
• Enhancement: Made configuration fields optional with sensible defaults (nullable, void, objectTypePattern)
• Enhancement: Added configuration normalization to handle missing fields gracefully

🔧 Configuration Improvements

• Backward Compatibility: All existing configurations continue to work without changes
• Flexible Configuration: Minimal configurations now work without requiring all fields
• Regex Support: Can use patterns like 'regex:/^App\\Entity\\/' to match entity classes

🔧 Documentation Improvements

📚 Enhanced Method Must Return Type Rule Documentation

• New Examples: Added comprehensive examples for oneOf, allOf, and anyOf usage
• Regex Documentation: Added documentation for regex pattern support with examples
• Configuration Guide: Updated configuration examples to show new optional fields
• Usage Examples: Added real-world examples for entity validation and union types

📚 Updated Configuration Examples

• New Configuration Patterns: Added examples for minimal configurations
• Regex Examples: Added examples showing how to use regex patterns for class matching
• Union Type Examples: Added examples for both oneOf and allOf scenarios

✅ New Test Cases

�� Comprehensive Test Coverage

• AnyOfRuleTest: Tests for the new anyOf functionality
• RegexRuleTest: Tests for regex pattern matching in anyOf arrays
• RegexAllOfRuleTest: Tests for regex pattern matching in allOf arrays
• EntityRegexRuleTest: Tests for realistic entity pattern matching scenarios
• FacadeRuleTest: Tests for minimal configuration scenarios
• UnionTypeRuleTest: Tests for union type functionality
• Enhanced MethodMustReturnTypeRuleTest: Updated existing tests for new functionality

📁 New Test Data Files

• data/MethodMustReturnType/AnyOfTestClass.php: Test cases for anyOf functionality
• data/MethodMustReturnType/EntityRegexTestClass.php: Test cases for entity regex patterns
• data/MethodMustReturnType/FacadeTestClass.php: Test cases for minimal configurations
• data/MethodMustReturnType/RegexAllOfTestClass.php: Test cases for allOf with regex
• data/MethodMustReturnType/RegexTestClass.php: Test cases for basic regex functionality
• data/MethodMustReturnType/UnionTypeTestClass.php: Test cases for union type validation

🏗️ Code Quality Improvements

🔧 Enhanced MethodMustReturnTypeRule

• New Methods: Added normalizeConfig(), isTypeMatchWithRegex(), getExpectedTypeDescription()
• Improved Error Handling: Better error messages for union types and regex patterns
• Code Organization: Better separation of concerns with dedicated methods for different validation types
• Type Safety: Enhanced type checking and validation logic

🐛 Bug Fixes

• Configuration Defaults: Fixed issues with missing configuration fields causing errors
• Regex Pattern Handling: Proper boolean conversion for regex pattern matching
• Union Type Parsing: Improved union type parsing and validation logic
• Error Message Consistency: Standardized error message formatting

📊 Statistics

• 16 files changed with 700+ lines added and 33 lines removed
• 17 new test files created for comprehensive coverage
• 100% backward compatibility maintained with existing configurations

🚀 Migration Guide

For Existing Users

No changes required! All existing configurations will continue to work exactly as before.

For New Features

To use the new union type functionality:

-
    class: Phauthentic\PHPStanRules\Architecture\MethodMustReturnTypeRule
    arguments:
        returnTypePatterns:
            -
                pattern: '/^MyClass::getValue$/'
                anyOf: ['int', 'string', 'bool']
            -
                pattern: '/^MyClass::getEntity$/'
                anyOf: ['regex:/^App\\Entity\\/', 'void']
    tags:
        - phpstan.rules.rule

This release significantly enhances the flexibility and power of the Method Must Return Type Rule while maintaining full backward compatibility.

1.1.0

Release Notes

🎉 New Features

✨ New Rule: Catch Exception of Type Not Allowed Rule

• Class: Phauthentic\PHPStanRules\Architecture\CatchExceptionOfTypeNotAllowedRule
• Purpose: Prevents catching overly broad exception types like Exception, Error, or Throwable
• Configuration: Accepts an array of forbidden exception types
• Example: Configure to prevent catching Exception, Error, or Throwable for better error handling practices

✨ Enhanced Method Signature Must Match Rule

• New Feature: Added visibility scope validation
• New Feature: Improved parameter validation with optional type checking
• Enhancement: Better error messages and validation logic
• Configuration: Now supports visibilityScope parameter (public, protected, private)

🔧 Documentation Improvements

📚 Fixed Class Name References

Updated all configuration examples to use correct class names:

• ReadonlyClassRule → ClassMustBeReadonlyRule
• FinalClassRule → ClassMustBeFinalRule
• NamespaceClassPatternRule → ClassnameMustMatchPatternRule

📚 Added Missing Rule Documentation

• Methods Returning Bool Must Follow Naming Convention Rule: Complete documentation added with configuration examples
• Catch Exception of Type Not Allowed Rule: Full documentation with examples

📚 Enhanced Documentation Structure

• Added anchor links to all rule sections for better navigation
• Improved README.md with clearer examples
• Updated namespace references from Phauthentic\PhpstanRules to Phauthentic\PHPStanRules

✅ New Test Cases

• CatchExceptionOfTypeNotAllowedRuleTest: Comprehensive tests for the new exception catching rule
• Enhanced MethodSignatureMustMatchRuleTest: Additional test cases for visibility scope and parameter validation

📁 New Test Data Files

• data/CatchExceptionOfTypeNotAllowed/CatchAllowedException.php: Examples of allowed exception catching
• data/CatchExceptionOfTypeNotAllowed/CatchForbiddenException.php: Examples of forbidden exception catching
• Enhanced data/MethodSignatureMustMatch/TestClass.php: Additional test methods for validation

🏗️ Code Quality Improvements

🔧 Refactoring

• MethodSignatureMustMatchRule: Improved code structure with better separation of concerns
• MethodMustReturnTypeRule: Enhanced documentation and code comments
• phpstan.neon: Removed hardcoded rule configurations (now serves as a clean template)

🐛 Bug Fixes

• Fixed namespace casing inconsistencies (PhpstanRules → PHPStanRules)
• Improved parameter validation logic in MethodSignatureMustMatchRule
• Enhanced error message formatting and consistency

1.0.0 - Initial Release

Adding Signature and Return Type checking Rules (#4)

* Adding rules to check return type and method signature
* Adding a rule for naming methods that return booleans