Download the PHP package tobento/service-upload without Composer

Upload Service

The Upload Service provides a secure and flexible foundation for handling uploaded files in PHP applications.
It offers tools for validating incoming files, creating PSR-7 UploadedFileInterface instances from various sources, writing files to storage, processing images, and safely copying existing files within a storage system.

The service is designed to be framework-agnostic, fully PSR-compliant, and easy to extend with custom validators, writers, or processing logic.

Key Capabilities

• Upload Validators: Validate uploaded files with specialized rules for general files, CSV, NDJSON, PDFs, ZIP archives, and more.
• Uploaded File Factory: Create PSR-7 UploadedFileInterface instances from remote URLs or storage files.
• File Writer: Safely write uploaded files or streams to any supported file storage.
• Copy Mode: Duplicate existing storage files without re-uploading or re-processing.
• Image Processor: Apply Imager actions such as resizing, orienting, or converting images.
• Flexibility: Works with any PSR-7 StreamInterface implementation (Nyholm, Guzzle, Laminas, Slim, etc.).
• Extensibility: Easily integrate custom validators, writers, or image actions.

Table of Contents

• Getting started
  • Requirements
• Documentation
  • Upload Validators
    • General Validator
    • CSV Validator
    • NDJSON Validator
    • PDF Validator
    • SVG Validator
    • ZIP Validator
    • Combine Validator
  • Uploaded File Factory
  • File Storage Writer
  • Writers
    • Image Writer
    • SVG Sanitizer Writer
  • Copy Mode (CopyFileWrapper)
  • Image Processor
• Credits

  ---

Getting started

Add the latest version of the upload project running this command.

Requirements

• PHP 8.4 or above

Documentation

Upload Validators

Upload validators provide a secure and consistent way to inspect incoming files before processing them.
Each validator operates on a PSR-7 UploadedFileInterface instance and applies a focused set of rules to ensure the file is safe, well-formed, and matches your application's expectations.
Validators can be used individually or combined to support multiple file types with minimal effort.

General Validator

The general validator validates a given uploaded file against a set of configurable security and consistency rules.

validateUploadedFile

Use the method to validate the given uploaded file:

Security

The validator ensures that:

• the file extension is allowed
• the mime type detected from the file's content is allowed
• the client filename extension is consistent with the file's content
• the client media type is consistent with the detected mime type
  (only if validateClientMediaType is enabled)
• the filename contains only alphanumeric characters, hyphens, underscores, spaces, and periods
  (if strictFilenameCharacters is true)
• the filename length does not exceed the configured maxFilenameLength
• the file size does not exceed the configured maxFileSizeInKb
  (default: null = unlimited)

Once the uploaded file is validated and accepted, you can rely on:

• $uploadedFile->getClientMediaType() being allowed and consistent with the file content
  (if strict client media type validation is enabled)
• $uploadedFile->getClientFilename() having a valid and consistent extension

The only remaining responsibility is verifying the filename itself, excluding the extension:

If you use the File Storage Writer to store files, ensure the parameter is configured safely.

File Storage Location

Always store uploaded files outside the webroot or on a separate host.
If you use the File Storage Writer, ensure the configured storage location is outside the webroot - such as the default or storage.

Resources

For further guidance on secure file uploads, refer to:
File Upload Cheatsheet - owasp.org.

CSV Validator

The CSV validator extends the general validator with additional CSV-specific security checks.
It ensures that uploaded CSV files are structurally valid, safe to process, and free from spreadsheet-formula injection.

CSV-Specific Security

The CSV validator ensures:

• the file extension is csv
• the detected mime type is one of the allowed CSV mime types: text/csv, text/plain, application/csv, application/vnd.ms-excel
• the CSV can be parsed line-by-line
• all rows have a consistent number of columns
• no cell begins with =, +, -, or @ (prevents spreadsheet formula injection)
• UTF-8 BOM is handled correctly
• empty lines are ignored safely

NDJSON Validator

The NDJSON validator extends the general validator with line-by-line JSON validation.
It ensures that uploaded NDJSON files contain one valid JSON object per line, ignore empty lines, and safely reject malformed entries.

PDF Validator

The PDF validator extends the general validator with additional PDF-specific security checks.
It ensures that uploaded PDF files are structurally safe by detecting features commonly used for malicious behavior, such as JavaScript, embedded files, encryption, and auto-execution actions.

SVG Validator

The SVG validator extends the general validator with additional SVG-specific security checks.
It ensures that uploaded SVG files are structurally safe by validating XML integrity and detecting features commonly associated with malicious behavior.

