UploadStorage
final class UploadStorage (View source)
| internal | Applications should use UploadFactory so validation and storage policy cannot be separated. |
Publishes caller-asserted snapshots inside visibility-specific storage boundaries.
This trusted-code boundary enforces paths, permissions, identity, and atomic no-clobber publication, but does not perform MIME, risk, or image validation. Applications must use UploadFactory for untrusted input.
Constants
| private COPY_BYTES |
|
| private CREATE_ATTEMPTS |
|
| private TEMPORARY_DIRECTORY |
|
Methods
Retains filesystem and path-policy collaborators used for constrained publication.
Creates a visibility-constrained target and verifies containment before and after filesystem mutation.
Combines a storage-relative directory and generated filename without interpreting either as a public URL.
Produces an unpredictable basename, or validates a server-owned retry token, while preserving the extension.
Combines a validated target directory and generated filename into its publication path.
Atomically publishes a verified snapshot without exposing partial bytes or replacing an existing target.
Reports the persisted byte count or maps filesystem failures to the upload storage category.
Removes one just-published result when its owning higher-level transaction cannot be confirmed.
Reclaims a bounded number of old publication temporaries whose process lease is no longer active.
Details
__construct
__construct(TranslatorInterface $translator, Filesystem $filesystem, UploadPathPolicy|null $pathPolicy = null, Closure|null $hardLink = null, ChunkUploadConfig|null $cleanupConfig = null)
Retains filesystem and path-policy collaborators used for constrained publication.
Omitting the path policy is retained only for constructor compatibility; such an instance refuses storage.
ensureTargetDirectory
string
ensureTargetDirectory(string $targetDirectory, UploadVisibility $visibility = UploadVisibility::Public)
Creates a visibility-constrained target and verifies containment before and after filesystem mutation.
buildRelativePath
string
buildRelativePath(string $targetRelativeDirectory, string $storedFilename)
Combines a storage-relative directory and generated filename without interpreting either as a public URL.
generateFilename
string
generateFilename(string|null $extension = null, string|null $publicationToken = null)
Produces an unpredictable basename, or validates a server-owned retry token, while preserving the extension.
buildPath
string
buildPath(string $targetDirectory, string $storedFilename)
Combines a validated target directory and generated filename into its publication path.
publishSnapshot
int
publishSnapshot(StagedUpload $upload, string $targetDirectory, string $storedFilename, UploadVisibility $visibility, bool $allowExistingIdentical = false)
Atomically publishes a verified snapshot without exposing partial bytes or replacing an existing target.
A complete same-directory temporary file is linked to the final random name only after its measured size and digest match the sealed staging identity. An explicitly idempotent retry may reuse only byte-identical output; any failure after a new publication removes the new target.
fileSize
int
fileSize(string $path)
Reports the persisted byte count or maps filesystem failures to the upload storage category.
rollbackPublished
void
rollbackPublished(UploadedFile $upload)
Removes one just-published result when its owning higher-level transaction cannot be confirmed.
The path is revalidated against its visibility root and symbolic links are never followed.
cleanupPublicationOrphans
int
cleanupPublicationOrphans(string $targetDirectory, UploadVisibility $visibility, int|null $now = null)
Reclaims a bounded number of old publication temporaries whose process lease is no longer active.
Only exact framework-owned temporary basenames inside the validated target directory are considered. Symbolic links, recent files, changed path identities, and files locked by an active publisher are skipped.