[FEATURE] Introduce Request/Response based on PSR-7
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Classes / Http / UploadedFile.php
1 <?php
2 namespace TYPO3\CMS\Core\Http;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use Psr\Http\Message\StreamInterface;
18 use Psr\Http\Message\UploadedFileInterface;
19 use TYPO3\CMS\Core\Utility\GeneralUtility;
20
21 /**
22 * Class UploadedFile which represents one uploaded file, usually coming
23 * from $_FILES, according to PSR-7 standard.
24 *
25 * Highly inspired by https://github.com/phly/http/
26 *
27 * @internal Note that this is not public API yet.
28 */
29 class UploadedFile implements UploadedFileInterface {
30
31 /**
32 * @var NULL|string
33 */
34 protected $file;
35
36 /**
37 * @var NULL|StreamInterface
38 */
39 protected $stream;
40
41 /**
42 * @var string
43 */
44 protected $clientFilename;
45
46 /**
47 * @var string
48 */
49 protected $clientMediaType;
50
51 /**
52 * @var int
53 */
54 protected $error;
55
56 /**
57 * @var bool
58 */
59 protected $moved = false;
60
61 /**
62 * @var int
63 */
64 protected $size;
65
66 /**
67 * Constructor method
68 *
69 * @param string|resource $input is either a stream or a filename
70 * @param int $size see $_FILES['size'] from PHP
71 * @param int $errorStatus see $_FILES['error']
72 * @param string $clientFilename the original filename handed over from the client
73 * @param string $clientMediaType the media type (optional)
74 *
75 * @throws \InvalidArgumentException
76 */
77 public function __construct($input, $size, $errorStatus, $clientFilename = NULL, $clientMediaType = NULL) {
78
79 if (is_string($input)) {
80 $this->file = $input;
81 }
82
83 if (is_resource($input)) {
84 $this->stream = new Stream($input);
85 } elseif ($input instanceof StreamInterface) {
86 $this->stream = $input;
87 }
88
89 if (!$this->file && !$this->stream) {
90 throw new \InvalidArgumentException('The input given was not a valid stream or file.', 1436717301);
91 }
92
93 if (!is_int($size)) {
94 throw new \InvalidArgumentException('The size provided for an uploaded file must be an integer.', 1436717302);
95 }
96 $this->size = $size;
97
98 if (!is_int($errorStatus) || 0 > $errorStatus || 8 < $errorStatus) {
99 throw new \InvalidArgumentException('Invalid error status for an uploaded file. See UPLOAD_ERR_* constant in PHP.', 1436717303);
100 }
101 $this->error = $errorStatus;
102
103 if ($clientFilename !== NULL && !is_string($clientFilename)) {
104 throw new \InvalidArgumentException('Invalid client filename provided for an uploaded file.', 1436717304);
105 }
106 $this->clientFilename = $clientFilename;
107
108 if ($clientMediaType !== NULL && !is_string($clientMediaType)) {
109 throw new \InvalidArgumentException('Invalid client media type provided for an uploaded file.', 1436717305);
110 }
111 $this->clientMediaType = $clientMediaType;
112 }
113
114 /**
115 * Retrieve a stream representing the uploaded file.
116 * Returns a StreamInterface instance, representing the uploaded file. The purpose of this method
117 * is to allow utilizing native PHP stream functionality to manipulate the file upload, such as
118 * stream_copy_to_stream() (though the result will need to be decorated in a native PHP stream wrapper
119 * to work with such functions).
120 *
121 * If the moveTo() method has been called previously, this method raises an exception.
122 *
123 * @return StreamInterface Stream representation of the uploaded file.
124 * @throws \RuntimeException in cases when no stream is available or can be created.
125 */
126 public function getStream() {
127 if ($this->moved) {
128 throw new \RuntimeException('Cannot retrieve stream as it was moved.', 1436717306);
129 }
130
131 if ($this->stream instanceof StreamInterface) {
132 return $this->stream;
133 }
134
135 $this->stream = new Stream($this->file);
136 return $this->stream;
137 }
138
139 /**
140 * Move the uploaded file to a new location.
141 *
142 * Use this method as an alternative to move_uploaded_file(). This method is
143 * guaranteed to work in both SAPI and non-SAPI environments.
144 * Implementations must determine which environment they are in, and use the
145 * appropriate method (move_uploaded_file(), rename(), or a stream
146 * operation) to perform the operation.
147 *
148 * $targetPath may be an absolute path, or a relative path. If it is a
149 * relative path, resolution should be the same as used by PHP's rename()
150 * function.
151 *
152 * The original file or stream MUST be removed on completion.
153 *
154 * If this method is called more than once, any subsequent calls MUST raise
155 * an exception.
156 *
157 * When used in an SAPI environment where $_FILES is populated, when writing
158 * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
159 * used to ensure permissions and upload status are verified correctly.
160 *
161 * If you wish to move to a stream, use getStream(), as SAPI operations
162 * cannot guarantee writing to stream destinations.
163 *
164 * @see http://php.net/is_uploaded_file
165 * @see http://php.net/move_uploaded_file
166 * @param string $targetPath Path to which to move the uploaded file.
167 * @throws \InvalidArgumentException if the $path specified is invalid.
168 * @throws \RuntimeException on any error during the move operation, or on the second or subsequent call to the method.
169 */
170 public function moveTo($targetPath) {
171 if (!is_string($targetPath) || empty($targetPath)) {
172 throw new \InvalidArgumentException('Invalid path while moving an uploaded file.', 1436717307);
173 }
174
175 if ($this->moved) {
176 throw new \RuntimeException('Cannot move uploaded file, as it was already moved.', 1436717308);
177 }
178
179 // Check if the target path is inside the allowed paths of TYPO3, and make it absolute.
180 $targetPath = GeneralUtility::getFileAbsFileName($targetPath);
181 if (empty($targetPath)) {
182 throw new \RuntimeException('Cannot move uploaded file, as it was already moved.', 1436717309);
183 }
184
185 if (!empty($this->file) && is_uploaded_file($this->file)) {
186 if (GeneralUtility::upload_copy_move($this->file, $targetPath . basename($this->file)) === FALSE) {
187 throw new \RuntimeException('An error occurred while moving uploaded file', 1436717310);
188 }
189 } elseif ($this->stream) {
190 $handle = fopen($targetPath, 'wb+');
191 if ($handle === FALSE) {
192 throw new \RuntimeException('Unable to write to target path.', 1436717311);
193 }
194
195 $this->stream->rewind();
196 while (!$this->stream->eof()) {
197 fwrite($handle, $this->stream->read(4096));
198 }
199
200 fclose($handle);
201 }
202
203 $this->moved = TRUE;
204 }
205
206 /**
207 * Retrieve the file size.
208 * Usually returns the value stored in the "size" key of
209 * the file in the $_FILES array if available, as PHP calculates this based
210 * on the actual size transmitted.
211 *
212 * @return int|NULL The file size in bytes or null if unknown.
213 */
214 public function getSize() {
215 return $this->size;
216 }
217
218 /**
219 * Retrieve the error associated with the uploaded file.
220 * Usually returns the value stored in the "error" key of
221 * the file in the $_FILES array.
222 *
223 * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
224 *
225 * If the file was uploaded successfully, this method MUST return
226 * UPLOAD_ERR_OK.
227 *
228 * @see http://php.net/manual/en/features.file-upload.errors.php
229 * @return int One of PHP's UPLOAD_ERR_XXX constants.
230 */
231 public function getError() {
232 return $this->error;
233 }
234
235 /**
236 * Retrieve the filename sent by the client.
237 * Usually returns the value stored in the "name" key of
238 * the file in the $_FILES array.
239 *
240 * Do not trust the value returned by this method. A client could send
241 * a malicious filename with the intention to corrupt or hack your
242 * application.
243 *
244 * @return string|NULL The filename sent by the client or null if none was provided.
245 */
246 public function getClientFilename() {
247 return $this->clientFilename;
248 }
249
250 /**
251 * Retrieve the media type sent by the client.
252 * Usually returns the value stored in the "type" key of
253 * the file in the $_FILES array.
254 *
255 * Do not trust the value returned by this method. A client could send
256 * a malicious media type with the intention to corrupt or hack your
257 * application.
258 *
259 * @return string|NULL The media type sent by the client or null if none was provided.
260 */
261 public function getClientMediaType() {
262 return $this->clientMediaType;
263 }
264
265 }