wordpress-seo / vendor_prefixed / psr / http-message / src / UploadedFileInterface.php

UploadedFileInterface.php in Yoast SEO – Advanced SEO with real-time guidance and built-in AI 28.2, at vendor_prefixed/psr/http-message/src/UploadedFileInterface.php

119 lines 4.7 KB

Raw Download Zip

1	<?php
2
3	namespace YoastSEO_Vendor\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() : \YoastSEO_Vendor\Psr\Http\Message\StreamInterface;
32	/**
33	* Move the uploaded file to a new location.
34	*
35	* Use this method as an alternative to move_uploaded_file(). This method is
36	* guaranteed to work in both SAPI and non-SAPI environments.
37	* Implementations must determine which environment they are in, and use the
38	* appropriate method (move_uploaded_file(), rename(), or a stream
39	* operation) to perform the operation.
40	*
41	* $targetPath may be an absolute path, or a relative path. If it is a
42	* relative path, resolution should be the same as used by PHP's rename()
43	* function.
44	*
45	* The original file or stream MUST be removed on completion.
46	*
47	* If this method is called more than once, any subsequent calls MUST raise
48	* an exception.
49	*
50	* When used in an SAPI environment where $_FILES is populated, when writing
51	* files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
52	* used to ensure permissions and upload status are verified correctly.
53	*
54	* If you wish to move to a stream, use getStream(), as SAPI operations
55	* cannot guarantee writing to stream destinations.
56	*
57	* @see http://php.net/is_uploaded_file
58	* @see http://php.net/move_uploaded_file
59	* @param string $targetPath Path to which to move the uploaded file.
60	* @throws \InvalidArgumentException if the $targetPath specified is invalid.
61	* @throws \RuntimeException on any error during the move operation, or on
62	* the second or subsequent call to the method.
63	*/
64	public function moveTo(string $targetPath) : void;
65	/**
66	* Retrieve the file size.
67	*
68	* Implementations SHOULD return the value stored in the "size" key of
69	* the file in the $_FILES array if available, as PHP calculates this based
70	* on the actual size transmitted.
71	*
72	* @return int\|null The file size in bytes or null if unknown.
73	*/
74	public function getSize() : ?int;
75	/**
76	* Retrieve the error associated with the uploaded file.
77	*
78	* The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
79	*
80	* If the file was uploaded successfully, this method MUST return
81	* UPLOAD_ERR_OK.
82	*
83	* Implementations SHOULD return the value stored in the "error" key of
84	* the file in the $_FILES array.
85	*
86	* @see http://php.net/manual/en/features.file-upload.errors.php
87	* @return int One of PHP's UPLOAD_ERR_XXX constants.
88	*/
89	public function getError() : int;
90	/**
91	* Retrieve the filename sent by the client.
92	*
93	* Do not trust the value returned by this method. A client could send
94	* a malicious filename with the intention to corrupt or hack your
95	* application.
96	*
97	* Implementations SHOULD return the value stored in the "name" key of
98	* the file in the $_FILES array.
99	*
100	* @return string\|null The filename sent by the client or null if none
101	* was provided.
102	*/
103	public function getClientFilename() : ?string;
104	/**
105	* Retrieve the media type sent by the client.
106	*
107	* Do not trust the value returned by this method. A client could send
108	* a malicious media type with the intention to corrupt or hack your
109	* application.
110	*
111	* Implementations SHOULD return the value stored in the "type" key of
112	* the file in the $_FILES array.
113	*
114	* @return string\|null The media type sent by the client or null if none
115	* was provided.
116	*/
117	public function getClientMediaType() : ?string;
118	}
119