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