imagify / classes / Optimization / Data / DataInterface.php

DataInterface.php in Imagify Image Optimization: Optimize Images | Compress & Convert to WebP/AVIF 2.2.3.1, at classes/Optimization/Data/DataInterface.php

276 lines 7.4 KB

Raw Download Zip

1	<?php
2	namespace Imagify\Optimization\Data;
3
4	defined( 'ABSPATH' ) \|\| die( 'Cheatin’ uh?' );
5
6	/**
7	* Interface to use to handle the optimization data of "media groups" (aka attachments).
8	*
9	* @since 1.9
10	* @author Grégory Viguier
11	*/
12	interface DataInterface {
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 media instance.
29	*
30	* @since 1.9
31	* @access public
32	* @author Grégory Viguier
33	*
34	* @return MediaInterface\|false
35	*/
36	public function get_media();
37
38	/**
39	* Tell if the current media is valid.
40	*
41	* @since 1.9
42	* @access public
43	* @author Grégory Viguier
44	*
45	* @return bool
46	*/
47	public function is_valid();
48
49
50	/** ----------------------------------------------------------------------------------------- */
51	/** OPTIMIZATION DATA ======================================================================= */
52	/** ----------------------------------------------------------------------------------------- */
53
54	/**
55	* Check if the main file is optimized (by Imagify).
56	*
57	* @since 1.9
58	* @access public
59	* @author Grégory Viguier
60	*
61	* @return bool True if the media is optimized.
62	*/
63	public function is_optimized();
64
65	/**
66	* Check if the main file is optimized (NOT by Imagify).
67	*
68	* @since 1.9
69	* @access public
70	* @author Grégory Viguier
71	*
72	* @return bool True if the media is optimized.
73	*/
74	public function is_already_optimized();
75
76	/**
77	* Check if the main file is optimized (by Imagify).
78	*
79	* @since 1.9
80	* @access public
81	* @author Grégory Viguier
82	*
83	* @return bool True if the media is optimized.
84	*/
85	public function is_error();
86
87	/**
88	* Get the whole media optimization data.
89	*
90	* @since 1.9
91	* @access public
92	* @author Grégory Viguier
93	*
94	* @return array {
95	* The data.
96	*
97	* @type string $status The optimization status of the whole media: 'success', 'already_optimized', or 'error'.
98	* It is the same as the main file’s status.
99	* @type int\|bool $level The optimization level (0=normal, 1=aggressive, 2=ultra). False if not set.
100	* @type array $sizes {
101	* A list of size data, keyed by size name, and containing:
102	*
103	* @type bool $success Whether the optimization has been successful.
104	* If a success:
105	* @type int $original_size The file size before optimization.
106	* @type int $optimized_size The file size after optimization.
107	* @type int $percent Saving in percent.
108	* If an error or 'already_optimized':
109	* @type string $error An error message.
110	* }
111	* @type array $stats {
112	* @type int $original_size Overall size before optimization.
113	* @type int $optimized_size Overall size after optimization.
114	* @type int $percent Overall saving in percent.
115	* }
116	* }
117	*/
118	public function get_optimization_data();
119
120	/**
121	* Update the optimization data, level, and status for a size.
122	*
123	* @since 1.9
124	* @access public
125	* @author Grégory Viguier
126	*
127	* @param string $size The size name.
128	* @param array $data {
129	* The optimization data.
130	*
131	* @type int $level The optimization level.
132	* @type string $status The status: 'success', 'already_optimized', 'error'.
133	* @type bool $success True if successfully optimized. False on error or if already optimized.
134	* @type string $error An error message.
135	* @type int $original_size The weight of the file, before optimization.
136	* @type int $optimized_size The weight of the file, after optimization.
137	* }
138	*/
139	public function update_size_optimization_data( $size, array $data );
140
141	/**
142	* Delete the media optimization data, level, and status.
143	*
144	* @since 1.9
145	* @access public
146	* @author Grégory Viguier
147	*/
148	public function delete_optimization_data();
149
150	/**
151	* Delete the optimization data for the given sizes.
152	* If all sizes are removed, all optimization data is deleted.
153	* Status and level are not modified nor removed if the "full" size is removed. This leaves the media in a Schrödinger state.
154	*
155	* @since 1.9.8
156	* @access public
157	* @author Grégory Viguier
158	*
159	* @param array $sizes A list of sizes to remove.
160	*/
161	public function delete_sizes_optimization_data( array $sizes );
162
163	/**
164	* Get the media's optimization level.
165	*
166	* @since 1.9
167	* @access public
168	* @author Grégory Viguier
169	*
170	* @return int\|bool The optimization level. False if not optimized.
171	*/
172	public function get_optimization_level();
173
174	/**
175	* Get the media's optimization status (success or error).
176	*
177	* @since 1.9
178	* @access public
179	* @author Grégory Viguier
180	*
181	* @return string The optimization status. An empty string if there is none.
182	*/
183	public function get_optimization_status();
184
185	/**
186	* Count number of optimized sizes.
187	*
188	* @since 1.9
189	* @access public
190	* @author Grégory Viguier
191	*
192	* @return int Number of optimized sizes.
193	*/
194	public function get_optimized_sizes_count();
195
196	/**
197	* Get the original media's size (weight).
198	*
199	* @since 1.9
200	* @access public
201	* @author Grégory Viguier
202	*
203	* @param bool $human_format True to display the image human format size (1Mb).
204	* @param int $decimals Precision of number of decimal places.
205	* @return string\|int
206	*/
207	public function get_original_size( $human_format = true, $decimals = 2 );
208
209	/**
210	* Get the file size of the full size file.
211	* If the Nextgen size is available, it is used.
212	*
213	* @since 1.9
214	* @access public
215	* @author Grégory Viguier
216	*
217	* @param bool $human_format True to display the image human format size (1Mb).
218	* @param int $decimals Precision of number of decimal places.
219	* @param bool $use_nextgen Use the Nextgen size if available.
220	* @return string\|int
221	*/
222	public function get_optimized_size( $human_format = true, $decimals = 2, $use_nextgen = true );
223
224
225	/** ----------------------------------------------------------------------------------------- */
226	/** OPTIMIZATION STATS ====================================================================== */
227	/** ----------------------------------------------------------------------------------------- */
228
229	/**
230	* Get one or all statistics of a specific size.
231	*
232	* @since 1.9
233	* @access public
234	* @author Grégory Viguier
235	*
236	* @param string $size The thumbnail slug.
237	* @param string $key The specific data slug.
238	* @return array\|string
239	*/
240	public function get_size_data( $size = 'full', $key = '' );
241
242	/**
243	* Get the overall statistics data or a specific one.
244	*
245	* @since 1.9
246	* @access public
247	* @author Grégory Viguier
248	*
249	* @param string $key The specific data slug.
250	* @return array\|string
251	*/
252	public function get_stats_data( $key = '' );
253
254	/**
255	* Get the optimized/original saving of the original image in percent.
256	*
257	* @since 1.9
258	* @access public
259	* @author Grégory Viguier
260	*
261	* @return float A 2-decimals float.
262	*/
263	public function get_saving_percent();
264
265	/**
266	* Get the overall optimized/original saving (original image + all thumbnails) in percent.
267	*
268	* @since 1.9
269	* @access public
270	* @author Grégory Viguier
271	*
272	* @return float A 2-decimals float.
273	*/
274	public function get_overall_saving_percent();
275	}
276