1<?php
2declare(strict_types=1);
3
4namespace PhpTal;
5
6use Exception;
7use stdClass;
8
9/**
10 * Interface: PhpTalInterface
11 */
12interface PhpTalInterface
13{
14
15    /**
16     * Set template from file path.
17     *
18     * @param string $path filesystem path,
19     *                     or any path that will be accepted by source resolver
20     *
21     * @return $this
22     */
23    public function setTemplate(string $path): self;
24
25    /**
26     * Set template from source.
27     *
28     * Should be used only with temporary template sources.
29     * Use setTemplate() or addSourceResolver() whenever possible.
30     *
31     * @param string $src The phptal template source.
32     * @param string $path Fake and 'unique' template path.
33     *
34     * @return $this
35     */
36    public function setSource(string $src, string $path = null): self;
37
38    /**
39     * Specify where to look for templates.
40     *
41     * @param mixed $rep string or Array of repositories
42     *
43     * @return $this
44     */
45    public function setTemplateRepository($rep): self;
46
47    /**
48     * Get template repositories.
49     *
50     * @return array
51     */
52    public function getTemplateRepositories() :array;
53
54    /**
55     * Clears the template repositories.
56     *
57     * @return $this
58     */
59    public function clearTemplateRepositories(): self;
60
61    /**
62     * Specify how to look for templates.
63     *
64     * @param SourceResolverInterface $resolver instance of resolver
65     *
66     * @return $this
67     */
68    public function addSourceResolver(SourceResolverInterface $resolver): self;
69
70    /**
71     * Ignore XML/XHTML comments on parsing.
72     * Comments starting with <!--! are always stripped.
73     *
74     * @param bool $bool if true all comments are stripped during parse
75     *
76     * @return $this
77     */
78    public function stripComments(bool $bool): self;
79
80    /**
81     * Set output mode
82     * XHTML output mode will force elements like <link/>, <meta/> and <img/>, etc.
83     * to be empty and threats attributes like selected, checked to be
84     * boolean attributes.
85     *
86     * XML output mode outputs XML without such modifications
87     * and is neccessary to generate RSS feeds properly.
88     *
89     * @param int $mode (\PhpTal\PHPTAL::XML, \PhpTal\PHPTAL::XHTML or \PhpTal\PHPTAL::HTML5).
90     *
91     * @return $this
92     */
93    public function setOutputMode(int $mode): self;
94
95    /**
96     * Get output mode
97     * @see setOutputMode()
98     *
99     * @return int output mode constant
100     */
101    public function getOutputMode(): int;
102
103    /**
104     * Set input and ouput encoding. Encoding is case-insensitive.
105     *
106     * @param string $enc example: 'UTF-8'
107     *
108     * @return $this
109     */
110    public function setEncoding(string $enc): self;
111
112    /**
113     * Get input and ouput encoding.
114     *
115     * @return string
116     */
117    public function getEncoding(): string;
118
119    /**
120     * Set the storage location for intermediate PHP files.
121     * The path cannot contain characters that would be interpreted by glob() (e.g. *[]?)
122     *
123     * @param string $path Intermediate file path.
124     *
125     * @return void
126     */
127    public function setPhpCodeDestination(string $path): void;
128
129    /**
130     * Get the storage location for intermediate PHP files.
131     *
132     * @return string
133     */
134    public function getPhpCodeDestination(): string;
135
136    /**
137     * Set the file extension for intermediate PHP files.
138     *
139     * @param string $extension The file extension.
140     *
141     * @return $this
142     */
143    public function setPhpCodeExtension(string $extension): self;
144
145    /**
146     * Get the file extension for intermediate PHP files.
147     *
148     * @return string
149     */
150    public function getPhpCodeExtension(): string;
151
152    /**
153     * Flags whether to ignore intermediate php files and to
154     * reparse templates every time (if set to true).
155     *
156     * DON'T USE IN PRODUCTION - this makes PHPTAL many times slower.
157     *
158     * @param bool $bool Forced reparse state.
159     *
160     * @return $this
161     */
162    public function setForceReparse(bool $bool): self;
163
164    /**
165     * Get the value of the force reparse state.
166     *
167     * @return bool
168     */
169    public function getForceReparse(): bool;
170
171    /**
172     * Set I18N translator.
173     *
174     * This sets encoding used by the translator, so be sure to use encoding-dependent
175     * features of the translator (e.g. addDomain) _after_ calling setTranslator.
176     *
177     * @param TranslationServiceInterface $t instance
178     *
179     * @return $this
180     */
181    public function setTranslator(TranslationServiceInterface $t): self;
182
183    /**
184     * Add new prefilter to filter chain.
185     * Prefilters are called only once template is compiled.
186     *
187     * PreFilters must inherit PreFilter class.
188     * (in future this method will allow string with filter name instead of object)
189     *
190     * @param PreFilter $filter PreFilter object or name of prefilter to add
191     *
192     * @return $this
193     */
194    public function addPreFilter(PreFilter $filter): self;
195
196    /**
197     * Sets the level of recursion for template cache directories
198     *
199     * @param int $recursion_level
200     *
201     * @return $this
202     */
203    public function setSubpathRecursionLevel(int $recursion_level): self;
204
205    /**
206     * Set template post filter.
207     * It will be called every time after template generates output.
208     *
209     * See PHPTAL_PostFilter class.
210     *
211     * @param FilterInterface $filter filter instance
212     *
213     * @return PhpTalInterface
214     */
215    public function setPostFilter(FilterInterface $filter): self;
216
217    /**
218     * Register a trigger for specified phptal:id.
219     *
220     * @param string $id phptal:id to look for
221     * @param TriggerInterface $trigger
222     *
223     * @return $this
224     */
225    public function addTrigger(string $id, TriggerInterface $trigger): self;
226
227
228    /**
229     * Returns trigger for specified phptal:id.
230     *
231     * @param string $id phptal:id
232     *
233     * @return TriggerInterface|null
234     */    public function getTrigger(string $id): ?TriggerInterface;
235
236    /**
237     * Set a context variable.
238     *
239     * @see \PhpTal\PHPTAL::__set()
240     * @param string $varname name of the variable
241     * @param mixed $value value of the variable
242     *
243     * @return $this
244     */
245    public function set(string $varname, $value): self;
246
247    /**
248     * Execute the template code and return generated markup.
249     *
250     * @return string
251     */
252    public function execute(): string;
253
254    /**
255     * Execute and echo template without buffering of the output.
256     * This function does not allow postfilters nor DOCTYPE/XML declaration.
257     *
258     * @return void
259     */
260    public function echoExecute(): void;
261
262    /**
263     * This is PHPTAL's internal function that handles
264     * execution of macros from templates.
265     *
266     * $this is caller's context (the file where execution had originally started)
267     *
268     * @param string $path
269     * @param PhpTalInterface $local_tpl is PHPTAL instance of the file in which macro is defined
270     *                          (it will be different from $this if it's external macro call)
271     * @return void
272     */
273    public function executeMacroOfTemplate(string $path, PhpTalInterface $local_tpl): void;
274
275
276    /**
277     * Prepare template without executing it.
278     *
279     * @return PhpTalInterface
280     */
281    public function prepare(): self;
282
283    /**
284     * set how long compiled templates and phptal:cache files are kept
285     *
286     * @param float $days number of days
287     *
288     * @return PhpTalInterface
289     */
290    public function setCacheLifetime(float $days): self;
291
292    /**
293     * PHPTAL will scan cache and remove old files on every nth compile
294     * Set to 0 to disable cleanups
295     *
296     * @param int $n
297     *
298     * @return $this
299     */
300    public function setCachePurgeFrequency(int $n): self;
301
302    /**
303     * Removes all compiled templates from cache that
304     * are older than getCacheLifetime() days
305     *
306     * @return void
307     */
308    public function cleanUpGarbage(): void;
309
310    /**
311     * Removes content cached with phptal:cache for currently set template
312     * Must be called after setSource/setTemplate.
313     *
314     * @return void
315     */
316    public function cleanUpCache(): void;
317
318    /**
319     * Returns the path of the intermediate PHP code file.
320     *
321     * The returned file may be used to cleanup (unlink) temporary files
322     * generated by temporary templates or more simply for debug.
323     *
324     * @return string
325     */
326    public function getCodePath(): string;
327
328    /**
329     * Returns the generated template function name.
330     *
331     * @return string
332     */
333    public function getFunctionName(): string;
334
335    /**
336     * Returns template translator.
337     *
338     * @return TranslationServiceInterface|null
339     */
340    public function getTranslator(): ?TranslationServiceInterface;
341
342    /**
343     * Returns array of exceptions caught by tal:on-error attribute.
344     *
345     * @return Exception[]
346     */
347    public function getErrors(): array;
348
349    /**
350     * Public for phptal templates, private for user.
351     *
352     * @param Exception $error
353     *
354     * @return void
355     */
356    public function addError(Exception $error): void;
357
358    /**
359     * Returns current context object.
360     * Use only in Triggers.
361     *
362     * @return Context
363     */
364    public function getContext(): Context;
365
366    /**
367     * only for use in generated template code
368     *
369     * @return stdClass
370     */
371    public function getGlobalContext(): stdClass;
372
373    /**
374     * only for use in generated template code
375     *
376     * @return Context
377     */
378    public function pushContext(): Context;
379
380    /**
381     * only for use in generated template code
382     *
383     * @return Context
384     */
385    public function popContext(): Context;
386
387    /**
388     * @return SourceInterface
389     */
390    public function getSource(): SourceInterface;
391
392    /**
393     * @return PHPTAL
394     */
395    public function allowPhpModifier(): self;
396
397    /**
398     * @return PHPTAL
399     */
400    public function disallowPhpModifier(): self;
401}
402