File indexing completed on 2025-01-26 05:29:15
0001 <?php 0002 0003 namespace Psr\Http\Message; 0004 0005 /** 0006 * Value object representing a file uploaded through an HTTP request. 0007 * 0008 * Instances of this interface are considered immutable; all methods that 0009 * might change state MUST be implemented such that they retain the internal 0010 * state of the current instance and return an instance that contains the 0011 * changed state. 0012 */ 0013 interface UploadedFileInterface 0014 { 0015 /** 0016 * Retrieve a stream representing the uploaded file. 0017 * 0018 * This method MUST return a StreamInterface instance, representing the 0019 * uploaded file. The purpose of this method is to allow utilizing native PHP 0020 * stream functionality to manipulate the file upload, such as 0021 * stream_copy_to_stream() (though the result will need to be decorated in a 0022 * native PHP stream wrapper to work with such functions). 0023 * 0024 * If the moveTo() method has been called previously, this method MUST raise 0025 * an exception. 0026 * 0027 * @return StreamInterface Stream representation of the uploaded file. 0028 * @throws \RuntimeException in cases when no stream is available or can be 0029 * created. 0030 */ 0031 public function getStream(); 0032 0033 /** 0034 * Move the uploaded file to a new location. 0035 * 0036 * Use this method as an alternative to move_uploaded_file(). This method is 0037 * guaranteed to work in both SAPI and non-SAPI environments. 0038 * Implementations must determine which environment they are in, and use the 0039 * appropriate method (move_uploaded_file(), rename(), or a stream 0040 * operation) to perform the operation. 0041 * 0042 * $targetPath may be an absolute path, or a relative path. If it is a 0043 * relative path, resolution should be the same as used by PHP's rename() 0044 * function. 0045 * 0046 * The original file or stream MUST be removed on completion. 0047 * 0048 * If this method is called more than once, any subsequent calls MUST raise 0049 * an exception. 0050 * 0051 * When used in an SAPI environment where $_FILES is populated, when writing 0052 * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be 0053 * used to ensure permissions and upload status are verified correctly. 0054 * 0055 * If you wish to move to a stream, use getStream(), as SAPI operations 0056 * cannot guarantee writing to stream destinations. 0057 * 0058 * @see http://php.net/is_uploaded_file 0059 * @see http://php.net/move_uploaded_file 0060 * @param string $targetPath Path to which to move the uploaded file. 0061 * @throws \InvalidArgumentException if the $targetPath specified is invalid. 0062 * @throws \RuntimeException on any error during the move operation, or on 0063 * the second or subsequent call to the method. 0064 */ 0065 public function moveTo($targetPath); 0066 0067 /** 0068 * Retrieve the file size. 0069 * 0070 * Implementations SHOULD return the value stored in the "size" key of 0071 * the file in the $_FILES array if available, as PHP calculates this based 0072 * on the actual size transmitted. 0073 * 0074 * @return int|null The file size in bytes or null if unknown. 0075 */ 0076 public function getSize(); 0077 0078 /** 0079 * Retrieve the error associated with the uploaded file. 0080 * 0081 * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants. 0082 * 0083 * If the file was uploaded successfully, this method MUST return 0084 * UPLOAD_ERR_OK. 0085 * 0086 * Implementations SHOULD return the value stored in the "error" key of 0087 * the file in the $_FILES array. 0088 * 0089 * @see http://php.net/manual/en/features.file-upload.errors.php 0090 * @return int One of PHP's UPLOAD_ERR_XXX constants. 0091 */ 0092 public function getError(); 0093 0094 /** 0095 * Retrieve the filename sent by the client. 0096 * 0097 * Do not trust the value returned by this method. A client could send 0098 * a malicious filename with the intention to corrupt or hack your 0099 * application. 0100 * 0101 * Implementations SHOULD return the value stored in the "name" key of 0102 * the file in the $_FILES array. 0103 * 0104 * @return string|null The filename sent by the client or null if none 0105 * was provided. 0106 */ 0107 public function getClientFilename(); 0108 0109 /** 0110 * Retrieve the media type sent by the client. 0111 * 0112 * Do not trust the value returned by this method. A client could send 0113 * a malicious media type with the intention to corrupt or hack your 0114 * application. 0115 * 0116 * Implementations SHOULD return the value stored in the "type" key of 0117 * the file in the $_FILES array. 0118 * 0119 * @return string|null The media type sent by the client or null if none 0120 * was provided. 0121 */ 0122 public function getClientMediaType(); 0123 }