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}
124