Celerik\Ui\Upload

StoredFile

final class Celerik\Ui\Upload\StoredFile implements JsonSerializable

A validated file in its final location.

Methods

__construct

__construct(string $path, string $name, string $originalName, string $mimeType, int $size)

• $name: Random stored file name (e.g. "3f2a…9c.pdf"), safe to use in paths.
• $originalName: Sanitized client name, for display only: never use it in a path.

jsonSerialize

jsonSerialize(): array

UploadException

final class Celerik\Ui\Upload\UploadException extends InvalidArgumentException implements Stringable

A rejected upload. The message is safe to show to the user.

UploadHandler

final class Celerik\Ui\Upload\UploadHandler

Validates and stores uploads.

Two ways to use it:

• Asynchronous (Field::file()->upload($url), FilePond): the endpoint calls process() and answers the returned id as text/plain; DELETE calls revert(). When the form is submitted, the field holds the ids and the controller calls claim() for each one.
• Classic form post (no upload URL): the controller calls store() for each file.

Validation: upload errors, empty files, size limit, the real MIME type (read from the content with finfo, never trusted from the browser), the extension matching that type, and forbidden extensions anywhere in the name (photo.php.jpg is refused). Stored files get random names. Keep both directories outside the web root and serve files through a controller that checks access.

Methods

__construct

__construct(UploadRules $rules, string $temporaryDirectory)

process

process(UploadedFile $file): string

Validates the file and keeps it in the temporary directory.

• Throws UploadException

revert

revert(string $id): bool

Deletes a temporary upload (FilePond's "revert"). Unknown ids are ignored.

claim

claim(string $id, string $directory): StoredFile

Moves a temporary upload to its final directory, after checking it again.

• Throws UploadException When the id is unknown, expired or no longer valid.

store

store(UploadedFile $file, string $directory): StoredFile

Validates the file and moves it straight to its final directory (no FilePond).

• Throws UploadException

purge

purge(int $maxAge = 86400): int

Deletes temporary uploads older than $maxAge seconds (never claimed). Run it from a cron job.

inspect

inspect(UploadedFile $file): array

Validates a file without moving it (also used by the File Manager's upload hook).

• Throws UploadException

UploadRules

final class Celerik\Ui\Upload\UploadRules

Which files an upload field accepts: MIME types with their allowed extensions, a size limit and a file count. The same rules drive the field (accept attribute, client-side checks, help text) and the server (UploadHandler).

Constants

Constant	Value
KNOWN_TYPES	['image/jpeg' => ['jpg', 'jpeg'], 'image/png' => ['png'], 'image/gif' => ['gif'], 'image/webp' => ['webp'], 'image/avif' => ['avif'], 'application/pdf' => ['…
FORBIDDEN_EXTENSIONS	['php', 'php3', 'php4', 'php5', 'php7', 'php8', 'phtml', 'phar', 'pht', 'phps', 'inc', 'asp', 'aspx', 'jsp', 'cgi', 'pl', 'py', 'rb', 'sh', 'bash', 'exe', 'c…
DEFAULT_MAX_SIZE	5242880

Methods

types

static types(string ...$mimeTypes): self

Rules for known MIME types, e.g. UploadRules::types('image/png', 'application/pdf').

images

static images(): self

JPEG, PNG, GIF and WebP images.

documents

static documents(): self

PDF, Word, Excel, OpenDocument text and plain text documents.

withType

withType(string $mimeType, array $extensions): self

• $extensions: Lowercase, without the dot.

maxSize

maxSize(string|int $size): self

Maximum size per file, in bytes or as "500K", "5M", "1G".

maxFiles

maxFiles(int $maxFiles): self

allows

allows(string $mimeType, string $extension): bool

accept

accept(): string

Value for the input's accept attribute, e.g. "image/png,.png,application/pdf,.pdf".

describe

describe(): string

Help text describing the rules, e.g. "JPG, JPEG, PNG. Up to 5 MB per file."

formatSize

static formatSize(int $bytes): string

UploadedFile

final class Celerik\Ui\Upload\UploadedFile

A file received over HTTP, before validation.

Plain PHP: UploadedFile::fromGlobals($_FILES['avatar']) checks is_uploaded_file(). Laravel / Symfony (already checked by the framework):

new UploadedFile($file->getPathname(), $file->getClientOriginalName(), $file->getError())

Methods

__construct

__construct(string $path, string $clientName, int $error = Celerik\Ui\Upload\UPLOAD_ERR_OK)

fromGlobals

static fromGlobals(array $entry): array

Normalizes one $_FILES entry, single or multiple (name="files[]").