1	<?php
2	/**
3	* Pop PHP Framework (https://www.popphp.org/)
4	*
5	* @link       https://github.com/popphp/popphp-framework
6	* @author     Nick Sagona, III <dev@noladev.com>
7	* @copyright  Copyright (c) 2009-2025 NOLA Interactive, LLC.
8	* @license    https://www.popphp.org/license     New BSD License
9	*/
10
11	/**
12	* @namespace
13	*/
14	namespace Pop\Image\Adapter;
15
16	use Pop\Image\Adjust;
17	use Pop\Color\Color;
18	use Pop\Image\Draw;
19	use Pop\Image\Effect;
20	use Pop\Image\Filter;
21	use Pop\Image\Layer;
22	use Pop\Image\Type;
23
24	/**
25	* Adapter interface
26	*
27	* @category   Pop
28	* @package    Pop\Image
29	* @author     Nick Sagona, III <dev@noladev.com>
30	* @copyright  Copyright (c) 2009-2025 NOLA Interactive, LLC.
31	* @license    https://www.popphp.org/license     New BSD License
32	* @version    4.1.1
33	*/
34	interface AdapterInterface
35	{
36
37	/**
38	* Create the image resource
39	*
40	* @return void
41	*/
42	public function createResource(): void;
43
44	/**
45	* Get the image resource
46	*
47	* @return mixed
48	*/
49	public function getResource(): mixed;
50
51	/**
52	* Determine if there is an image resource
53	*
54	* @return bool
55	*/
56	public function hasResource(): bool;
57
58	/**
59	* Get the image name
60	*
61	* @return string
62	*/
63	public function getName(): string;
64
65	/**
66	* Get the image width
67	*
68	* @return int
69	*/
70	public function getWidth(): int;
71
72	/**
73	* Get the image height
74	*
75	* @return int
76	*/
77	public function getHeight(): int;
78
79	/**
80	* Get the image quality
81	*
82	* @return int
83	*/
84	public function getQuality(): int;
85
86	/**
87	* Get the colorspace
88	*
89	* @return int
90	*/
91	public function getColorspace(): int;
92
93	/**
94	* Determine if the image is index color
95	*
96	* @return bool
97	*/
98	public function isIndexed(): bool;
99
100	/**
101	* Get the image EXIF data
102	*
103	* @return array
104	*/
105	public function getExif(): array;
106
107	/**
108	* Determine if the image is grayscale
109	*
110	* @return bool
111	*/
112	public function isGray(): bool;
113
114	/**
115	* Determine if the image is RGB
116	*
117	* @return bool
118	*/
119	public function isRgb(): bool;
120
121	/**
122	* Determine if the image is CMYK
123	*
124	* @return bool
125	*/
126	public function isCmyk(): bool;
127
128	/**
129	* Set the image quality
130	*
131	* @param  int $quality
132	* @return static
133	*/
134	public function setQuality(int $quality): static;
135
136	/**
137	* Load the image resource from the existing image file
138	*
139	* @param  ?string $name
140	* @return AdapterInterface
141	*/
142	public function load(?string $name = null): AdapterInterface;
143
144	/**
145	* Load the image resource from data
146	*
147	* @param  string $data
148	* @param  string $name
149	* @return AdapterInterface
150	*/
151	public function loadFromString(string $data, ?string $name = null): AdapterInterface;
152
153	/**
154	* Create a new image resource
155	*
156	* @param  ?int    $width
157	* @param  ?int    $height
158	* @param  ?string $name
159	* @return AdapterInterface
160	*/
161	public function create(?int $width = null, ?int $height = null, ?string $name = null): AdapterInterface;
162
163	/**
164	* Create a new indexed image resource
165	*
166	* @param  ?int    $width
167	* @param  ?int    $height
168	* @param  ?string $name
169	* @return AdapterInterface
170	*/
171	public function createIndex(?int $width = null, ?int $height = null, ?string $name = null): AdapterInterface;
172
173	/**
174	* Resize the image object to the width parameter passed
175	*
176	* @param  int $w
177	* @return AdapterInterface
178	*/
179	public function resizeToWidth(int $w): AdapterInterface;
180
181	/**
182	* Resize the image object to the height parameter passed
183	*
184	* @param  int $h
185	* @return AdapterInterface
186	*/
187	public function resizeToHeight(int $h): AdapterInterface;
188
189	/**
190	* Resize the image object, allowing for the largest dimension
191	* to be scaled to the value of the $px argument.
192	*
193	* @param  int $px
194	* @return AdapterInterface
195	*/
196	public function resize(int $px): AdapterInterface;
197
198	/**
199	* Scale the image object, allowing for the dimensions to be scaled
200	* proportionally to the value of the $scl argument.
201	*
202	* @param  float $scale
203	* @return AdapterInterface
204	*/
205	public function scale(float $scale): AdapterInterface;
206
207	/**
208	* Crop the image object to a image whose dimensions are based on the
209	* value of the $wid and $hgt argument. The optional $x and $y arguments
210	* allow for the adjustment of the crop to select a certain area of the
211	* image to be cropped.
212	*
213	* @param  int $w
214	* @param  int $h
215	* @param  int $x
216	* @param  int $y
217	* @return AdapterInterface
218	*/
219	public function crop(int $w, int $h, int $x = 0, int $y = 0): AdapterInterface;
220
221	/**
222	* Crop the image object to a square image whose dimensions are based on the
223	* value of the $px argument. The optional $offset argument allows for the
224	* adjustment of the crop to select a certain area of the image to be cropped.
225	*
226	* @param  int  $px
227	* @param  ?int $offset
228	* @return AdapterInterface
229	*/
230	public function cropThumb(int $px, ?int $offset = null): AdapterInterface;
231
232	/**
233	* Rotate the image object
234	*
235	* @param  int                   $degrees
236	* @param  ?Color\ColorInterface $bgColor
237	* @throws Exception
238	* @return Gd
239	*/
240	public function rotate(int $degrees, ?Color\ColorInterface $bgColor = null): AdapterInterface;
241
242	/**
243	* Method to flip the image over the x-axis
244	*
245	* @return AdapterInterface
246	*/
247	public function flip(): AdapterInterface;
248
249	/**
250	* Method to flip the image over the y-axis
251	*
252	* @return AdapterInterface
253	*/
254	public function flop(): AdapterInterface;
255
256	/**
257	* Get the image adjust object
258	*
259	* @return Adjust\AdjustInterface
260	*/
261	public function adjust(): Adjust\AdjustInterface;
262
263	/**
264	* Get the image filter object
265	*
266	* @return Filter\FilterInterface
267	*/
268	public function filter(): Filter\FilterInterface;
269
270	/**
271	* Get the image layer object
272	*
273	* @return Layer\LayerInterface
274	*/
275	public function layer(): Layer\LayerInterface;
276
277	/**
278	* Get the image draw object
279	*
280	* @return Draw\DrawInterface
281	*/
282	public function draw(): Draw\DrawInterface;
283
284	/**
285	* Get the image effect object
286	*
287	* @return Effect\EffectInterface
288	*/
289	public function effect(): Effect\EffectInterface;
290
291	/**
292	* Get the image type object
293	*
294	* @return Type\TypeInterface
295	*/
296	public function type(): Type\TypeInterface;
297
298	/**
299	* Convert the image object to another format
300	*
301	* @param  string $type
302	* @throws Exception
303	* @return AdapterInterface
304	*/
305	public function convert(string $type): AdapterInterface;
306
307	/**
308	* Write the image object to a file on disk
309	*
310	* @param  ?string $to
311	* @param  int     $quality
312	* @throws Exception
313	* @return void
314	*/
315	public function writeToFile(?string $to = null, int $quality = 100): void;
316
317	/**
318	* Output the image object to a raw string
319	*
320	* @param  int $quality
321	* @throws Exception
322	* @return string|false
323	*/
324	public function outputToRawString(int $quality = 100): string|false;
325
326	/**
327	* Output the image object directly to HTTP
328	*
329	* @param  int     $quality
330	* @param  ?string $to
331	* @param  bool    $download
332	* @param  bool    $sendHeaders
333	* @throws Exception
334	* @return void
335	*/
336	public function outputToHttp(int $quality = 100, ?string $to = null, bool $download = false, bool $sendHeaders = true): void;
337
338	/**
339	* Destroy the image object and the related image file directly
340	*
341	* @param  bool $delete
342	* @return void
343	*/
344	public function destroy(bool $delete = false): void;
345
346	/**
347	* Create and return a color.
348	*
349	* @param  ?Color\ColorInterface $color
350	* @param  int                  $alpha
351	* @throws Exception
352	* @return mixed
353	*/
354	public function createColor(Color\ColorInterface $color = null, int $alpha = 100): mixed;
355
356	/**
357	* Send image headers the image
358	*
359	* @param  ?string $to
360	* @param  bool    $download
361	* @return void
362	*/
363	public function sendHeaders(?string $to = null, bool $download = false): void;
364
365	/**
366	* Output the image
367	*
368	* @return string
369	*/
370	public function __toString(): string;
371
372	}