[CLEANUP] The correct case must be used for standard PHP types in phpdoc
[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 {
128 if ($this->moved) {
129 throw new \RuntimeException('Cannot retrieve stream as it was moved.', 1436717306);
130 }
131
132 if ($this->stream instanceof StreamInterface) {
133 return $this->stream;
134 }
135
136 $this->stream = new Stream($this->file);
137 return $this->stream;
138 }
139
140 /**
141 * Move the uploaded file to a new location.
142 *
143 * Use this method as an alternative to move_uploaded_file(). This method is
144 * guaranteed to work in both SAPI and non-SAPI environments.
145 * Implementations must determine which environment they are in, and use the
146 * appropriate method (move_uploaded_file(), rename(), or a stream
147 * operation) to perform the operation.
148 *
149 * $targetPath may be an absolute path, or a relative path. If it is a
150 * relative path, resolution should be the same as used by PHP's rename()
151 * function.
152 *
153 * The original file or stream MUST be removed on completion.
154 *
155 * If this method is called more than once, any subsequent calls MUST raise
156 * an exception.
157 *
158 * When used in an SAPI environment where $_FILES is populated, when writing
159 * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
160 * used to ensure permissions and upload status are verified correctly.
161 *
162 * If you wish to move to a stream, use getStream(), as SAPI operations
163 * cannot guarantee writing to stream destinations.
164 *
165 * @see http://php.net/is_uploaded_file
166 * @see http://php.net/move_uploaded_file
167 * @param string $targetPath Path to which to move the uploaded file.
168 * @throws \InvalidArgumentException if the $path specified is invalid.
169 * @throws \RuntimeException on any error during the move operation, or on the second or subsequent call to the method.
170 */
171 public function moveTo($targetPath)
172 {
173 if (!is_string($targetPath) || empty($targetPath)) {
174 throw new \InvalidArgumentException('Invalid path while moving an uploaded file.', 1436717307);
175 }
176
177 if ($this->moved) {
178 throw new \RuntimeException('Cannot move uploaded file, as it was already moved.', 1436717308);
179 }
180
181 // Check if the target path is inside the allowed paths of TYPO3, and make it absolute.
182 $targetPath = GeneralUtility::getFileAbsFileName($targetPath);
183 if (empty($targetPath)) {
184 throw new \RuntimeException('Cannot move uploaded file, as it was already moved.', 1436717309);
185 }
186
187 if (!empty($this->file) && is_uploaded_file($this->file)) {
188 if (GeneralUtility::upload_copy_move($this->file, $targetPath . basename($this->file)) === false) {
189 throw new \RuntimeException('An error occurred while moving uploaded file', 1436717310);
190 }
191 } elseif ($this->stream) {
192 $handle = fopen($targetPath, 'wb+');
193 if ($handle === false) {
194 throw new \RuntimeException('Unable to write to target path.', 1436717311);
195 }
196
197 $this->stream->rewind();
198 while (!$this->stream->eof()) {
199 fwrite($handle, $this->stream->read(4096));
200 }
201
202 fclose($handle);
203 }
204
205 $this->moved = true;
206 }
207
208 /**
209 * Retrieve the file size.
210 * Usually returns the value stored in the "size" key of
211 * the file in the $_FILES array if available, as PHP calculates this based
212 * on the actual size transmitted.
213 *
214 * @return int|null The file size in bytes or null if unknown.
215 */
216 public function getSize()
217 {
218 return $this->size;
219 }
220
221 /**
222 * Retrieve the error associated with the uploaded file.
223 * Usually returns the value stored in the "error" key of
224 * the file in the $_FILES array.
225 *
226 * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
227 *
228 * If the file was uploaded successfully, this method MUST return
229 * UPLOAD_ERR_OK.
230 *
231 * @see http://php.net/manual/en/features.file-upload.errors.php
232 * @return int One of PHP's UPLOAD_ERR_XXX constants.
233 */
234 public function getError()
235 {
236 return $this->error;
237 }
238
239 /**
240 * Retrieve the filename sent by the client.
241 * Usually returns the value stored in the "name" key of
242 * the file in the $_FILES array.
243 *
244 * Do not trust the value returned by this method. A client could send
245 * a malicious filename with the intention to corrupt or hack your
246 * application.
247 *
248 * @return string|null The filename sent by the client or null if none was provided.
249 */
250 public function getClientFilename()
251 {
252 return $this->clientFilename;
253 }
254
255 /**
256 * Retrieve the media type sent by the client.
257 * Usually returns the value stored in the "type" key of
258 * the file in the $_FILES array.
259 *
260 * Do not trust the value returned by this method. A client could send
261 * a malicious media type with the intention to corrupt or hack your
262 * application.
263 *
264 * @return string|null The media type sent by the client or null if none was provided.
265 */
266 public function getClientMediaType()
267 {
268 return $this->clientMediaType;
269 }
270 }