Unlike formats such as PDF, SVGs are XML-based and can contain embedded scripts or external references. This validator uses the excellent enshrined/svg-sanitize library to sanitize and inspect SVG content safely.

Requirements

To enable this validator, install:

Example

Note: If you only need to sanitize SVG files before saving them, consider using the SVG Sanitizer Writer. The SVG validator is still recommended when you want to validate uploads and reject malformed or unsafe SVGs early.

ZIP Validator

The ZIP validator extends the general validator with archive-specific security checks.
It ensures that uploaded ZIP files are safe to extract, structurally valid, and free from common archive-based attack vectors such as ZIP bombs, directory traversal, and excessive nesting.

ZIP-Specific Security Features

The ZipValidator performs several safety checks to ensure uploaded archives are safe to process:

• Maximum entry count
  Prevents ZIP files containing thousands of entries, which can overwhelm extraction routines.

• Maximum total uncompressed size
  Protects against ZIP bombs that expand to massive sizes when extracted.

• Maximum compression ratio
  Detects malicious archives with extreme compression ratios.

• Directory traversal protection
  Blocks unsafe paths such as:

• Nested ZIP depth
  Controls how many layers of ZIP-within-ZIP are allowed. Useful for preventing recursive archive bombs.

• In-memory nested ZIP validation
  Nested ZIPs are validated using an internal in‑memory uploaded file implementation, without writing to disk.

Upload Combine Validator

The combine validator allows you to register multiple validators and automatically dispatches validation to the first validator that supports the file's extension.

This is ideal when your application accepts multiple file types, each with its own specialized validator.

Uploaded File Factory

The uploaded file factory creates PSR-7 UploadedFileInterface instances from different resources such as remote URLs or storage files.

createFromRemoteUrl

Creates an uploaded file by downloading the content from a remote URL using a PSR-18 HTTP client.

If the remote request fails or the response status code is not 200, a CreateUploadedFileException is thrown.

createFromStorageFile

Creates an uploaded file from a Storage File.

This feature is optional. To use it, install the file-storage package:

If the storage file does not provide a stream, a CreateUploadedFileException is thrown.

File Storage Writer

The file storage writer writes the given file to the defined File Storage.
Before writing, you may use upload validators to ensure the file meets your requirements (e.g., type, size, or structure).
Writers can also be used to sanitize or process files before they are stored, allowing you to modify or transform the file content as needed.

Requirements

This feature is optional. To enable the file writer, install:

Example

Check out the Available Writers section for details on each writer and their requirements.

writeFromStream

Use the method to write the given stream to the file storage:

writeUploadedFile

Use the method to write the given uploaded file to the file storage:

It is highly recommended to use the Upload Validator before writing the uploaded file to the file storage.

copyFile

Use the copyFile method to copy an existing file inside the same file storage to a new folder. This is useful when selecting files from a file manager or when you want to duplicate files without re-uploading or re-processing them.
This method does not run any writers.

This method performs a storage-level copy (e.g. local to local, S3 to S3) without reading streams or applying any image processing. It is ideal for file-manager selections or fast, lossless duplication.

writeResponse

Writers

Writers are responsible for sanitizing, processing, or transforming files before they are stored. They can modify file contents, optimize images, sanitize SVGs, or perform other processing tasks depending on the writer implementation.

Writers are typically used by the File Storage Writer, which selects the appropriate writer based on the file type before writing the file to storage.
However, writers may also be used as standalone components when you need to process files independently of the storage workflow.

Image Writer

The Image Writer applies image transformations such as orientation correction, resizing, or any other actions supported by the underlying Image Processor.

Requirements

To enable this writer, install:

Example

SVG Sanitizer Writer

The SVG Sanitizer Writer handles .svg files by sanitizing their XML markup using a dedicated SVG sanitizing library.
This helps prevent security issues such as embedded scripts or malicious attributes, making SVG uploads safer for display in browsers.

Requirements

To enable this writer, install:

Example

Copy Mode (CopyFileWrapper)

Copy mode can be used when you want to copy an existing file inside the same file storage instead of uploading a new one.
A CopyFileWrapper contains:

• the original UploadedFileInterface (metadata only)
• the storage name where the file currently exists
• the path of the file inside that storage

Image Processor

The image processor applies the configured Imager actions to an image stream or resource, using the underlying Imager Service.

You can find all available Imager actions in the Imager Actions documentation.

processFromResource

Use the method to process the given resource:

Check out the Resource and Encoded documentation to learn more.

processFromStream

Use the method to process the given stream:

Check out the Encoded documentation to learn more.

Credits

• Tobias Strub
• All Contributors