PHPDoc / Docblock
debt(d3/e1/b3/t5)
Closest to 'default linter catches the common case' (d3). The term's detection_hints.tools lists phpstan, psalm, phpcs, and phpdoc — these are standard PHP ecosystem tools that catch redundant docblocks, missing @throws tags, and type mismatches. PHPStan and Psalm are commonly configured in CI pipelines and flag docblock issues automatically.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix describes adding or removing docblock annotations — this is a single-line or few-line change per method. Fixing outdated docblocks or adding missing @throws is localized to the declaration site with no ripple effects.
Closest to 'localised tax' (b3). Docblock conventions apply across all PHP contexts (web, cli, queue-worker per applies_to), but the impact is localized — poor docblock hygiene affects IDE autocompletion and static analysis accuracy for that component, not architectural decisions. It's a persistent minor friction rather than a system-shaping choice.
Closest to 'notable trap' (t5). The misconception field states developers believe 'PHPDoc blocks are redundant once PHP has native type declarations' — this is a documented gotcha that most PHP devs eventually learn. The trap is that docblocks serve purposes native types cannot (generics via @template, exception contracts via @throws, complex array shapes), but it's not counterintuitive once explained.
Also Known As
TL;DR
Explanation
PHPDoc docblocks (/** ... */) use tags like @param, @return, @throws, @var, @property, @template, and @deprecated to annotate code. IDEs (PhpStorm, VS Code with Intelephense) use them for autocomplete and type inference; tools like PHPStan and Psalm use them for advanced static analysis; phpDocumentor generates API documentation from them. With modern PHP's native type declarations, many @param and @return tags are redundant — use them to add context, describe array shapes, or document generic types not expressible in PHP's type system.
Common Misconception
Why It Matters
Common Mistakes
- Docblocks that restate the type declarations already visible in the signature — zero added value.
- Missing @throws tags — callers cannot know which exceptions to handle.
- @param with no description for non-obvious parameters — the type is already in the declaration.
- Outdated docblocks that contradict the current code — worse than no docblock.
Code Examples
/**
* Get user
* @param int $id The id
* @return User The user
*/
public function getUser(int $id): User // Docblock adds nothing — all visible in signature
// Valuable docblock:
/**
* Finds user by ID. Throws if not found because callers must handle absence explicitly.
* @throws UserNotFoundException if no user with this ID exists
* @throws DatabaseException on connection failure
*//**
* Transfer funds between two accounts atomically.
*
* @param Account $from Source account — must have sufficient balance
* @param Account $to Destination account
* @param Money $amount Amount to transfer — must be positive
* @return Transfer The completed transfer record
* @throws InsufficientFundsException If $from balance < $amount
* @throws CurrencyMismatchException If accounts use different currencies
*/
public function transfer(Account $from, Account $to, Money $amount): Transfer
// Skip docblocks when types + names are already self-documenting:
public function findById(int $id): ?User {} // no docblock needed