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