imagify / classes / Media / MediaInterface.php

MediaInterface.php in Imagify Image Optimization: Optimize Images | Compress & Convert to WebP/AVIF 2.2.7, at classes/Media/MediaInterface.php

337 lines 7.8 KB

Raw Download Zip

1	<?php
2	namespace Imagify\Media;
3
4	use Imagify\CDN\PushCDNInterface;
5	use Imagify\Context\ContextInterface;
6	use WP_Error;
7
8	/**
9	* Interface to use for "media groups" (aka attachments).
10	*
11	* @since 1.9
12	* @author Grégory Viguier
13	*/
14	interface MediaInterface {
15
16	/**
17	* Tell if the given entry can be accepted in the constructor.
18	* For example it can include `is_numeric( $id )` if the constructor accepts integers.
19	*
20	* @since 1.9
21	* @access public
22	* @author Grégory Viguier
23	*
24	* @param mixed $id Whatever.
25	* @return bool
26	*/
27	public static function constructor_accepts( $id );
28
29	/**
30	* Get the media ID.
31	*
32	* @since 1.9
33	* @access public
34	* @author Grégory Viguier
35	*
36	* @return int
37	*/
38	public function get_id();
39
40	/**
41	* Tell if the current media is valid.
42	*
43	* @since 1.9
44	* @access public
45	* @author Grégory Viguier
46	*
47	* @return bool
48	*/
49	public function is_valid();
50
51	/**
52	* Get the media context name.
53	*
54	* @since 1.9
55	* @access public
56	* @author Grégory Viguier
57	*
58	* @return string
59	*/
60	public function get_context();
61
62	/**
63	* Get the media context instance.
64	*
65	* @since 1.9
66	* @access public
67	* @author Grégory Viguier
68	*
69	* @return ContextInterface
70	*/
71	public function get_context_instance();
72
73	/**
74	* Get the CDN instance.
75	*
76	* @since 1.9
77	* @access public
78	* @author Grégory Viguier
79	*
80	* @return bool\|PushCDNInterface A PushCDNInterface instance. False if no CDN is used.
81	*/
82	public function get_cdn();
83
84
85	/** ----------------------------------------------------------------------------------------- */
86	/** ORIGINAL FILE =========================================================================== */
87	/** ----------------------------------------------------------------------------------------- */
88
89	/**
90	* Get the original file path, even if the file doesn't exist.
91	*
92	* @since 1.9
93	* @access public
94	* @author Grégory Viguier
95	*
96	* @return string\|bool The file path. False on failure.
97	*/
98	public function get_raw_original_path();
99
100	/**
101	* Get the original media's path if the file exists.
102	*
103	* @since 1.9
104	* @access public
105	* @author Grégory Viguier
106	*
107	* @return string\|bool The file path. False if it doesn't exist.
108	*/
109	public function get_original_path();
110
111
112	/** ----------------------------------------------------------------------------------------- */
113	/** FULL SIZE FILE ========================================================================== */
114	/** ----------------------------------------------------------------------------------------- */
115
116	/**
117	* Get the URL of the media’s full size file.
118	*
119	* @since 1.9.8
120	* @access public
121	* @author Grégory Viguier
122	*
123	* @return string\|bool The file URL. False on failure.
124	*/
125	public function get_fullsize_url();
126
127	/**
128	* Get the path to the media’s full size file, even if the file doesn't exist.
129	*
130	* @since 1.9.8
131	* @access public
132	* @author Grégory Viguier
133	*
134	* @return string\|bool The file path. False on failure.
135	*/
136	public function get_raw_fullsize_path();
137
138	/**
139	* Get the path to the media’s full size file if the file exists.
140	*
141	* @since 1.9.8
142	* @access public
143	* @author Grégory Viguier
144	*
145	* @return string\|bool The file path. False if it doesn't exist.
146	*/
147	public function get_fullsize_path();
148
149
150	/** ----------------------------------------------------------------------------------------- */
151	/** BACKUP FILE ============================================================================= */
152	/** ----------------------------------------------------------------------------------------- */
153
154	/**
155	* Get the backup URL, even if the file doesn't exist.
156	*
157	* @since 1.9
158	* @access public
159	* @author Grégory Viguier
160	*
161	* @return string\|bool The file URL. False on failure.
162	*/
163	public function get_backup_url();
164
165	/**
166	* Get the backup file path, even if the file doesn't exist.
167	*
168	* @since 1.9
169	* @access public
170	* @author Grégory Viguier
171	*
172	* @return string\|bool The file path. False on failure.
173	*/
174	public function get_raw_backup_path();
175
176	/**
177	* Get the backup file path if the file exists.
178	*
179	* @since 1.9
180	* @access public
181	* @author Grégory Viguier
182	*
183	* @return string\|bool The file path. False if it doesn't exist.
184	*/
185	public function get_backup_path();
186
187	/**
188	* Check if the media has a backup of the original file.
189	*
190	* @since 1.9
191	* @access public
192	* @author Grégory Viguier
193	*
194	* @return bool True if the media has a backup.
195	*/
196	public function has_backup();
197
198
199	/** ----------------------------------------------------------------------------------------- */
200	/** THUMBNAILS ============================================================================== */
201	/** ----------------------------------------------------------------------------------------- */
202
203	/**
204	* Create the media thumbnails.
205	*
206	* @since 1.9
207	* @access public
208	* @author Grégory Viguier
209	*
210	* @return bool\|WP_Error True on success. A \WP_Error instance on failure.
211	*/
212	public function generate_thumbnails();
213
214
215	/** ----------------------------------------------------------------------------------------- */
216	/** MEDIA DATA ============================================================================== */
217	/** ----------------------------------------------------------------------------------------- */
218
219	/**
220	* Tell if the current media type is supported.
221	*
222	* @since 1.9
223	* @access public
224	* @author Grégory Viguier
225	*
226	* @return bool
227	*/
228	public function is_supported();
229
230	/**
231	* Tell if the current media refers to an image, based on file extension.
232	*
233	* @since 1.9
234	* @access public
235	* @author Grégory Viguier
236	*
237	* @return bool Returns false in case it's an image but not in a supported format (bmp for example).
238	*/
239	public function is_image();
240
241	/**
242	* Tell if the current media refers to a pdf, based on file extension.
243	*
244	* @since 1.9
245	* @access public
246	* @author Grégory Viguier
247	*
248	* @return bool
249	*/
250	public function is_pdf();
251
252	/**
253	* Get the original file extension (if supported by Imagify).
254	*
255	* @since 1.9
256	* @access public
257	* @author Grégory Viguier
258	*
259	* @return string\|null
260	*/
261	public function get_extension();
262
263	/**
264	* Get the original file mime type (if supported by Imagify).
265	*
266	* @since 1.9
267	* @access public
268	* @author Grégory Viguier
269	*
270	* @return string
271	*/
272	public function get_mime_type();
273
274	/**
275	* Get the file mime type + file extension (if the file is supported by Imagify).
276	* This test is ran against the original file.
277	*
278	* @since 1.9
279	* @access public
280	* @author Grégory Viguier
281	*
282	* @return array
283	*/
284	public function get_allowed_mime_types();
285
286	/**
287	* Tell if the current media has the required data (the data containing the file paths and thumbnails).
288	*
289	* @since 1.9
290	* @access public
291	* @author Grégory Viguier
292	*
293	* @return bool
294	*/
295	public function has_required_media_data();
296
297	/**
298	* Get the list of the files of this media, including the original file.
299	*
300	* @since 1.9
301	* @access public
302	* @author Grégory Viguier
303	*
304	* @return array {
305	* An array with the size names as keys ('full' is used for the original file), and arrays of data as values:
306	*
307	* @type string $path Absolute path to the file.
308	* @type int $width The file width.
309	* @type int $height The file height.
310	* @type string $mime-type The file mime type.
311	* }
312	*/
313	public function get_media_files();
314
315	/**
316	* If the media is an image, get its width and height.
317	*
318	* @since 1.9
319	* @access public
320	* @author Grégory Viguier
321	*
322	* @return array
323	*/
324	public function get_dimensions();
325
326	/**
327	* If the media is an image, update the dimensions in the database with the current file dimensions.
328	*
329	* @since 1.9
330	* @access public
331	* @author Grégory Viguier
332	*
333	* @return bool True on success. False on failure.
334	*/
335	public function update_dimensions();
336	}
337