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