1: <?php
  2: 
  3: namespace Psr\Http\Message;
  4: 
  5: /**
  6:  * Value object representing a file uploaded through an HTTP request.
  7:  *
  8:  * Instances of this interface are considered immutable; all methods that
  9:  * might change state MUST be implemented such that they retain the internal
 10:  * state of the current instance and return an instance that contains the
 11:  * changed state.
 12:  */
 13: interface UploadedFileInterface
 14: {
 15:     /**
 16:      * Retrieve a stream representing the uploaded file.
 17:      *
 18:      * This method MUST return a StreamInterface instance, representing the
 19:      * uploaded file. The purpose of this method is to allow utilizing native PHP
 20:      * stream functionality to manipulate the file upload, such as
 21:      * stream_copy_to_stream() (though the result will need to be decorated in a
 22:      * native PHP stream wrapper to work with such functions).
 23:      *
 24:      * If the moveTo() method has been called previously, this method MUST raise
 25:      * an exception.
 26:      *
 27:      *     created.
 28:      *
 29:      * @throws \RuntimeException in cases when no stream is available or can be
 30:      *
 31:      * @return StreamInterface stream representation of the uploaded file
 32:      */
 33:     public function getStream();
 34: 
 35:     /**
 36:      * Move the uploaded file to a new location.
 37:      *
 38:      * Use this method as an alternative to move_uploaded_file(). This method is
 39:      * guaranteed to work in both SAPI and non-SAPI environments.
 40:      * Implementations must determine which environment they are in, and use the
 41:      * appropriate method (move_uploaded_file(), rename(), or a stream
 42:      * operation) to perform the operation.
 43:      *
 44:      * $targetPath may be an absolute path, or a relative path. If it is a
 45:      * relative path, resolution should be the same as used by PHP's rename()
 46:      * function.
 47:      *
 48:      * The original file or stream MUST be removed on completion.
 49:      *
 50:      * If this method is called more than once, any subsequent calls MUST raise
 51:      * an exception.
 52:      *
 53:      * When used in an SAPI environment where $_FILES is populated, when writing
 54:      * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
 55:      * used to ensure permissions and upload status are verified correctly.
 56:      *
 57:      * If you wish to move to a stream, use getStream(), as SAPI operations
 58:      * cannot guarantee writing to stream destinations.
 59:      *
 60:      *     the second or subsequent call to the method.
 61:      *
 62:      * @see http://php.net/is_uploaded_file
 63:      * @see http://php.net/move_uploaded_file
 64:      *
 65:      * @param string $targetPath path to which to move the uploaded file
 66:      *
 67:      * @throws \InvalidArgumentException if the $path specified is invalid
 68:      * @throws \RuntimeException         on any error during the move operation, or on
 69:      */
 70:     public function moveTo($targetPath);
 71: 
 72:     /**
 73:      * Retrieve the file size.
 74:      *
 75:      * Implementations SHOULD return the value stored in the "size" key of
 76:      * the file in the $_FILES array if available, as PHP calculates this based
 77:      * on the actual size transmitted.
 78:      *
 79:      * @return int|null the file size in bytes or null if unknown
 80:      */
 81:     public function getSize();
 82: 
 83:     /**
 84:      * Retrieve the error associated with the uploaded file.
 85:      *
 86:      * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
 87:      *
 88:      * If the file was uploaded successfully, this method MUST return
 89:      * UPLOAD_ERR_OK.
 90:      *
 91:      * Implementations SHOULD return the value stored in the "error" key of
 92:      * the file in the $_FILES array.
 93:      *
 94:      * @see http://php.net/manual/en/features.file-upload.errors.php
 95:      *
 96:      * @return int one of PHP's UPLOAD_ERR_XXX constants
 97:      */
 98:     public function getError();
 99: 
100:     /**
101:      * Retrieve the filename sent by the client.
102:      *
103:      * Do not trust the value returned by this method. A client could send
104:      * a malicious filename with the intention to corrupt or hack your
105:      * application.
106:      *
107:      * Implementations SHOULD return the value stored in the "name" key of
108:      * the file in the $_FILES array.
109:      *
110:      *     was provided.
111:      *
112:      * @return string|null The filename sent by the client or null if none
113:      */
114:     public function getClientFilename();
115: 
116:     /**
117:      * Retrieve the media type sent by the client.
118:      *
119:      * Do not trust the value returned by this method. A client could send
120:      * a malicious media type with the intention to corrupt or hack your
121:      * application.
122:      *
123:      * Implementations SHOULD return the value stored in the "type" key of
124:      * the file in the $_FILES array.
125:      *
126:      *     was provided.
127:      *
128:      * @return string|null The media type sent by the client or null if none
129:      */
130:     public function getClientMediaType();
131: }
132: