Php Cs Fixer Phpdoc Force Fqcn Laravel Package

Product Decisions This Supports

• Code Quality & Consistency: Enables strict adherence to PSR-12 (or custom) standards for FQCN (Fully Qualified Class Name) usage in DocBlocks, reducing ambiguity and improving IDE autocompletion/navigation.
• Developer Experience (DX): Reduces manual effort in maintaining consistent DocBlock formatting, especially in large codebases or teams with varying conventions.
• Onboarding & Maintenance: Simplifies new developer ramp-up by enforcing a single, predictable format for documentation references.
• Build vs. Buy: Avoids reinventing a custom solution for DocBlock validation, leveraging an existing, battle-tested rule in the PHP-CS-Fixer ecosystem.
• Roadmap Alignment: Supports initiatives like:
  • Scaling developer productivity in monorepos or microservices.
  • Enforcing stricter linting in CI/CD pipelines (e.g., pre-merge checks).
  • Preparing for PHP 8+ features (e.g., attributes) where FQCNs are increasingly critical.

When to Consider This Package

• Adopt if:

  • Your team enforces PSR-12 or a similar standard requiring FQCNs in DocBlocks.
  • You use PHP-CS-Fixer in your workflow and want to extend its rules without forking.
  • DocBlock inconsistencies cause IDE tooling issues (e.g., PhpStorm/PHPStan false positives).
  • You’re migrating legacy code with mixed DocBlock formats (e.g., Some\Class vs. \Some\Class).
  • Your CI/CD pipeline lacks automated DocBlock validation for FQCNs.

• Look elsewhere if:

  • Your project uses non-standard DocBlock formats (e.g., custom annotations).
  • You need dynamic FQCN resolution (e.g., for namespaced aliases like use Class as Alias).
  • The package’s last release (2021) is a blocker for your long-term roadmap (check for forks/maintenance).
  • Your team prioritizes performance over strictness (this adds a linting pass).
  • You’re using alternative tools (e.g., PHPStan’s parameters.docblock.type rules) that already cover this.

How to Pitch It (Stakeholders)

For Executives: "This is a low-cost, high-impact way to standardize our code documentation. By enforcing FQCNs in DocBlocks via PHP-CS-Fixer, we’ll reduce bugs from ambiguous references (e.g., Class vs. \Vendor\Class) and improve IDE tooling—all without manual reviews. It’s a 10-minute setup with years of maintenance savings, aligning with our quality and DX goals."

For Engineering/DevOps: *"We’re adding a PHP-CS-Fixer rule to auto-fix DocBlock FQCN inconsistencies. This:

• Saves time: No more manual fixes for use Class; vs. \Class in docs.
• Reduces tech debt: Catches issues early in CI (e.g., GitHub Actions).
• Works with existing tools: Integrates seamlessly with PHP-CS-Fixer’s config. Proposal: Enable in CI as a warning (then error) post-POC. Estimated effort: 2 hours to test/configure."*

For Developers: "Your PRs might get auto-updated to use \Vendor\Class instead of Class in DocBlocks—this makes IDE hints and static analysis (PHPStan) more reliable. It’s opt-in for now; let us know if it breaks your workflow!"