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