annotate vendor/psr/http-message/src/UploadedFileInterface.php @ 19:fa3358dc1485 tip

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