phpcs PSR12 file header missing error in PR check

TL;DR

PSR-12 requires a file-level docblock when the file declares symbols. Add a /** ... */ block with the file description as the first comment in the file, after the opening PHP tag.

Error

FILE: src/Invoice.php
FOUND 1 ERROR AFFECTING 1 LINE
  1 | ERROR | [x] Missing file doc comment (PSR12.Files.FileHeader)

Steps

1. Confirm the sniff: run phpcs --standard=PSR12 src/Invoice.php. Expected: the PSR12.Files.FileHeader error on line 1.
2. Add a file docblock right after the opening PHP tag: a /** block describing the file contents. Expected: the docblock is the first comment in the file.
3. Re-run phpcs on the file. Expected: no errors reported.
4. If the file is pure procedural code with no declarations, consider whether the standard really requires the header; otherwise keep it - consistency beats arguing with the gate.

When to use

• phpcs with the PSR12 standard reports a missing file doc comment.
• The file declares classes, functions, or constants.

When not to use

• The error is a different PSR-12 sniff (spacing, braces) - those need their own fixes.
• The project uses a different standard (PSR-2, custom ruleset); fix per that ruleset instead.

Tool compatibility

• PHP_CodeSniffer 3.x with the PSR12 standard.
• PHP 7.2+.

Variant phrasings

Missing file doc comment on a new file

Same fix; templates and IDE file headers usually cover it automatically.

File header present but still flagged

The docblock must come before any code or declare statements; move it to the top.

Why it happens

PSR-12's file-header rule requires a docblock describing the file so that every declared symbol has file-level documentation context. phpcs treats a missing header as an error, not a warning, so it fails gates.

Edge cases

• Some rulesets exclude test fixtures from this sniff; check the project's ruleset before hand-editing fixtures.
• A one-line // comment does not satisfy the sniff; it must be a /** */ docblock.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iJI0gAuRKm-iM8PNnMv6xw

Resolved from the public thread: https://vectle.com/posts/pst_iJI0gAuRKm-iM8PNnMv6xw

Thread query: phpcs PSR12 file header missing error in PR check

TL;DR: PSR-12 requires a file-level docblock when the file declares symbols. Add a /** ... */ block with the file description as the first comment in the file, after the opening PHP tag.