Skip to content

Commit 4fdc4b7

Browse files
GromNaNGromNaN
committed
Implement Runtime class name convention
1 parent 36ddfc4 commit 4fdc4b7

File tree

3 files changed

+356
-6
lines changed

3 files changed

+356
-6
lines changed

‎doc/advanced.rst‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -868,7 +868,7 @@ must be autoload-able)::
868868
// implement the logic to create an instance of $class
869869
// and inject its dependencies
870870
// most of the time, it means using your dependency injection container
871-
if ('CustomRuntimeExtension' === $class) {
871+
if ('CustomTwigRuntime' === $class) {
872872
return new $class(new Rot13Provider());
873873
} else {
874874
// ...
@@ -884,9 +884,9 @@ must be autoload-able)::
884884
(``\Twig\RuntimeLoader\ContainerRuntimeLoader``).
885885

886886
It is now possible to move the runtime logic to a new
887-
``CustomRuntimeExtension`` class and use it directly in the extension::
887+
``CustomTwigRuntime`` class and use it directly in the extension::
888888

889-
class CustomRuntimeExtension
889+
class CustomTwigRuntime
890890
{
891891
private $rot13Provider;
892892

@@ -906,13 +906,19 @@ It is now possible to move the runtime logic to a new
906906
public function getFunctions()
907907
{
908908
return [
909-
new \Twig\TwigFunction('rot13', ['CustomRuntimeExtension', 'rot13']),
909+
new \Twig\TwigFunction('rot13', ['CustomTwigRuntime', 'rot13']),
910910
// or
911-
new \Twig\TwigFunction('rot13', 'CustomRuntimeExtension::rot13'),
911+
new \Twig\TwigFunction('rot13', 'CustomTwigRuntime::rot13'),
912912
];
913913
}
914914
}
915915

916+
.. note::
917+
918+
By naming the runtime with the ``Runtime`` suffix instead of ``Extension``,
919+
Twig automatically tracks updates to its source file for cache invalidation.
920+
Otherwise, you can implement the method ``getLastModified(): int``.
921+
916922
Testing an Extension
917923
--------------------
918924

‎src/Extension/AbstractExtension.php‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,17 @@ public function getOperators()
4646
public function getLastModified(): int
4747
{
4848
$filename = (new \ReflectionClass($this))->getFileName();
49+
if (!is_file($filename)) {
50+
return 0;
51+
}
4952

50-
return is_file($filename) ? filemtime($filename) : 0;
53+
$lastModified = filemtime($filename);
54+
55+
// Track modifications of the runtime class if it exists and follows the naming convention
56+
if (str_ends_with($filename, 'Extension.php') && is_file($filename = substr($filename, 0, -13) . 'Runtime.php')) {
57+
$lastModified = max($lastModified, filemtime($filename));
58+
}
59+
60+
return $lastModified;
5161
}
5262
}

