imagify / classes / Optimization / Process / ProcessInterface.php

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

363 lines 10.2 KB

Raw Download Zip

1	<?php
2	namespace Imagify\Optimization\Process;
3
4	defined( 'ABSPATH' ) \|\| die( 'Cheatin’ uh?' );
5
6	/**
7	* Interface to use to optimize medias.
8	*
9	* @since 1.9
10	* @author Grégory Viguier
11	*/
12	interface ProcessInterface {
13
14	/**
15	* Tell if the given entry can be accepted in the constructor.
16	* For example it can include `is_numeric( $id )` if the constructor accepts integers.
17	*
18	* @since 1.9
19	* @access public
20	* @author Grégory Viguier
21	*
22	* @param mixed $id Whatever.
23	* @return bool
24	*/
25	public static function constructor_accepts( $id );
26
27	/**
28	* Get the data instance.
29	*
30	* @since 1.9
31	* @access public
32	* @author Grégory Viguier
33	*
34	* @return DataInterface\|false
35	*/
36	public function get_data();
37
38	/**
39	* Get the media instance.
40	*
41	* @since 1.9
42	* @access public
43	* @author Grégory Viguier
44	*
45	* @return MediaInterface\|false
46	*/
47	public function get_media();
48
49	/**
50	* Get the File instance of the original file.
51	*
52	* @since 1.9.8
53	* @access public
54	* @author Grégory Viguier
55	*
56	* @return File\|false
57	*/
58	public function get_original_file();
59
60	/**
61	* Get the File instance of the full size file.
62	*
63	* @since 1.9.8
64	* @access public
65	* @author Grégory Viguier
66	*
67	* @return File\|false
68	*/
69	public function get_fullsize_file();
70
71	/**
72	* Tell if the current media is valid.
73	*
74	* @since 1.9
75	* @access public
76	* @author Grégory Viguier
77	*
78	* @return bool
79	*/
80	public function is_valid();
81
82	/**
83	* Tell if the current user is allowed to operate Imagify in this context.
84	*
85	* @since 1.9
86	* @access public
87	* @author Grégory Viguier
88	*
89	* @param string $describer Capacity describer. See \Imagify\Context\ContextInterface->get_capacity() for possible values. Can also be a "real" user capacity.
90	* @return bool
91	*/
92	public function current_user_can( $describer );
93
94
95	/** ----------------------------------------------------------------------------------------- */
96	/** OPTIMIZATION ============================================================================ */
97	/** ----------------------------------------------------------------------------------------- */
98
99	/**
100	* Optimize a media files by pushing tasks into the queue.
101	*
102	* @since 1.9
103	* @access public
104	* @author Grégory Viguier
105	*
106	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
107	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
108	*/
109	public function optimize( $optimization_level = null );
110
111	/**
112	* Re-optimize a media files with a different level.
113	*
114	* @since 1.9
115	* @access public
116	* @author Grégory Viguier
117	*
118	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
119	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
120	*/
121	public function reoptimize( $optimization_level = null );
122
123	/**
124	* Optimize several file sizes by pushing tasks into the queue.
125	*
126	* @since 1.9
127	* @access public
128	* @author Grégory Viguier
129	*
130	* @param array $sizes An array of media sizes (strings). Use "full" for the size of the main file.
131	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
132	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
133	*/
134	public function optimize_sizes( $sizes, $optimization_level = null );
135
136	/**
137	* Optimize one file with Imagify directly.
138	*
139	* @since 1.9
140	* @access public
141	* @author Grégory Viguier
142	*
143	* @param string $size The media size.
144	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
145	* @return array\|WP_Error The optimization data. A \WP_Error instance on failure.
146	*/
147	public function optimize_size( $size, $optimization_level = null );
148
149	/**
150	* Restore the media files from the backup file.
151	*
152	* @since 1.9
153	* @access public
154	* @author Grégory Viguier
155	*
156	* @return bool\|WP_Error True on success. A \WP_Error instance on failure.
157	*/
158	public function restore();
159
160
161	/** ----------------------------------------------------------------------------------------- */
162	/** MISSING THUMBNAILS ====================================================================== */
163	/** ----------------------------------------------------------------------------------------- */
164
165	/**
166	* Get the sizes for this media that have not get through optimization.
167	* No sizes are returned if the file is not optimized, has no backup, or is not an image.
168	* The 'full' size os never returned.
169	*
170	* @since 1.9
171	* @access public
172	* @author Grégory Viguier
173	*
174	* @return array\|WP_Error {
175	* A WP_Error object on failure.
176	* An array of data for the thumbnail sizes on success.
177	* Size names are used as array keys.
178	*
179	* @type int $width The image width.
180	* @type int $height The image height.
181	* @type bool $crop True to crop, false to resize.
182	* @type string $name The size name.
183	* @type string $file The name the thumbnail "should" have.
184	* }
185	*/
186	public function get_missing_sizes();
187
188	/**
189	* Optimize missing thumbnail sizes.
190	*
191	* @since 1.9
192	* @access public
193	* @author Grégory Viguier
194	*
195	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
196	*/
197	public function optimize_missing_thumbnails();
198
199
200	/** ----------------------------------------------------------------------------------------- */
201	/** BACKUP FILE ============================================================================= */
202	/** ----------------------------------------------------------------------------------------- */
203
204	/**
205	* Delete the backup file.
206	*
207	* @since 1.9
208	* @access public
209	* @author Grégory Viguier
210	*/
211	public function delete_backup();
212
213
214	/** ----------------------------------------------------------------------------------------- */
215	/** RESIZE FILE ============================================================================= */
216	/** ----------------------------------------------------------------------------------------- */
217
218	/**
219	* Maybe resize an image.
220	*
221	* @since 1.9
222	* @access protected
223	* @author Grégory Viguier
224	*
225	* @param string $size The size name.
226	* @param File $file A File instance.
227	* @return array\|WP_Error A \WP_Error instance on failure, an array on success as follow: {
228	* @type bool $resized True when the image has been resized.
229	* @type bool $backuped True when the image has been backuped.
230	* @type int $file_size The file size in bytes.
231	* }
232	*/
233	public function maybe_resize( $size, $file );
234
235
236	/** ----------------------------------------------------------------------------------------- */
237	/** WEBP ==================================================================================== */
238	/** ----------------------------------------------------------------------------------------- */
239
240	/**
241	* Generate webp images if they are missing.
242	*
243	* @since 1.9
244	* @access public
245	* @author Grégory Viguier
246	*
247	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
248	*/
249	public function generate_webp_versions();
250
251	/**
252	* Delete the webp images.
253	* This doesn't delete the related optimization data.
254	*
255	* @since 1.9
256	* @since 1.9.6 Return WP_Error or true.
257	* @access public
258	* @author Grégory Viguier
259	*
260	* @param bool $keep_full Set to true to keep the full size.
261	* @return bool\|\WP_Error True on success. A \WP_Error object on failure.
262	*/
263	public function delete_webp_files( $keep_full = false );
264
265	/**
266	* Tell if a thumbnail size is an "Imagify webp" size.
267	*
268	* @since 1.9
269	* @access public
270	* @author Grégory Viguier
271	*
272	* @param string $size_name The size name.
273	* @return string\|bool The unsuffixed name of the size if webp. False if not webp.
274	*/
275	public function is_size_webp( $size_name );
276
277	/**
278	* Tell if the media has webp versions.
279	*
280	* @since 1.9
281	* @access public
282	* @author Grégory Viguier
283	*
284	* @return bool
285	*/
286	public function has_webp();
287
288
289	/** ----------------------------------------------------------------------------------------- */
290	/** PROCESS STATUS ========================================================================== */
291	/** ----------------------------------------------------------------------------------------- */
292
293	/**
294	* Tell if a process is running for this media.
295	*
296	* @since 1.9
297	* @access public
298	* @author Grégory Viguier
299	*
300	* @return bool
301	*/
302	public function is_locked();
303
304	/**
305	* Set the running status to "running" for a period of time.
306	*
307	* @since 1.9
308	* @access public
309	* @author Grégory Viguier
310	*/
311	public function lock();
312
313	/**
314	* Delete the running status.
315	*
316	* @since 1.9
317	* @access public
318	* @author Grégory Viguier
319	*/
320	public function unlock();
321
322
323	/** ----------------------------------------------------------------------------------------- */
324	/** DATA ==================================================================================== */
325	/** ----------------------------------------------------------------------------------------- */
326
327	/**
328	* Tell if a size already has optimization data.
329	*
330	* @since 1.9
331	* @access public
332	* @author Grégory Viguier
333	*
334	* @param string $size The size name.
335	* @return bool
336	*/
337	public function size_has_optimization_data( $size );
338
339	/**
340	* Update the optimization data for a size.
341	*
342	* @since 1.9
343	* @access public
344	* @author Grégory Viguier
345	*
346	* @param object $response The API response.
347	* @param string $size The size name.
348	* @param int $level The optimization level (0=normal, 1=aggressive, 2=ultra).
349	* @return array {
350	* The optimization data.
351	*
352	* @type string $size The size name.
353	* @type int $level The optimization level.
354	* @type string $status The status: 'success', 'already_optimized', 'error'.
355	* @type bool $success True if successfully optimized. False on error or if already optimized.
356	* @type string $error An error message.
357	* @type int $original_size The weight of the file, before optimization.
358	* @type int $optimized_size The weight of the file, once optimized.
359	* }
360	*/
361	public function update_size_optimization_data( $response, $size, $level );
362	}
363