searchpro / BerqWP / vendor / psr / http-message / src / UploadedFileInterface.php

UploadedFileInterface.php in BerqWP – All-In-One Optimization for Core Web Vitals, Cache, CDN, Images, CSS & JavaScript trunk, at BerqWP/vendor/psr/http-message/src/UploadedFileInterface.php

124 lines 4.6 KB

Raw Download Zip

1	<?php
2
3	namespace 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	*/
13	interface 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(): StreamInterface;
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(string $targetPath): void;
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(): ?int;
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(): int;
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(): ?string;
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(): ?string;
123	}
124