‎src/Extension/EscaperRuntime.php‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
<?php
2+
3+
/*
4+
* This file is part of Twig.
5+
*
6+
* (c) Fabien Potencier
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Twig\Runtime;
13+
14+
use Twig\Error\RuntimeError;
15+
use Twig\Extension\RuntimeExtensionInterface;
16+
use Twig\Markup;
17+
18+
final class EscaperRuntime implements RuntimeExtensionInterface
19+
{
20+
/** @var array<string, callable(string $string, string $charset): string> */
21+
private $escapers = [];
22+
23+
/** @internal */
24+
public $safeClasses = [];
25+
26+
/** @internal */
27+
public $safeLookup = [];
28+
29+
public function __construct(
30+
private $charset = 'UTF-8',
31+
) {
32+
}
33+
34+
/**
35+
* Defines a new escaper to be used via the escape filter.
36+
*
37+
* @param string $strategy The strategy name that should be used as a strategy in the escape call
38+
* @param callable(string $string, string $charset): string $callable A valid PHP callable
39+
*/
40+
public function setEscaper($strategy, callable $callable)
41+
{
42+
$this->escapers[$strategy] = $callable;
43+
}
44+
45+
/**
46+
* Gets all defined escapers.
47+
*
48+
* @return array<string, callable(string $string, string $charset): string> An array of escapers
49+
*/
50+
public function getEscapers()
51+
{
52+
return $this->escapers;
53+
}
54+
55+
/**
56+
* @param array<class-string<\Stringable>, string[]> $safeClasses
57+
*/
58+
public function setSafeClasses(array $safeClasses = [])
59+
{
60+
$this->safeClasses = [];
61+
$this->safeLookup = [];
62+
foreach ($safeClasses as $class => $strategies) {
63+
$this->addSafeClass($class, $strategies);
64+
}
65+
}
66+
67+
/**
68+
* @param class-string<\Stringable> $class
69+
* @param string[] $strategies
70+
*/
71+
public function addSafeClass(string $class, array $strategies)
72+
{
73+
$class = ltrim($class, '\\');
74+
if (!isset($this->safeClasses[$class])) {
75+
$this->safeClasses[$class] = [];
76+
}
77+
$this->safeClasses[$class] = array_merge($this->safeClasses[$class], $strategies);
78+
79+
foreach ($strategies as $strategy) {
80+
$this->safeLookup[$strategy][$class] = true;
81+
}
82+
}
83+
84+
/**
85+
* Escapes a string.
86+
*
87+
* @param mixed $string The value to be escaped
88+
* @param string $strategy The escaping strategy
89+
* @param string|null $charset The charset
90+
* @param bool $autoescape Whether the function is called by the auto-escaping feature (true) or by the developer (false)
91+
*
92+
* @throws RuntimeError
93+
*/
94+
public function escape($string, string $strategy = 'html', ?string $charset = null, bool $autoescape = false)
95+
{
96+
if ($autoescape && $string instanceof Markup) {
97+
return $string;
98+
}
99+
100+
if (!\is_string($string)) {
101+
if ($string instanceof \Stringable) {
102+
if ($autoescape) {
103+
$c = \get_class($string);
104+
if (!isset($this->safeClasses[$c])) {
105+
$this->safeClasses[$c] = [];
106+
foreach (class_parents($string) + class_implements($string) as $class) {
107+
if (isset($this->safeClasses[$class])) {
108+
$this->safeClasses[$c] = array_unique(array_merge($this->safeClasses[$c], $this->safeClasses[$class]));
109+
foreach ($this->safeClasses[$class] as $s) {
110+
$this->safeLookup[$s][$c] = true;
111+
}
112+
}
113+
}
114+
}
115+
if (isset($this->safeLookup[$strategy][$c]) || isset($this->safeLookup['all'][$c])) {
116+
return (string) $string;
117+
}
118+
}
119+
120+
$string = (string) $string;
121+
} elseif (\in_array($strategy, ['html', 'js', 'css', 'html_attr', 'url'])) {
122+
// we return the input as is (which can be of any type)
123+
return $string;
124+
}
125+
}
126+
127+
if ('' === $string) {
128+
return '';
129+
}
130+
131+
$charset = $charset ?: $this->charset;
132+
133+
switch ($strategy) {
134+
case 'html':
135+
// see https://www.php.net/htmlspecialchars
136+
137+
// Using a static variable to avoid initializing the array
138+
// each time the function is called. Moving the declaration on the
139+
// top of the function slow downs other escaping strategies.
140+
static $htmlspecialcharsCharsets = [
141+
'ISO-8859-1' => true, 'ISO8859-1' => true,
142+
'ISO-8859-15' => true, 'ISO8859-15' => true,
143+
'utf-8' => true, 'UTF-8' => true,
144+
'CP866' => true, 'IBM866' => true, '866' => true,
145+
'CP1251' => true, 'WINDOWS-1251' => true, 'WIN-1251' => true,
146+
'1251' => true,
147+
'CP1252' => true, 'WINDOWS-1252' => true, '1252' => true,
148+
'KOI8-R' => true, 'KOI8-RU' => true, 'KOI8R' => true,
149+
'BIG5' => true, '950' => true,
150+
'GB2312' => true, '936' => true,
151+
'BIG5-HKSCS' => true,
152+
'SHIFT_JIS' => true, 'SJIS' => true, '932' => true,
153+
'EUC-JP' => true, 'EUCJP' => true,
154+
'ISO8859-5' => true, 'ISO-8859-5' => true, 'MACROMAN' => true,
155+
];
156+
157+
if (isset($htmlspecialcharsCharsets[$charset])) {
158+
return htmlspecialchars($string, \ENT_QUOTES | \ENT_SUBSTITUTE, $charset);
159+
}
160+
161+
if (isset($htmlspecialcharsCharsets[strtoupper($charset)])) {
162+
// cache the lowercase variant for future iterations
163+
$htmlspecialcharsCharsets[$charset] = true;
164+
165+
return htmlspecialchars($string, \ENT_QUOTES | \ENT_SUBSTITUTE, $charset);
166+
}
167+
168+
$string = $this->convertEncoding($string, 'UTF-8', $charset);
169+
$string = htmlspecialchars($string, \ENT_QUOTES | \ENT_SUBSTITUTE, 'UTF-8');
170+
171+
return iconv('UTF-8', $charset, $string);
172+
173+
case 'js':
174+
// escape all non-alphanumeric characters
175+
// into their \x or \uHHHH representations
176+
if ('UTF-8' !== $charset) {
177+
$string = $this->convertEncoding($string, 'UTF-8', $charset);
178+
}
179+
180+
if (!preg_match('//u', $string)) {
181+
throw new RuntimeError('The string to escape is not a valid UTF-8 string.');
182+
}
183+
184+
$string = preg_replace_callback('#[^a-zA-Z0-9,\._]#Su', function ($matches) {
185+
$char = $matches[0];
186+
187+
/*
188+
* A few characters have short escape sequences in JSON and JavaScript.
189+
* Escape sequences supported only by JavaScript, not JSON, are omitted.
190+
* \" is also supported but omitted, because the resulting string is not HTML safe.
191+
*/
192+
static $shortMap = [
193+
'\\' => '\\\\',
194+
'/' => '\\/',
195+
"\x08" => '\b',
196+
"\x0C" => '\f',
197+
"\x0A" => '\n',
198+
"\x0D" => '\r',
199+
"\x09" => '\t',
200+
];
201+
202+
if (isset($shortMap[$char])) {
203+
return $shortMap[$char];
204+
}
205+
206+
$codepoint = mb_ord($char, 'UTF-8');
207+
if (0x10000 > $codepoint) {
208+
return \sprintf('\u%04X', $codepoint);
209+
}
210+
211+
// Split characters outside the BMP into surrogate pairs
212+
// https://tools.ietf.org/html/rfc2781.html#section-2.1
213+
$u = $codepoint - 0x10000;
214+
$high = 0xD800 | ($u >> 10);
215+
$low = 0xDC00 | ($u & 0x3FF);
216+
217+
return \sprintf('\u%04X\u%04X', $high, $low);
218+
}, $string);
219+
220+
if ('UTF-8' !== $charset) {
221+
$string = iconv('UTF-8', $charset, $string);
222+
}
223+
224+
return $string;
225+
226+
case 'css':
227+
if ('UTF-8' !== $charset) {
228+
$string = $this->convertEncoding($string, 'UTF-8', $charset);
229+
}
230+
231+
if (!preg_match('//u', $string)) {
232+
throw new RuntimeError('The string to escape is not a valid UTF-8 string.');
233+
}
234+
235+
$string = preg_replace_callback('#[^a-zA-Z0-9]#Su', function ($matches) {
236+
$char = $matches[0];
237+
238+
return \sprintf('\\%X ', 1 === \strlen($char) ? \ord($char) : mb_ord($char, 'UTF-8'));
239+
}, $string);
240+
241+
if ('UTF-8' !== $charset) {
242+
$string = iconv('UTF-8', $charset, $string);
243+
}
244+
245+
return $string;
246+
247+
case 'html_attr':
248+
if ('UTF-8' !== $charset) {
249+
$string = $this->convertEncoding($string, 'UTF-8', $charset);
250+
}
251+
252+
if (!preg_match('//u', $string)) {
253+
throw new RuntimeError('The string to escape is not a valid UTF-8 string.');
254+
}
255+
256+
$string = preg_replace_callback('#[^a-zA-Z0-9,\.\-_]#Su', function ($matches) {
257+
/**
258+
* This function is adapted from code coming from Zend Framework.
259+
*
260+
* @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (https://www.zend.com)
261+
* @license https://framework.zend.com/license/new-bsd New BSD License
262+
*/
263+
$chr = $matches[0];
264+
$ord = \ord($chr);
265+
266+
/*
267+
* The following replaces characters undefined in HTML with the
268+
* hex entity for the Unicode replacement character.
269+
*/
270+
if (($ord <= 0x1F && "\t" != $chr && "\n" != $chr && "\r" != $chr) || ($ord >= 0x7F && $ord <= 0x9F)) {
271+
return '&#xFFFD;';
272+
}
273+
274+
/*
275+
* Check if the current character to escape has a name entity we should
276+
* replace it with while grabbing the hex value of the character.
277+
*/
278+
if (1 === \strlen($chr)) {
279+
/*
280+
* While HTML supports far more named entities, the lowest common denominator
281+
* has become HTML5's XML Serialisation which is restricted to the those named
282+
* entities that XML supports. Using HTML entities would result in this error:
283+
* XML Parsing Error: undefined entity
284+
*/
285+
static $entityMap = [
286+
34 => '&quot;', /* quotation mark */
287+
38 => '&amp;', /* ampersand */
288+
60 => '&lt;', /* less-than sign */
289+
62 => '&gt;', /* greater-than sign */
290+
];
291+
292+
if (isset($entityMap[$ord])) {
293+
return $entityMap[$ord];
294+
}
295+
296+
return \sprintf('&#x%02X;', $ord);
297+
}
298+
299+
/*
300+
* Per OWASP recommendations, we'll use hex entities for any other
301+
* characters where a named entity does not exist.
302+
*/
303+
return \sprintf('&#x%04X;', mb_ord($chr, 'UTF-8'));
304+
}, $string);
305+
306+
if ('UTF-8' !== $charset) {
307+
$string = iconv('UTF-8', $charset, $string);
308+
}
309+
310+
return $string;
311+
312+
case 'url':
313+
return rawurlencode($string);
314+
315+
default:
316+
if (\array_key_exists($strategy, $this->escapers)) {
317+
return $this->escapers[$strategy]($string, $charset);
318+
}
319+
320+
$validStrategies = implode('", "', array_merge(['html', 'js', 'url', 'css', 'html_attr'], array_keys($this->escapers)));
321+
322+
throw new RuntimeError(\sprintf('Invalid escaping strategy "%s" (valid ones: "%s").', $strategy, $validStrategies));
323+
}
324+
}
325+
326+
private function convertEncoding(string $string, string $to, string $from)
327+
{
328+
if (!\function_exists('iconv')) {
329+
throw new RuntimeError('Unable to convert encoding: required function iconv() does not exist. You should install ext-iconv or symfony/polyfill-iconv.');
330+
}
331+
332+
return iconv($from, $to, $string);
333+
}
334+
}

0 commit comments

Comments
 (0)