# Class HttpSoft\Message\UploadedFile

Abstraction for convenient management of uploaded files, implements Psr\Http\Message\UploadedFileInterface.

use HttpSoft\Message\Stream;
use HttpSoft\Message\UploadedFile;

$uploadedFile = new UploadedFile('file.txt', 1024, UPLOAD_ERR_OK);
$uploadedFile->getClientFilename(); // null
$uploadedFile->getClientMediaType(); // null
$uploadedFile->getError(); // 0
$uploadedFile->getSize(); // 1024

$uploadedFile = new UploadedFile('file.txt', 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');
$uploadedFile->getClientFilename(); // 'file.txt'
$uploadedFile->getClientMediaType(); // 'text/plain'
$uploadedFile->getError(); // 0
$uploadedFile->getSize(); // 1024

$uploadedFile->getStream()->getContents(); // Content
$uploadedFile->moveTo('new/path/to/file.txt');
file_get_contents('new/path/to/file.txt'); // Content

// Create from resource:
$resource = fopen('path/to/file', 'wb+');
$uploadedFile = new UploadedFile($resource, 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');

// Create from `StreamInterface` instance:
$stream = new Stream($resource);
$uploadedFile = new UploadedFile($stream, 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');

# Public methods

See the original detailed description of the methods in the Psr\Http\Message\UploadedFileInterface.

/**
 * @param StreamInterface|string|resource $streamOrFile
 * @param int $size
 * @param int $error
 * @param string|null $clientFilename
 * @param string|null $clientMediaType
 */
public function __construct(
    $streamOrFile,
    int $size,
    int $error,
    string $clientFilename = null,
    string $clientMediaType = null
);

# moveTo

Moves the uploaded file to a new location. It must only be called once.

/**
 * @param string $targetPath
 */
public function moveTo($targetPath): void;

This method is guaranteed to work in both SAPI and non-SAPI environments.

If invalid specified $targetPath, the \InvalidArgumentException exception will be thrown.

The \RuntimeException exception will be thrown on any error during the move operation, or on the second or subsequent call to the method.

use HttpSoft\Message\UploadedFile;

$uploadedFile = new UploadedFile('path/to/file.txt', 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');
$uploadedFile->getStream()->getMetadata('uri'); // 'path/to/file.txt'
$uploadedFile->moveTo('new/path/to/new.txt');
$uploadedFile->getSize(); // 1024
$uploadedFile->getError(); // 0
$uploadedFile->getClientFilename(); // 'file.txt'
$uploadedFile->getClientMediaType(); // 'text/plain'

$uploadedFile = new UploadedFile('path/to/file.txt', 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');
$uploadedFile->moveTo('target/path/directory/is/not/writeable'); // throws InvalidArgumentException
$uploadedFile->moveTo('target/path/does/not/exist'); // throws InvalidArgumentException

$uploadedFile = new UploadedFile('path/to/file.txt', 1024, UPLOAD_ERR_OK, 'file.txt', 'text/plain');
$uploadedFile->moveTo('new/path/to/new.txt'); // Ok
$uploadedFile->moveTo('new/path/to/new.txt'); // throws RuntimeException

# getStream

Returns stream instance representing the uploaded file. Must be called before calling the moveTo() method.

public function getStream(): StreamInterface;

Psr\Http\Message\StreamInterface methods are implemented in the HttpSoft\Message\StreamTrait.

The \RuntimeException exception will be thrown if the moveTo() method has been called previously or in cases when no stream is available or can be created.

# getSize

Returns the file size in bytes or null if unknown.

public function getSize(): ?int;

Similar to the size key of the file in the $_FILES a global array.

# getError

Returns the error associated with the uploaded file.

public function getError(): int;

Returns value of one of the PHP's UPLOAD_ERR_XXX constants.

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

Similar to the error key of the file in the $_FILES a global array.

# getClientFilename

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

public function getClientFilename(): ?string;

Similar to the name key of the file in the $_FILES a global array.

# getClientMediaType

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

public function getClientMediaType(): ?string;

Similar to the name key of the file in the $_FILES a global array.