CodeIgniter v4.5 API

UploadedFile extends File
in package

Application

implements UploadedFileInterface

Value object representing a single file uploaded through an HTTP request. Used by the IncomingRequest class to provide files.

Typically, implementors will extend the SplFileInfo class.

Interfaces

UploadedFileInterface: Value object representing a single file uploaded through an HTTP request. Used by the IncomingRequest class to provide files.

Properties

$clientPath : string: The webkit relative path of the file.
$error : int: The error constant of the upload (one of PHP's UPLOADERRXXX constants)
$hasMoved : bool: Whether the file has been moved already or not.
$name : string: The filename given to a file during a move.
$originalMimeType : string: The type of file as provided by PHP
$originalName : string: The original filename as provided by the client.
$path : string: The path to the temporary file.
$size : int: The files size in bytes

Methods

__construct() : mixed: Accepts the file information as would be filled in from the $_FILES array.
getClientExtension() : string: Returns the original file extension, based on the file name that was uploaded. This is NOT a trusted source.
getClientMimeType() : string: Returns the mime type as provided by the client.
getClientName() : string: Returns the name of the file as provided by the client during upload.
getClientPath() : string|null: (PHP 8.1+) Returns the webkit relative path of the uploaded file on directory uploads.
getDestination() : string: Returns the destination path for the move operation where overwriting is not expected.
getError() : int: Retrieve the error associated with the uploaded file.
getErrorString() : string: Get error string
getExtension() : string: Overrides SPLFileInfo's to work with uploaded files, since the temp file that's been uploaded doesn't have an extension.
getMimeType() : string: Retrieve the media type of the file. SHOULD not use information from the $_FILES array, but should use other methods to more accurately determine the type of file, like finfo, or mime_content_type().
getName() : string: Retrieve the filename. This will typically be the filename sent by the client, and should not be trusted. If the file has been moved, this will return the final name of the moved file.
getRandomName() : string: Generates a random names based on a simple hash and the time, with the correct file extension attached.
getSize() : false|int: Retrieve the file size.
getSizeByUnit() : false|int|string: Retrieve the file size by unit.
getTempName() : string: Gets the temporary filename where the file was uploaded to.
guessExtension() : string: Attempts to determine the best file extension from the file's mime type. In contrast to getExtension, this method will return an empty string if it fails to determine an extension instead of falling back to the unsecure clientExtension.
hasMoved() : bool: Returns whether the file has been moved or not. If it has, the move() method will not work and certain properties, like the tempName, will no longer be available.
isValid() : bool: Returns whether the file was uploaded successfully, based on whether it was uploaded via HTTP and has no errors.
move() : bool: Move the uploaded file to a new location.
store() : string: Save the uploaded file to a new location.
setPath() : string: create file target path if the set path does not exist

$clientPath

The webkit relative path of the file.


    protected
        string
    $clientPath

$error

The error constant of the upload (one of PHP's UPLOADERRXXX constants)


    protected
        int
    $error

$hasMoved

Whether the file has been moved already or not.


    protected
        bool
    $hasMoved
     = false

$name

The filename given to a file during a move.


    protected
        string
    $name

$originalMimeType

The type of file as provided by PHP


    protected
        string
    $originalMimeType

$originalName

The original filename as provided by the client.


    protected
        string
    $originalName

$path

The path to the temporary file.


    protected
        string
    $path

$size

The files size in bytes


    protected
        int
    $size

__construct()

Accepts the file information as would be filled in from the $_FILES array.


    public
                    __construct(string $path, string $originalName[, string|null $mimeType = null ][, int|null $size = null ][, int|null $error = null ][, string|null $clientPath = null ]) : mixed

Parameters

$path : string: The temporary location of the uploaded file.
$originalName : string: The client-provided filename.
$mimeType : string|null = null: The type of file as provided by PHP
$size : int|null = null: The size of the file, in bytes
$error : int|null = null: The error constant of the upload (one of PHP's UPLOADERRXXX constants)
$clientPath : string|null = null: The webkit relative path of the uploaded file.

getClientExtension()

Returns the original file extension, based on the file name that was uploaded. This is NOT a trusted source.


    public
                    getClientExtension() : string

For a trusted version, use guessExtension() instead.

Return values

string

getClientMimeType()

Returns the mime type as provided by the client.


    public
                    getClientMimeType() : string

This is NOT a trusted value. For a trusted version, use getMimeType() instead.

Return values

string —

The media type sent by the client or null if none was provided.

getClientName()

Returns the name of the file as provided by the client during upload.


    public
                    getClientName() : string

Return values

string

getClientPath()

(PHP 8.1+) Returns the webkit relative path of the uploaded file on directory uploads.


    public
                    getClientPath() : string|null

Return values

string|null

getDestination()

Returns the destination path for the move operation where overwriting is not expected.


    public
                    getDestination(string $destination[, string $delimiter = '_' ][, int $i = 0 ]) : string

First, it checks whether the delimiter is present in the filename, if it is, then it checks whether the last element is an integer as there may be cases that the delimiter may be present in the filename. For the all other cases, it appends an integer starting from zero before the file's extension.

Parameters

$destination : string
$delimiter : string = '_'
$i : int = 0

Return values

string

getError()

Retrieve the error associated with the uploaded file.


    public
                    getError() : int

The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.

If the file was uploaded successfully, this method MUST return UPLOAD_ERR_OK.

Implementations SHOULD return the value stored in the "error" key of the file in the $_FILES array.

Return values

int —

One of PHP's UPLOAD_ERR_XXX constants.

getErrorString()

Get error string


    public
                    getErrorString() : string

Return values

string

getExtension()

Overrides SPLFileInfo's to work with uploaded files, since the temp file that's been uploaded doesn't have an extension.


    public
                    getExtension() : string

This method tries to guess the extension from the files mime type but will return the clientExtension if it fails to do so.

This method will always return a more or less helpfull extension but might be insecure if the mime type is not matched. Consider using guessExtension for a more safe version.

Return values

string

getMimeType()

Retrieve the media type of the file. SHOULD not use information from the $_FILES array, but should use other methods to more accurately determine the type of file, like finfo, or mime_content_type().


    public
                    getMimeType() : string

Return values

string —

The media type we determined it to be.

getName()

Retrieve the filename. This will typically be the filename sent by the client, and should not be trusted. If the file has been moved, this will return the final name of the moved file.


    public
                    getName() : string

Return values

string —

The filename sent by the client or null if none was provided.

getRandomName()

Generates a random names based on a simple hash and the time, with the correct file extension attached.


    public
                    getRandomName() : string

Return values

string

getSize()

Retrieve the file size.


    public
                    getSize() : false|int

Implementations SHOULD return the value stored in the "size" key of the file in the $_FILES array if available, as PHP calculates this based on the actual size transmitted. A RuntimeException will be thrown if the file does not exist or an error occurs.

#[ReturnTypeWillChange]

Return values

false|int —

The file size in bytes, or false on failure

getSizeByUnit()

Retrieve the file size by unit.


    public
                    getSizeByUnit([string $unit = 'b' ]) : false|int|string

Parameters

$unit : string = 'b'

Return values

false|int|string

getTempName()

Gets the temporary filename where the file was uploaded to.


    public
                    getTempName() : string

Return values

string

guessExtension()

Attempts to determine the best file extension from the file's mime type. In contrast to getExtension, this method will return an empty string if it fails to determine an extension instead of falling back to the unsecure clientExtension.


    public
                    guessExtension() : string

Return values

string

hasMoved()

Returns whether the file has been moved or not. If it has, the move() method will not work and certain properties, like the tempName, will no longer be available.


    public
                    hasMoved() : bool

Return values

bool

isValid()

Returns whether the file was uploaded successfully, based on whether it was uploaded via HTTP and has no errors.


    public
                    isValid() : bool

Return values

bool

move()

Move the uploaded file to a new location.


    public
                    move(string $targetPath[, string|null $name = null ][, bool $overwrite = false ]) : bool

$targetPath may be an absolute path, or a relative path. If it is a relative path, resolution should be the same as used by PHP's rename() function.

The original file MUST be removed on completion.

If this method is called more than once, any subsequent calls MUST raise an exception.

When used in an SAPI environment where $_FILES is populated, when writing files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be used to ensure permissions and upload status are verified correctly.

If you wish to move to a stream, use getStream(), as SAPI operations cannot guarantee writing to stream destinations.

Parameters

$targetPath : string: Path to which to move the uploaded file.
$name : string|null = null: the name to rename the file to.
$overwrite : bool = false: State for indicating whether to overwrite the previously generated file with the same name or not.

Return values

bool

store()

Save the uploaded file to a new location.


    public
                    store([string|null $folderName = null ][, string|null $fileName = null ]) : string

By default, upload files are saved in writable/uploads directory. The YYYYMMDD folder and random file name will be created.

Parameters

$folderName : string|null = null: the folder name to writable/uploads directory.
$fileName : string|null = null: the name to rename the file to.

Return values

string —

file full path

setPath()

create file target path if the set path does not exist


    protected
                    setPath(string $path) : string

Parameters

$path : string

Return values

string —

The path set or created.

UploadedFile extends File in package Application implements UploadedFileInterface

Table of Contents

Interfaces

Properties

Methods

Properties

$clientPath

$error

$hasMoved

$name

$originalMimeType

$originalName

$path

$size

Methods

__construct()

Parameters

getClientExtension()

Return values

getClientMimeType()

Return values

getClientName()

Return values

getClientPath()

Return values

getDestination()

Parameters

Return values

getError()

Tags

Return values

getErrorString()

Return values

getExtension()

Return values

getMimeType()

Return values

getName()

Return values

getRandomName()

Return values

getSize()

Attributes

Return values

getSizeByUnit()

Parameters

Return values

getTempName()

Return values

guessExtension()

Return values

hasMoved()

Return values

isValid()

Return values

move()

Parameters

Tags

Return values

store()

Parameters

Return values

setPath()

Parameters

Return values

UploadedFile extends File
in package

Application

implements UploadedFileInterface