 |
VOOZH | about |
|
VOOZH | about |
This page documents the file upload exception hierarchy used by the UploadedFile class to represent various upload error conditions. These exceptions correspond to PHP's native file upload error codes (UPLOAD_ERR_* constants) and provide detailed error messages for debugging upload failures.
For general HTTP exceptions like PostTooLargeException, see HTTP Exceptions. For details on file upload handling and validation, see File Uploads.
The file upload exceptions follow a hierarchical structure with FileException as the base class for all upload-related errors.
Sources: src/UploadedFile.php14-22 src/Exceptions/CannotWriteFileException.php1-12 src/Exceptions/ExtensionFileException.php1-12
Each upload exception corresponds to a specific PHP upload error code. The following table maps error constants to exception classes and their associated error messages.
| PHP Constant | Exception Class | Error Message Template |
|---|---|---|
UPLOAD_ERR_INI_SIZE | IniSizeFileException | "The file "%s" exceeds your upload_max_filesize ini directive (limit is %d KiB)." |
UPLOAD_ERR_FORM_SIZE | FormSizeFileException | "The file "%s" exceeds the upload limit defined in your form." |
UPLOAD_ERR_PARTIAL | PartialFileException | "The file "%s" was only partially uploaded." |
UPLOAD_ERR_NO_FILE | NoFileException | "No file was uploaded." |
UPLOAD_ERR_CANT_WRITE | CannotWriteFileException | "The file "%s" could not be written on disk." |
UPLOAD_ERR_NO_TMP_DIR | NoTmpDirFileException | "File could not be uploaded: missing temporary directory." |
UPLOAD_ERR_EXTENSION | ExtensionFileException | "File upload was stopped by a PHP extension." |
| N/A | FileNotFoundException | "File does not exist at path {path}." |
| N/A | FileException | Generic file operation errors |
Sources: src/UploadedFile.php32-40
The base exception class for all file-related errors. It can be thrown directly for generic file operation failures or used as the parent class for more specific exceptions.
Common scenarios:
Thrown when the uploaded file exceeds the upload_max_filesize directive in php.ini. The error message includes the actual size limit in kilobytes.
Error code: UPLOAD_ERR_INI_SIZE (value: 1)
Sources: src/UploadedFile.php33 src/UploadedFile.php386-387
Thrown when the uploaded file exceeds the MAX_FILE_SIZE directive specified in the HTML form via a hidden input field.
Error code: UPLOAD_ERR_FORM_SIZE (value: 2)
Sources: src/UploadedFile.php34 src/UploadedFile.php388-389
Thrown when the file was only partially uploaded, typically due to network interruption or user cancellation during upload.
Error code: UPLOAD_ERR_PARTIAL (value: 3)
Sources: src/UploadedFile.php35 src/UploadedFile.php390-391
Thrown when no file was uploaded in the request, even though a file input field was present in the form.
Error code: UPLOAD_ERR_NO_FILE (value: 4)
Sources: src/UploadedFile.php36 src/UploadedFile.php392-393
Thrown when PHP failed to write the uploaded file to disk. This typically indicates filesystem permission issues or insufficient disk space.
Error code: UPLOAD_ERR_CANT_WRITE (value: 7)
Sources: src/UploadedFile.php37 src/UploadedFile.php394-395 src/Exceptions/CannotWriteFileException.php1-12
Thrown when PHP's temporary upload directory is missing from the server configuration. This indicates a server misconfiguration.
Error code: UPLOAD_ERR_NO_TMP_DIR (value: 6)
Sources: src/UploadedFile.php38 src/UploadedFile.php396-397
Thrown when a PHP extension stopped the file upload. This occurs when a loaded extension explicitly aborted the upload process through PHP's internal hooks.
Error code: UPLOAD_ERR_EXTENSION (value: 8)
Sources: src/UploadedFile.php39 src/UploadedFile.php398-399 src/Exceptions/ExtensionFileException.php1-12
Thrown when an expected file does not exist at the specified path. This is used during UploadedFile construction when the file path is invalid, and when attempting to read content from an invalid uploaded file.
Usage contexts:
Sources: src/UploadedFile.php61-62 src/UploadedFile.php330
The following diagram illustrates when exceptions are thrown during the file upload lifecycle.
Sources: src/UploadedFile.php50-73 src/UploadedFile.php364-403 src/UploadedFile.php327-334 src/UploadedFile.php350-357
The UploadedFile class provides formatted error messages through the getErrorMessage() method. This method uses the error code to look up the appropriate message template and formats it with relevant details.
Key implementation details:
| Method | Purpose | File Location |
|---|---|---|
getErrorMessage() | Generates formatted error message based on error code | src/UploadedFile.php493-501 |
getMaxFilesize() | Calculates maximum allowed file size from php.ini | src/UploadedFile.php410-416 |
parseFilesize() | Parses php.ini size strings (e.g., "8M", "2G") | src/UploadedFile.php444-476 |
Example error message for UPLOAD_ERR_INI_SIZE:
Sources: src/UploadedFile.php493-501 src/UploadedFile.php410-416 src/UploadedFile.php444-476
The typical pattern for handling file upload exceptions involves catching specific exceptions to provide appropriate user feedback:
Recommended HTTP status codes by exception:
| Exception | Recommended Status | Rationale |
|---|---|---|
IniSizeFileException | 413 (Payload Too Large) | File exceeds server limits |
FormSizeFileException | 413 (Payload Too Large) | File exceeds form-specified limits |
PartialFileException | 400 (Bad Request) | Incomplete upload (client issue) |
NoFileException | 400 (Bad Request) | Missing required file |
CannotWriteFileException | 500 (Internal Server Error) | Server filesystem issue |
NoTmpDirFileException | 500 (Internal Server Error) | Server configuration issue |
ExtensionFileException | 500 (Internal Server Error) | Server extension interference |
FileNotFoundException | 404 (Not Found) | File does not exist |
FileException | 500 (Internal Server Error) | Generic file operation failure |
Sources: src/UploadedFile.php385-402
When testing file uploads, the File class (see Testing) sets the test flag to true, which affects validation behavior. The isValid() method checks this flag to determine whether to use real PHP upload validation or simple error code checking.
Sources: src/UploadedFile.php272-277 src/Testing/File.php1-116
Refresh this wiki