Php Docblock Checker Laravel Package

Product Decisions This Supports

• Documentation coverage as a trackable quality metric. This tool gives a binary, CI-enforceable answer to "do our classes and methods have docblocks?" That turns an abstract "we should document more" into a pass/fail gate and a baseline number you can trend sprint over sprint — useful for tech-debt burn-down reporting and for justifying (or killing) a documentation initiative.
• Build vs. buy vs. borrow for a narrow need. The scope is deliberately tiny — presence checking, not style enforcement or content validation. Framing it as "borrow" (BSD-2 permits vendoring/forking) rather than "buy" keeps the decision cheap and reversible. The real build-vs-buy question becomes "adopt this, fork it, or fold the check into an existing coding-standard ruleset."
• Roadmap sequencing for documentation-dependent features. If generated API docs (phpDocumentor), IDE/static-analysis ergonomics, or SDK publishing are on the roadmap, docblock coverage is a prerequisite. This tool is the cheapest possible gate to establish before investing in generators or publishing pipelines.
• Use cases it genuinely serves: legacy-codebase documentation audits, a pre-refactor baseline before a large migration, an onboarding checklist item ("new code must carry docblocks"), and a low-friction PR gate for teams that won't accept a heavyweight linter.
• What it does not support: decisions about docblock quality. It won't catch stale @param tags, wrong types, or empty boilerplate — so don't let a green build be read as "our docs are good." Pair it with PHPStan/Psalm for correctness if that matters.

When to Consider This Package

Consider it when most of the following hold:

• You're on a PHP 7.x-era stack (or can verify compatibility), and CI already runs Composer scripts — adoption is one dev dependency and one CI line.
• You want presence-only enforcement with minimal configuration and no appetite for rolling out a full coding standard.
• Your team is small and low-ceremony; a heavyweight ruleset would get ignored or disabled.
• You're comfortable pinning a version or forking it — this is archived and last released in 2021, so treat it as a frozen artifact, not a maintained dependency. BSD-2-Clause makes forking straightforward, but you own the maintenance from day one.

Look elsewhere when:

• You need PHP 8.1+ / current dependency support. An archived 2021 tool is a dependency-rot candidate (Console/Symfony version constraints are the usual failure point). Verify installability before promising anything.
• You want configurable, per-path rules, exclusions for generated code, or auto-fixing — go to PHP_CodeSniffer + Slevomat Coding Standard (doc-comment sniffs) or PHP-CS-Fixer's phpdoc rules. These are maintained, cover presence and formatting, and are already in most PHP toolchains.
• You need docblock correctness, not presence — PHPStan/Psalm are the right layer.
• You need vendor support, SLAs, or a security review trail — a 31-star archived repo won't clear procurement.
• You're standardizing tooling across many repos; a standalone one-off checker adds a bespoke CI step you'll have to maintain forever.

How to Pitch It (Stakeholders)

To executives: "This is a low-cost, reversible pilot to make documentation a measurable gate rather than a suggestion. It's a single CI check that reports whether our classes and methods carry docblocks, giving us a coverage signal we can report on. It costs essentially nothing and we can drop it in a sprint. Caveat: the project is archived, so I'm recommending a time-boxed pilot — adopt, measure for a quarter, and either fork it or fold the check into our existing coding-standard tooling."

To engineering: "One Composer dev dependency, one CI step, non-zero exit on missing docblocks. It checks presence only — it won't validate tag accuracy, so it complements rather than replaces PHPStan. Because it's archived and last shipped in 2021, we pin it and budget half a sprint to replace it with a Slevomat/PHP_CodeSniffer sniff, which is where I'd expect us to land long term."

Recommendation: Adopt as a time-boxed pilot on legacy repos only, with an explicit exit criterion — migrate to a maintained coding-standard sniff at the next tooling review. Do not make it a platform dependency, and don't cite a passing build as evidence of documentation quality.