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 <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Pdf\Document;
16
17	/**
18	* Pdf document interface
19	*
20	* @category   Pop
21	* @package    Pop\Pdf
22	* @author     Nick Sagona, III <nick@popphp.org>
23	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
24	* @license    https://www.popphp.org/license     New BSD License
25	* @version    6.0.0
26	*/
27	interface DocumentInterface
28	{
29
30	/**
31	* Set the document version
32	*
33	* @param  float $version
34	* @return DocumentInterface
35	*/
36	public function setVersion(float $version): DocumentInterface;
37
38	/**
39	* Set the document metadata
40	*
41	* @param  Metadata $metadata
42	* @return DocumentInterface
43	*/
44	public function setMetadata(Metadata $metadata): DocumentInterface;
45
46	/**
47	* Set the document origin
48	*
49	* @param  string $origin
50	* @return DocumentInterface
51	*/
52	public function setOrigin(string $origin): DocumentInterface;
53
54	/**
55	* Get the document version
56	*
57	* @return float
58	*/
59	public function getVersion(): float;
60
61	/**
62	* Get the document origin
63	*
64	* @return string
65	*/
66	public function getOrigin(): string;
67
68	/**
69	* Get the document metadata
70	*
71	* @return ?Metadata
72	*/
73	public function getMetadata(): ?Metadata;
74
75	/**
76	* Get the PDF page objects array
77	*
78	* @return array
79	*/
80	public function getPages(): array;
81
82	/**
83	* Get a PDF page object
84	*
85	* @param  int $p
86	* @throws \Pop\Pdf\Exception
87	* @return Page
88	*/
89	public function getPage(int $p): Page;
90
91	/**
92	* Determine if the document has page objects
93	*
94	* @return bool
95	*/
96	public function hasPages(): bool;
97
98	/**
99	* Get the PDF font objects array
100	*
101	* @return array
102	*/
103	public function getFonts(): array;
104
105	/**
106	* Get a PDF font object
107	*
108	* @param  string $name
109	* @throws \Pop\Pdf\Exception
110	* @return Font
111	*/
112	public function getFont(string $name): Font;
113
114	/**
115	* Determine if the document has font objects
116	*
117	* @return bool
118	*/
119	public function hasFonts(): bool;
120
121	/**
122	* Get available fonts that have been added to the PDF document
123	*
124	* @return array
125	*/
126	public function getAvailableFonts(): array;
127
128	/**
129	* Determine if a font has been added to the PDF document
130	*
131	* @param  string $font
132	* @return bool
133	*/
134	public function isFontAvailable(string $font): bool;
135
136	/**
137	* Determine if a font has been added to the PDF document (alias)
138	*
139	* @param  string $font
140	* @return bool
141	*/
142	public function hasFont(string $font): bool;
143
144	/**
145	* Get the current page number
146	*
147	* @return ?int
148	*/
149	public function getCurrentPage(): ?int;
150
151	/**
152	* Get the current number of pages
153	*
154	* @return int
155	*/
156	public function getNumberOfPages(): int;
157
158	/**
159	* Get the current font
160	*
161	* @return ?string
162	*/
163	public function getCurrentFont(): ?string;
164
165	/**
166	* Get the current number of fonts
167	*
168	* @return int
169	*/
170	public function getNumberOfFonts(): int;
171
172	/**
173	* Get form objects
174	*
175	* @return array
176	*/
177	public function getForms(): array;
178
179	/**
180	* Get form objects
181	*
182	* @param  string $name
183	* @return ?Form
184	*/
185	public function getForm(string $name): ?Form;
186
187	/**
188	* Determine if the document has form objects
189	*
190	* @return bool
191	*/
192	public function hasForms(): bool;
193
194	/**
195	* Add form
196	*
197	* @param  Form $form
198	* @return DocumentInterface
199	*/
200	public function addForm(Form $form): DocumentInterface;
201
202	/**
203	* Set the compression
204	*
205	* @param  bool $compression
206	* @return DocumentInterface
207	*/
208	public function setCompression(bool $compression): DocumentInterface;
209
210	/**
211	* Determine whether the PDF is compressed or not
212	*
213	* @return bool
214	*/
215	public function isCompressed(): bool;
216
217	/**
218	* Constructor
219	*
220	* Instantiate a PDF document
221	*
222	* @param  ?Page     $page
223	* @param  ?Metadata $metadata
224	* @return DocumentInterface
225	*/
226	public function __construct(?Page $page = null, ?Metadata $metadata = null);
227
228	/**
229	* Add a page to the PDF document
230	*
231	* @param  Page $page
232	* @return DocumentInterface
233	*/
234	public function addPage(Page $page): DocumentInterface;
235
236	/**
237	* Add pages to the PDF document
238	*
239	* @param  array $pages
240	* @return DocumentInterface
241	*/
242	public function addPages(array $pages): DocumentInterface;
243
244	/**
245	* Create and return a new page object, adding it to the PDF document
246	*
247	* @param  mixed $size
248	* @param  mixed $height
249	* @return Page
250	*/
251	public function createPage(mixed $size, mixed $height = null): Page;
252
253	/**
254	* Copy and return a page of the PDF, adding it to the PDF document
255	*
256	* @param  int $p
257	* @throws Exception
258	* @return Page
259	*/
260	public function copyPage(int $p): Page;
261
262	/**
263	* Order the pages
264	*
265	* @param  array $pages
266	* @throws Exception
267	* @return DocumentInterface
268	*/
269	public function orderPages(array $pages): DocumentInterface;
270
271	/**
272	* Delete a page from the PDF document
273	*
274	* @param  int $p
275	* @throws Exception
276	* @return DocumentInterface
277	*/
278	public function deletePage(int $p): DocumentInterface;
279
280	/**
281	* Add a font
282	*
283	* @param  Font $font
284	* @throws Exception
285	* @return DocumentInterface
286	*/
287	public function addFont(Font $font): DocumentInterface;
288
289	/**
290	* Add fonts
291	*
292	* @param  array $fonts
293	* @throws Exception
294	* @return AbstractDocument
295	*/
296	public function addFonts(array $fonts): DocumentInterface;
297
298	/**
299	* Add a font
300	*
301	* @param  Font $font
302	* @param  bool $embedOverride
303	* @throws Exception
304	* @return DocumentInterface
305	*/
306	public function embedFont(Font $font, bool $embedOverride = false): DocumentInterface;
307
308	/**
309	* Embed fonts
310	*
311	* @param  array $fonts
312	* @param  bool $embedOverride
313	* @throws Exception
314	* @return DocumentInterface
315	*/
316	public function embedFonts(array $fonts, bool $embedOverride = false): DocumentInterface;
317
318	/**
319	* Create style
320	*
321	* @param  Style|string $style
322	* @return DocumentInterface
323	*/
324	public function createStyle(Style|string $style, ?string $font = null, int|float|null $size = null): DocumentInterface;
325
326	/**
327	* Add a style
328	*
329	* @param  Style|string $style
330	* @return DocumentInterface
331	*/
332	public function addStyle(Style|string $style): DocumentInterface;
333
334	/**
335	* Add styles
336	*
337	* @param  array $styles
338	* @return DocumentInterface
339	*/
340	public function addStyles(array $styles): DocumentInterface;
341
342	/**
343	* Set the current page of the PDF document
344	*
345	* @param  int $p
346	* @throws Exception
347	* @return DocumentInterface
348	*/
349	public function setCurrentPage(int $p): DocumentInterface;
350
351	/**
352	* Set the current font of the PDF document
353	*
354	* @param  string $name
355	* @throws Exception
356	* @return DocumentInterface
357	*/
358	public function setCurrentFont(string $name): DocumentInterface;
359
360	/**
361	* Output the PDF document to string
362	*
363	* @return string
364	*/
365	public function __toString(): string;
366
367	}