krz/vox-populi

  1<?php
  2
  3namespace 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 */
 13interface 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     * @return StreamInterface Stream representation of the uploaded file.
 28     * @throws \RuntimeException in cases when no stream is available or can be
 29     *     created.
 30     */
 31    public function getStream();
 32
 33    /**
 34     * Move the uploaded file to a new location.
 35     *
 36     * Use this method as an alternative to move_uploaded_file(). This method is
 37     * guaranteed to work in both SAPI and non-SAPI environments.
 38     * Implementations must determine which environment they are in, and use the
 39     * appropriate method (move_uploaded_file(), rename(), or a stream
 40     * operation) to perform the operation.
 41     *
 42     * $targetPath may be an absolute path, or a relative path. If it is a
 43     * relative path, resolution should be the same as used by PHP's rename()
 44     * function.
 45     *
 46     * The original file or stream MUST be removed on completion.
 47     *
 48     * If this method is called more than once, any subsequent calls MUST raise
 49     * an exception.
 50     *
 51     * When used in an SAPI environment where $_FILES is populated, when writing
 52     * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
 53     * used to ensure permissions and upload status are verified correctly.
 54     *
 55     * If you wish to move to a stream, use getStream(), as SAPI operations
 56     * cannot guarantee writing to stream destinations.
 57     *
 58     * @see http://php.net/is_uploaded_file
 59     * @see http://php.net/move_uploaded_file
 60     * @param string $targetPath Path to which to move the uploaded file.
 61     * @throws \InvalidArgumentException if the $targetPath specified is invalid.
 62     * @throws \RuntimeException on any error during the move operation, or on
 63     *     the second or subsequent call to the method.
 64     */
 65    public function moveTo($targetPath);
 66    
 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    /**
 79     * Retrieve the error associated with the uploaded file.
 80     *
 81     * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
 82     *
 83     * If the file was uploaded successfully, this method MUST return
 84     * UPLOAD_ERR_OK.
 85     *
 86     * Implementations SHOULD return the value stored in the "error" key of
 87     * the file in the $_FILES array.
 88     *
 89     * @see http://php.net/manual/en/features.file-upload.errors.php
 90     * @return int One of PHP's UPLOAD_ERR_XXX constants.
 91     */
 92    public function getError();
 93    
 94    /**
 95     * Retrieve the filename sent by the client.
 96     *
 97     * Do not trust the value returned by this method. A client could send
 98     * a malicious filename with the intention to corrupt or hack your
 99     * application.
100     *
101     * Implementations SHOULD return the value stored in the "name" key of
102     * the file in the $_FILES array.
103     *
104     * @return string|null The filename sent by the client or null if none
105     *     was provided.
106     */
107    public function getClientFilename();
108    
109    /**
110     * Retrieve the media type sent by the client.
111     *
112     * Do not trust the value returned by this method. A client could send
113     * a malicious media type with the intention to corrupt or hack your
114     * application.
115     *
116     * Implementations SHOULD return the value stored in the "type" key of
117     * the file in the $_FILES array.
118     *
119     * @return string|null The media type sent by the client or null if none
120     *     was provided.
121     */
122    public function getClientMediaType();
123}