HTTP Uploaded File (PSR-7)

Overview

Phalcon\Http\Message\UploadedFile is an implementation of the PSR-7 HTTP messaging interface as defined by PHP-FIG.

The Phalcon\Http\Message\UploadedFile is a value object class that stores information for the uploaded files to your application. making it easier to work with. There are several limitations when using just the $_FILES superglobal, which the Phalcon\Http\Message\UploadedFile resolves. The Phalcon\Http\Message\ServerRequest object allows you to retrieve all the uploaded files in a normalized structure, which each leaf is a Phalcon\Http\Message\UploadedFile object.

<?php
use Phalcon\Http\Message\UploadedFile;
$file = new UploadedFile(
    'php://memory',
    0,
    UPLOAD_ERR_OK,
    'phalcon.txt'
);
echo $file->getClientFilename(); // 'phalcon.txt'

We are creating a new Phalcon\Http\Message\UploadedFile using the memory stream, with size 0, specifying that there was no upload error (UOLOAD_ERR_OK) and the name of the file is phalcon.txt. This information is available to us when working with the Phalcon\Http\Message\ServerRequest object automatically.

Constructor

public function __construct(
    StreamInterface | string | null $stream 
    [, int $size = null 
    [, int error = 0
    [, string clientFilename = null
    [, string clientMediaType = null ]]]] 
)

The constructor accepts parameters allowing you to create the object with certain properties populated. You can define the stream, the size of the file, if any error occurred during the upload, the client file name as well as the client media type.

• stream - A valid stream for the file (StreamInterface, string)
• size - The size of the file
• error - An upload error (see the UPLOADERR*PHP constants)
• clientFilename - The name of the uploaded file from the client
• clientMediaType - The media type of the uploaded file from the client

Getters

getClientFilename()

Returns the filename sent by the client. You should not trust the value returned by this method. The client could very well send a malicious filename with the intent to corrupt or hack your application. The value returned is the value stored in the name key in the $_FILES array.

<?php
use Phalcon\Http\Message\UploadedFile;
$file = new UploadedFile(
    'php://memory',
    0,
    UPLOAD_ERR_OK,
    'phalcon.txt'
);
echo $file->getClientFilename(); // 'phalcon.txt'

getClientMediaType()

Returns the media type sent by the client. You should not trust the value returned by this method. The client could very well send a malicious filename with the intent to corrupt or hack your application. The value returned is the value stored in the type key in the $_FILES array.

<?php
use Phalcon\Http\Message\UploadedFile;
$file = new UploadedFile(
    'php://memory',
    0,
    UPLOAD_ERR_OK,
    'phalcon.txt',
    'application/text'
);
echo $file->getClientMediaType(); // 'application/text'

getError()

Returns the error associated with the uploaded file. The value is PHP’s UPLOADERR* constants. If the file was uploaded successfully, the method will return UPLOAD_ERR_OK. The value returned is the value stored in the error key in the $_FILES array.

<?php
use Phalcon\Http\Message\UploadedFile;
$file = new UploadedFile(
    'php://memory',
    0,
    UPLOAD_ERR_OK,
    'phalcon.txt',
    'application/text'
);
echo $file->getError(); // UPLOAD_ERR_OK

getSize()

Returns the size of the uploaded file. The value returned is the value stored in the size key in the $_FILES array if available.

<?php
use Phalcon\Http\Message\UploadedFile;
$file = new UploadedFile(
    'php://memory',
    1234,
    UPLOAD_ERR_OK,
    'phalcon.txt'
);
echo $file->getSize(); // 1234

getStream()

Returns the stream representing the uploaded file. The method returns a StreamInterface instance. The purpose of this method is to allow utilizing native PHP stream functionality to manipulate the file upload, such as stream_copy_to_stream() (though the result will need to be decorated in a native PHP stream wrapper to work with such functions).

If the moveTo() method has been called previously, a Phalcon\Http\Message\Exception\InvalidArgumentException exception will be thrown.

<?php
use Phalcon\Http\Message\Stream;
use Phalcon\Http\Message\UploadedFile;
$fileName = dataFolder('/assets/stream/mit.txt');
$stream   = new Stream($fileName, 'rb');
$file = new UploadedFile(
    $stream,
    1234,
    UPLOAD_ERR_OK,
    'phalcon.txt'
);
echo $file->getStream(); // '/assets/stream/mit.txt'

moveTo()

Moves the uploaded file to a new location. This method should be used as an alternative to move_uploaded_file(). This method is guaranteed to work in both SAPI and non-SAPI environments.

The parameter $targetPath can be an absolute or relative path. When calling this method, the original file or stream will be removed. As noted above, if this method is called more than once, any subsequent calls will raise a Phalcon\Http\Message\Exception\InvalidArgumentException exception.

The method performs necessary checks internally so that permissions are properly maintained. If you need to to move the file to a stream, you will need to use getStream(), since SAPI operations cannot guarantee writing stream destinations.

<?php
use Phalcon\Http\Message\Stream;
use Phalcon\Http\Message\UploadedFile;
$fileName = dataFolder('/assets/stream/mit.txt');
$stream   = new Stream($fileName, 'rb');
$file = new UploadedFile(
    $stream,
    1234,
    UPLOAD_ERR_OK,
    'phalcon.txt'
);
$file->moveTo('/storage/files/');