imagify / classes / Optimization / Process / ProcessInterface.php

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

314 lines 7.4 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	*
106	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
107	*
108	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
109	*/
110	public function optimize( $optimization_level = null );
111
112	/**
113	* Re-optimize a media files with a different level.
114	*
115	* @since 1.9
116	*
117	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
118	*
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	*
128	* @param array $sizes An array of media sizes (strings). Use "full" for the size of the main file.
129	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
130	*
131	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
132	*/
133	public function optimize_sizes( $sizes, $optimization_level = null );
134
135	/**
136	* Optimize one file with Imagify directly.
137	*
138	* @since 1.9
139	*
140	* @param string $size The media size.
141	* @param int $optimization_level The optimization level (0=normal, 1=aggressive, 2=ultra).
142	*
143	* @return array\|WP_Error The optimization data. A \WP_Error instance on failure.
144	*/
145	public function optimize_size( $size, $optimization_level = null );
146
147	/**
148	* Restore the media files from the backup file.
149	*
150	* @since 1.9
151	*
152	* @return bool\|WP_Error True on success. A \WP_Error instance on failure.
153	*/
154	public function restore();
155
156	/**
157	* Get the sizes for this media that have not get through optimization.
158	* No sizes are returned if the file is not optimized, has no backup, or is not an image.
159	* The 'full' size os never returned.
160	*
161	* @since 1.9
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	*
182	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
183	*/
184	public function optimize_missing_thumbnails();
185
186	/**
187	* Delete the backup file.
188	*
189	* @since 1.9
190	*/
191	public function delete_backup();
192
193	/**
194	* Maybe resize an image.
195	*
196	* @since 1.9
197	*
198	* @param string $size The size name.
199	* @param File $file A File instance.
200	*
201	* @return array\|WP_Error A \WP_Error instance on failure, an array on success as follow: {
202	* @type bool $resized True when the image has been resized.
203	* @type bool $backuped True when the image has been backuped.
204	* @type int $file_size The file size in bytes.
205	* }
206	*/
207	public function maybe_resize( $size, $file );
208
209	/**
210	* Generate next-gen images if they are missing.
211	*
212	* @since 1.9
213	*
214	* @return bool\|WP_Error True if successfully launched. A \WP_Error instance on failure.
215	*/
216	public function generate_nextgen_versions();
217
218	/**
219	* Delete the next gen format images.
220	* This doesn't delete the related optimization data.
221	*
222	* @since 2.2
223	*
224	* @param bool $keep_full Set to true to keep the full size.
225	*
226	* @return bool\|WP_Error True on success. A \WP_Error object on failure.
227	*/
228	public function delete_nextgen_files( $keep_full = false );
229
230	/**
231	* Tell if a thumbnail size is an "Imagify Next-Gen" size.
232	*
233	* @since 2.2
234	*
235	* @param string $size_name The size name.
236	*
237	* @return string\|bool The unsuffixed name of the size if next-gen. False if not next-gen.
238	*/
239	public function is_size_next_gen( $size_name );
240
241	/**
242	* Tell if the media has all next-gen versions.
243	*
244	* @return bool
245	*/
246	public function is_full_next_gen();
247
248	/**
249	* Tell if the media has a next-gen format.
250	*
251	* @since 2.2
252	*
253	* @return bool
254	*/
255	public function has_next_gen();
256
257	/**
258	* Tell if a process is running for this media.
259	*
260	* @since 1.9
261	*
262	* @return bool
263	*/
264	public function is_locked();
265
266	/**
267	* Set the running status to "running" for a period of time.
268	*
269	* @since 1.9
270	*/
271	public function lock();
272
273	/**
274	* Delete the running status.
275	*
276	* @since 1.9
277	*/
278	public function unlock();
279
280	/**
281	* Tell if a size already has optimization data.
282	*
283	* @since 1.9
284	*
285	* @param string $size The size name.
286	*
287	* @return bool
288	*/
289	public function size_has_optimization_data( $size );
290
291	/**
292	* Update the optimization data for a size.
293	*
294	* @since 1.9
295	*
296	* @param object $response The API response.
297	* @param string $size The size name.
298	* @param int $level The optimization level (0=normal, 1=aggressive, 2=ultra).
299	*
300	* @return array {
301	* The optimization data.
302	*
303	* @type string $size The size name.
304	* @type int $level The optimization level.
305	* @type string $status The status: 'success', 'already_optimized', 'error'.
306	* @type bool $success True if successfully optimized. False on error or if already optimized.
307	* @type string $error An error message.
308	* @type int $original_size The weight of the file, before optimization.
309	* @type int $optimized_size The weight of the file, once optimized.
310	* }
311	*/
312	public function update_size_optimization_data( $response, $size, $level );
313	}
314