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