1	<?php declare(strict_types=1);
2
3	namespace Computator\FrameworkUtils\PHPTemplate\UserApi;
4
5	use Computator\FrameworkUtils\PHPTemplate\TemplateResolver;
6	use Computator\FrameworkUtils\PHPTemplate\Templates;
7
8	/**
9	* User-visible interface to a `Renderer`.
10	*
11	* These are the available methods intended for public use to configure and use
12	* a `Renderer`.
13	*
14	* Note that `Renderer` instances have additional public methods meant for
15	* internal use to control the rendering process (defined by the `RenderManager`
16	* interface), but these methods are not intended for use by end-users.
17	*
18	* @see Computator\FrameworkUtils\PHPTemplate\Renderer
19	* @see RenderManager
20	*/
21	interface RenderClient {
22	/**
23	* Create a new `Renderer`.
24	*
25	* This method is used to create a new `Renderer` (as a `RenderClient`) bound
26	* to the provided template.
27	*
28	* # Example
29	*
30	* ```php
31	* <?php
32	* $resolver = new TemplateResolver(
33	*     // This is the class used to instantiate new templates.
34	*     // In this case, `Templates\File` is the default so it
35	*     // could also be left unspecified.
36	*     Templates\File::class
37	* );
38	* $renderclient = Renderer::create(new Templates\File('main.php'), $resolver);
39	* ```
40	*
41	* @param Templates\Base $template The root template that the rendering process will start at.
42	*
43	* @param TemplateResolver $resolver (optional) The `TemplateResolver` that will be used to
44	*                                   resolve additional template names referenced during
45	*                                   the rendering process.
46	*/
47	public static function create(Templates\Base $template, TemplateResolver $resolver): RenderClient;
48
49	/**
50	* Set context to render the root template with.
51	*
52	* This method is used to set the data that the root template will be rendered
53	* with. Every call replaces any previous data and the template is rendered
54	* with the latest specified data.
55	*
56	* # Example
57	*
58	* ```php
59	* <?php
60	* // Example user
61	* $user = ['id' => 3, 'first' => "User", 'last' => "Name"];
62	*
63	* $renderclient = Renderer::create(new Templates\File('profile.php'));
64	* $renderclient->with(
65	*     $user,
66	*     message: "This is a profile message.",
67	* )->render();
68	* ```
69	*
70	* # Data Formats
71	*
72	* This method accepts data in multiple formats:
73	* - Named parameters
74	* - Parameter arrays
75	* - A mix of named parameters and arrays
76	*
77	* ## Named Parameters
78	*
79	* ```php
80	* <?php
81	* $renderclient->with(key1: "value1", key2: "value2", key3: 3)
82	* ```
83	*
84	* ## Parameter Arrays
85	*
86	* ```php
87	* <?php
88	* $renderclient->with(['key1' => "value1", 'key2' => "value2", 'key3' => 3])
89	* ```
90	*
91	* ```php
92	* <?php
93	* $data1 = ['key1' => "value1", 'key2' => "value2"];
94	* $data2 = ['key3' => "value3", 'key4' => 4];
95	* $renderclient->with($data1, $data2)
96	* ```
97	*
98	* ## Mixed
99	*
100	* ```php
101	* <?php
102	* $data = ['key3' => "value3", 'key4' => 4];
103	* $renderclient->with($data, key1: "value1", key2: "value2")
104	* ```
105	*
106	* @return $this Chains to self
107	*/
108	public function with(mixed ...$context): self;
109
110	/**
111	* Execute the rendering process.
112	*
113	* This method will render the base template and any templates referenced by
114	* it and output the rendered content directly.
115	*
116	* The base template will be rendered with any context data set by `with()`.
117	*
118	* @see RenderClient::with() Set the context for rendering
119	* @see RenderClient::renderToString() Alternative method to render to a string
120	*/
121	public function render(): void;
122
123	/**
124	* Execute the rendering process.
125	*
126	* This method will render the base template and any templates referenced by
127	* it and return the rendered content as a string. This method does not
128	* have any output.
129	*
130	* The base template will be rendered with any context data set by `with()`.
131	*
132	* @return string The rendered content
133	*
134	* @see RenderClient::with() Set the context for rendering
135	* @see RenderClient::render() Alternative method to output directly
136	*/
137	public function renderToString(): string;
138	}