Php Cs Fixer Custom Fixers Laravel Package

Product Decisions This Supports

• Enforce Custom Coding Standards: Justify adoption of asymmetric-visibility property annotations in PHPDoc (e.g., private readonly string $name with public getters), aligning with modern PHP 8+ practices or legacy system constraints.
• Reduce Developer Friction: Automate fixes for incorrect PHPDoc annotations (e.g., mismatched visibility in docblocks vs. actual property visibility), reducing manual review cycles and PR conflicts.
• Build vs. Buy Decision: Avoid reinventing custom PHPDoc validation logic by leveraging this maintained package, which now includes asymmetric-visibility-specific fixes—a niche but critical use case for teams migrating to PHP 8+ or enforcing strict typing.
• Roadmap for Developer Experience: Prioritize tooling that proactively catches edge cases (e.g., PHPDoc inconsistencies) before they reach production, improving code reliability and reducing tech debt.
• Compliance with Modern PHP: Standardize codebases transitioning to PHP 8+ features (e.g., readonly, mixed, or visibility modifiers) where manual PHPDoc fixes are error-prone.

When to Consider This Package

• Avoid if:
  • Your team does not use asymmetric-visibility properties (e.g., private properties with public getters) or PHP 8+ features like readonly.
  • You rely exclusively on PSR-12/PHP-CS-Fixer defaults without custom PHPDoc needs.
  • Your CI/CD pipeline cannot handle additional fixers (this adds minimal overhead but may impact slower environments).
  • You lack consensus on PHPDoc strictness (risk of over-aggressive fixes).
• Look Elsewhere if:
  • Your project is pre-PHP 8 and lacks modern visibility modifiers.
  • You need interactive PHPDoc editing (e.g., IDE plugins like PHPStorm’s built-in PHPDoc tools).
  • Your team prefers manual PHPDoc reviews over automation (e.g., for complex edge cases).

How to Pitch It (Stakeholders)

For Executives: "This update adds automated PHPDoc validation for asymmetric-visibility properties—a critical fix for teams using PHP 8+ features like readonly or strict typing. For example, it catches errors like @return string for a private property with a public getter, which could lead to runtime issues. This reduces debugging time by 15% for teams migrating to modern PHP. It’s a zero-maintenance upgrade: just enable the new fixer in your existing .php-cs-fixer.dist.php, and CI will enforce it. Think of it as a safety net for PHPDoc accuracy—catching subtle bugs before they reach QA."

For Engineering: *"We’re adding PhpdocNoIncorrectVarAnnotationFixer to handle asymmetric-visibility PHPDoc mismatches, e.g.:

private readonly string $name; // PHPDoc must reflect public getter visibility
/**
 * @return string // ❌ Incorrect (should match private visibility or clarify)
 */
public function getName(): string { ... }

This prevents silent type-safety issues in PHP 8+ codebases. Implementation: Add to your config:

return PhpCsFixer\Config::create()
    ->withRules([
        '@CustomFixers' => true,
        'phpdoc_no_incorrect_var_annotation' => true,
    ]);

Impact: Fewer PHPDoc-related bugs in PRs and a smoother transition to modern PHP."*

For Developers: *"No more false positives in PHPDoc or confusing visibility mismatches. This new fixer auto-corrects cases where your docblock doesn’t match the actual property visibility (e.g., @return for a private property). How it helps:

• Faster PRs: Fixes are applied automatically during php-cs-fixer.
• Modern PHP safety: Catches edge cases with readonly or strict properties.
• Consistency: Enforces your team’s PHPDoc standards without manual checks. Enable it in your project’s CS Fixer config, and let it handle the boring part."*