imagify / classes / Optimization / Process / ProcessInterface.php

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

320 lines 7.9 KB

Raw Download Zip

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