Make the seams that closed say so

[jakejackson1]

File::isValid() stopped being an extension seam in 4.0.0 and said nothing. Two independent silent breaks:

1. The override stops being called. upload() routes through the private runValidations().
2. The property it wrote to is gone. protected $errors became private $errorDetails, so $this->errors[] = $message lands on a dynamic property nothing reads — and before PHP 8.2, without so much as a deprecation.

A subclass loosening a check fails safe. One adding a check — a virus scan, a tenant quota, a stricter name rule — has it bypassed on every upload, on a release whose headline is security.

What changed

final on isValid(), upload() and uploadValid(). The three share the reset-then-validate sequence, the re-entrancy lock and the error count that decides which files passed, so a partial override breaks one of them. prepareUpload() and store() are private either way, so an override could only ever have wrapped these — which is what beforeUpload/afterUpload are for. A check of your own belongs in a ValidationInterface, which all three run.

The error list is guarded on all four routes to it, because each is silent on its own:

Route	Caught by
$this->errors = [...]	__set()
$this->errors[] = $message — an append is a read	__get()
empty($this->errors) — answered true for a collection that rejected every file	__isset()
class Mine extends File { protected $errors = []; }	a construction-time check in init()

The magic methods run in File's scope, so the guard covers the rest of what the class declares private — $running above all, which a bare fallback would have let a subclass take from inside a callback. No magic method can see a property the subclass declares, and a static never dispatches to one at all, which is why init() carries the fifth name: protected static $errorCodeMessages, now getUploadErrorMessages().

UPGRADE.md gets a removed-seams table. §10 had the facts as prose; a migration is read in two columns. The rows that did not move are half the value — FileInfo::isUploadedFile() and getReservedWindowsNames() still hold, FileSystem::resolveFilename() still names the file but no longer refuses one, and FileInfo::sanitizeName() is a seam setExtension() re-fits behind. FileTest pins the table by reflection, in the idiom testReadmeDocumentsTheDefaultDenyList() already uses, so it cannot drift the way the 4.0.0 docs did.

Compatibility

Breaking for a File subclass that overrode one of the three entry points or touched the error list — which is the point: each was already broken and now says so, at load or at construction rather than never. CHANGELOG.md and UPGRADE.md cover both.

Checks

phpunit (716 tests, 1,436 assertions), phpstan (level 9), lint, check-syntax, psr7-readme and base64-docs all pass. i18n:pot regenerates with no diff — the new exception messages are developer-facing and unmarked.

🤖 Generated with Claude Code