imagify / classes / Optimization / Process / ProcessInterface.php

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

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