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

__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.

string
ensureTargetDirectory(string $targetDirectory, UploadVisibility $visibility = UploadVisibility::Public)

Creates a visibility-constrained target and verifies containment before and after filesystem mutation.

string
string
buildRelativePath(string $targetRelativeDirectory, string $storedFilename)

Combines a storage-relative directory and generated filename without interpreting either as a public URL.

string
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.

string
string
buildPath(string $targetDirectory, string $storedFilename)

Combines a validated target directory and generated filename into its publication path.

string
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.

int
int
fileSize(string $path)

Reports the persisted byte count or maps filesystem failures to the upload storage category.

int
void

Removes one just-published result when its owning higher-level transaction cannot be confirmed.

void
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.

int

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.

Parameters

TranslatorInterface $translator
Filesystem $filesystem
UploadPathPolicy|null $pathPolicy
Closure|null $hardLink
ChunkUploadConfig|null $cleanupConfig

ensureTargetDirectory

string ensureTargetDirectory(string $targetDirectory, UploadVisibility $visibility = UploadVisibility::Public)

Creates a visibility-constrained target and verifies containment before and after filesystem mutation.

Parameters

string $targetDirectory
UploadVisibility $visibility

Return Value

string

buildRelativePath

string buildRelativePath(string $targetRelativeDirectory, string $storedFilename)

Combines a storage-relative directory and generated filename without interpreting either as a public URL.

Parameters

string $targetRelativeDirectory
string $storedFilename

Return Value

string

Exceptions

UploadStorageException

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.

Parameters

string|null $extension
string|null $publicationToken

Return Value

string

buildPath

string buildPath(string $targetDirectory, string $storedFilename)

Combines a validated target directory and generated filename into its publication path.

Parameters

string $targetDirectory
string $storedFilename

Return Value

string

Exceptions

UploadStorageException

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.

Parameters

StagedUpload $upload
string $targetDirectory
string $storedFilename
UploadVisibility $visibility
bool $allowExistingIdentical

Return Value

int

Exceptions

UploadStorageException

fileSize

int fileSize(string $path)

Reports the persisted byte count or maps filesystem failures to the upload storage category.

Parameters

string $path

Return Value

int

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.

Parameters

UploadedFile $upload

Return Value

void

Exceptions

UploadStorageException

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.

Parameters

string $targetDirectory
UploadVisibility $visibility
int|null $now

Return Value

int