Oihana PHP

UploadTrait

Provides helpers to receive PSR-7 file uploads, validate them and store them on disk.

Both helpers delegate the per-file work (error/size/MIME checks, name sanitization, move) to the shared self::storeUploadedFile() method and throw a FileException on any failure, leaving the response shaping to the controller.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Methods

receiveUpload()  : string
Receives a single uploaded file for the given field, validates it and stores it.
receiveUploads()  : array<string|int, string>
Receives multiple uploaded files for the given field, validates them and stores them.
storeUploadedFile()  : string
Validates a single uploaded file and moves it into the destination directory.
uploadErrorMessage()  : string
Maps a PHP `UPLOAD_ERR_*` code to a human-readable message.

Methods

receiveUpload()

Receives a single uploaded file for the given field, validates it and stores it.

public receiveUpload(ServerRequestInterface $request, string $field, string $destDir[, array<string|int, mixed> $options = [] ]) : string
Parameters
$request : ServerRequestInterface

The PSR-7 request carrying the uploaded files.

$field : string

The uploaded-file field name.

$destDir : string

The destination directory.

$options : array<string|int, mixed> = []

Optional switches (see UploadOption).

Tags
throws
FileException

If the field is missing, the upload failed, the size/MIME checks fail, or the destination is invalid.

example 
class AvatarController extends Controller
{
    use UploadTrait ;

    public function upload( Request $request , Response $response ) : Response
    {
        $path = $this->receiveUpload( $request , 'avatar' , '/var/uploads' , [
            UploadOption::MAX_SIZE           => 2_000_000 ,
            UploadOption::ALLOWED_MIME_TYPES => [ 'image/png' , 'image/jpeg' ] ,
        ] ) ;

        return $this->success( $request , $response , [ 'path' => $path ] ) ;
    }
}
Return values
string —

The absolute path of the stored file.

receiveUploads()

Receives multiple uploaded files for the given field, validates them and stores them.

public receiveUploads(ServerRequestInterface $request, string $field, string $destDir[, array<string|int, mixed> $options = [] ]) : array<string|int, string>

The UploadOption::FILENAME option is ignored here: each file keeps its own sanitized client name to avoid collisions.

Parameters
$request : ServerRequestInterface

The PSR-7 request carrying the uploaded files.

$field : string

The uploaded-file field name (an array of files).

$destDir : string

The destination directory.

$options : array<string|int, mixed> = []

Optional switches (see UploadOption).

Tags
throws
FileException

If the field is missing/not a list, an upload failed, the size/MIME checks fail, or the destination is invalid.

Return values
array<string|int, string> —

The absolute paths of the stored files.

storeUploadedFile()

Validates a single uploaded file and moves it into the destination directory.

private storeUploadedFile(UploadedFileInterface $uploaded, string $destDir[, array<string|int, mixed> $options = [] ]) : string
Parameters
$uploaded : UploadedFileInterface

The uploaded file.

$destDir : string

The destination directory.

$options : array<string|int, mixed> = []

Optional switches (see UploadOption).

Tags
throws
FileException

On any validation or destination error.

Return values
string —

The absolute path of the stored file.

uploadErrorMessage()

Maps a PHP `UPLOAD_ERR_*` code to a human-readable message.

private uploadErrorMessage(int $error) : string
Parameters
$error : int

One of the UPLOAD_ERR_* constants.

Return values
string —

The associated message.

On this page

Search results