imagify / classes / Media / MediaInterface.php

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

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