imagify / classes / Media / MediaInterface.php

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

311 lines 7.0 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 media's URL.
92	*
93	* @since 1.9
94	* @access public
95	* @author Grégory Viguier
96	*
97	* @return string\|bool The file URL. False on failure.
98	*/
99	public function get_original_url();
100
101	/**
102	* Get the original file path, even if the file doesn't exist.
103	*
104	* @since 1.9
105	* @access public
106	* @author Grégory Viguier
107	*
108	* @return string\|bool The file path. False on failure.
109	*/
110	public function get_raw_original_path();
111
112	/**
113	* Get the original media's path if the file exists.
114	*
115	* @since 1.9
116	* @access public
117	* @author Grégory Viguier
118	*
119	* @return string\|bool The file path. False if it doesn't exist.
120	*/
121	public function get_original_path();
122
123
124	/** ----------------------------------------------------------------------------------------- */
125	/** BACKUP FILE ============================================================================= */
126	/** ----------------------------------------------------------------------------------------- */
127
128	/**
129	* Get the backup URL, even if the file doesn't exist.
130	*
131	* @since 1.9
132	* @access public
133	* @author Grégory Viguier
134	*
135	* @return string\|bool The file URL. False on failure.
136	*/
137	public function get_backup_url();
138
139	/**
140	* Get the backup file path, even if the file doesn't exist.
141	*
142	* @since 1.9
143	* @access public
144	* @author Grégory Viguier
145	*
146	* @return string\|bool The file path. False on failure.
147	*/
148	public function get_raw_backup_path();
149
150	/**
151	* Get the backup file path if the file exists.
152	*
153	* @since 1.9
154	* @access public
155	* @author Grégory Viguier
156	*
157	* @return string\|bool The file path. False if it doesn't exist.
158	*/
159	public function get_backup_path();
160
161	/**
162	* Check if the media has a backup of the original file.
163	*
164	* @since 1.9
165	* @access public
166	* @author Grégory Viguier
167	*
168	* @return bool True if the media has a backup.
169	*/
170	public function has_backup();
171
172
173	/** ----------------------------------------------------------------------------------------- */
174	/** THUMBNAILS ============================================================================== */
175	/** ----------------------------------------------------------------------------------------- */
176
177	/**
178	* Create the media thumbnails.
179	*
180	* @since 1.9
181	* @access public
182	* @author Grégory Viguier
183	*
184	* @return bool\|WP_Error True on success. A \WP_Error instance on failure.
185	*/
186	public function generate_thumbnails();
187
188
189	/** ----------------------------------------------------------------------------------------- */
190	/** MEDIA DATA ============================================================================== */
191	/** ----------------------------------------------------------------------------------------- */
192
193	/**
194	* Tell if the current media type is supported.
195	*
196	* @since 1.9
197	* @access public
198	* @author Grégory Viguier
199	*
200	* @return bool
201	*/
202	public function is_supported();
203
204	/**
205	* Tell if the current media refers to an image, based on file extension.
206	*
207	* @since 1.9
208	* @access public
209	* @author Grégory Viguier
210	*
211	* @return bool Returns false in case it's an image but not in a supported format (bmp for example).
212	*/
213	public function is_image();
214
215	/**
216	* Tell if the current media refers to a pdf, based on file extension.
217	*
218	* @since 1.9
219	* @access public
220	* @author Grégory Viguier
221	*
222	* @return bool
223	*/
224	public function is_pdf();
225
226	/**
227	* Get the original file extension (if supported by Imagify).
228	*
229	* @since 1.9
230	* @access public
231	* @author Grégory Viguier
232	*
233	* @return string\|null
234	*/
235	public function get_extension();
236
237	/**
238	* Get the original file mime type (if supported by Imagify).
239	*
240	* @since 1.9
241	* @access public
242	* @author Grégory Viguier
243	*
244	* @return string
245	*/
246	public function get_mime_type();
247
248	/**
249	* Get the file mime type + file extension (if the file is supported by Imagify).
250	* This test is ran against the original file.
251	*
252	* @since 1.9
253	* @access public
254	* @author Grégory Viguier
255	*
256	* @return array
257	*/
258	public function get_allowed_mime_types();
259
260	/**
261	* Tell if the current media has the required data (the data containing the file paths and thumbnails).
262	*
263	* @since 1.9
264	* @access public
265	* @author Grégory Viguier
266	*
267	* @return bool
268	*/
269	public function has_required_media_data();
270
271	/**
272	* Get the list of the files of this media, including the original file.
273	*
274	* @since 1.9
275	* @access public
276	* @author Grégory Viguier
277	*
278	* @return array {
279	* An array with the size names as keys ('full' is used for the original file), and arrays of data as values:
280	*
281	* @type string $path Absolute path to the file.
282	* @type int $width The file width.
283	* @type int $height The file height.
284	* @type string $mime-type The file mime type.
285	* }
286	*/
287	public function get_media_files();
288
289	/**
290	* If the media is an image, get its width and height.
291	*
292	* @since 1.9
293	* @access public
294	* @author Grégory Viguier
295	*
296	* @return array
297	*/
298	public function get_dimensions();
299
300	/**
301	* If the media is an image, update the dimensions in the database with the current file dimensions.
302	*
303	* @since 1.9
304	* @access public
305	* @author Grégory Viguier
306	*
307	* @return bool True on success. False on failure.
308	*/
309	public function update_dimensions();
310	}
311