## 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

```text
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