vendor/twig/twig/src/Extension/CoreExtension.php line 1740

Open in your IDE?
  1. <?php
  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.  */
  12. namespace Twig\Extension;
  14. use Twig\Environment;
  15. use Twig\Error\LoaderError;
  16. use Twig\Error\RuntimeError;
  17. use Twig\Error\SyntaxError;
  18. use Twig\ExpressionParser;
  19. use Twig\Markup;
  20. use Twig\Node\Expression\AbstractExpression;
  21. use Twig\Node\Expression\Binary\AddBinary;
  22. use Twig\Node\Expression\Binary\AndBinary;
  23. use Twig\Node\Expression\Binary\BitwiseAndBinary;
  24. use Twig\Node\Expression\Binary\BitwiseOrBinary;
  25. use Twig\Node\Expression\Binary\BitwiseXorBinary;
  26. use Twig\Node\Expression\Binary\ConcatBinary;
  27. use Twig\Node\Expression\Binary\DivBinary;
  28. use Twig\Node\Expression\Binary\EndsWithBinary;
  29. use Twig\Node\Expression\Binary\EqualBinary;
  30. use Twig\Node\Expression\Binary\FloorDivBinary;
  31. use Twig\Node\Expression\Binary\GreaterBinary;
  32. use Twig\Node\Expression\Binary\GreaterEqualBinary;
  33. use Twig\Node\Expression\Binary\HasEveryBinary;
  34. use Twig\Node\Expression\Binary\HasSomeBinary;
  35. use Twig\Node\Expression\Binary\InBinary;
  36. use Twig\Node\Expression\Binary\LessBinary;
  37. use Twig\Node\Expression\Binary\LessEqualBinary;
  38. use Twig\Node\Expression\Binary\MatchesBinary;
  39. use Twig\Node\Expression\Binary\ModBinary;
  40. use Twig\Node\Expression\Binary\MulBinary;
  41. use Twig\Node\Expression\Binary\NotEqualBinary;
  42. use Twig\Node\Expression\Binary\NotInBinary;
  43. use Twig\Node\Expression\Binary\OrBinary;
  44. use Twig\Node\Expression\Binary\PowerBinary;
  45. use Twig\Node\Expression\Binary\RangeBinary;
  46. use Twig\Node\Expression\Binary\SpaceshipBinary;
  47. use Twig\Node\Expression\Binary\StartsWithBinary;
  48. use Twig\Node\Expression\Binary\SubBinary;
  49. use Twig\Node\Expression\BlockReferenceExpression;
  50. use Twig\Node\Expression\Filter\DefaultFilter;
  51. use Twig\Node\Expression\FunctionNode\EnumCasesFunction;
  52. use Twig\Node\Expression\GetAttrExpression;
  53. use Twig\Node\Expression\NullCoalesceExpression;
  54. use Twig\Node\Expression\ParentExpression;
  55. use Twig\Node\Expression\Test\ConstantTest;
  56. use Twig\Node\Expression\Test\DefinedTest;
  57. use Twig\Node\Expression\Test\DivisiblebyTest;
  58. use Twig\Node\Expression\Test\EvenTest;
  59. use Twig\Node\Expression\Test\NullTest;
  60. use Twig\Node\Expression\Test\OddTest;
  61. use Twig\Node\Expression\Test\SameasTest;
  62. use Twig\Node\Expression\Unary\NegUnary;
  63. use Twig\Node\Expression\Unary\NotUnary;
  64. use Twig\Node\Expression\Unary\PosUnary;
  65. use Twig\Node\Node;
  66. use Twig\NodeVisitor\MacroAutoImportNodeVisitor;
  67. use Twig\Parser;
  68. use Twig\Source;
  69. use Twig\Template;
  70. use Twig\TemplateWrapper;
  71. use Twig\TokenParser\ApplyTokenParser;
  72. use Twig\TokenParser\BlockTokenParser;
  73. use Twig\TokenParser\DeprecatedTokenParser;
  74. use Twig\TokenParser\DoTokenParser;
  75. use Twig\TokenParser\EmbedTokenParser;
  76. use Twig\TokenParser\ExtendsTokenParser;
  77. use Twig\TokenParser\FlushTokenParser;
  78. use Twig\TokenParser\ForTokenParser;
  79. use Twig\TokenParser\FromTokenParser;
  80. use Twig\TokenParser\IfTokenParser;
  81. use Twig\TokenParser\ImportTokenParser;
  82. use Twig\TokenParser\IncludeTokenParser;
  83. use Twig\TokenParser\MacroTokenParser;
  84. use Twig\TokenParser\SetTokenParser;
  85. use Twig\TokenParser\UseTokenParser;
  86. use Twig\TokenParser\WithTokenParser;
  87. use Twig\TwigFilter;
  88. use Twig\TwigFunction;
  89. use Twig\TwigTest;
  90. use Twig\Util\CallableArgumentsExtractor;
  92. final class CoreExtension extends AbstractExtension
  93. {
  94.     private $dateFormats = ['F j, Y H:i', '%d days'];
  95.     private $numberFormat = [0, '.', ','];
  96.     private $timezone = null;
  98.     /**
  99.      * Sets the default format to be used by the date filter.
  100.      *
  101.      * @param string|null $format             The default date format string
  102.      * @param string|null $dateIntervalFormat The default date interval format string
  103.      */
  104.     public function setDateFormat($format = null, $dateIntervalFormat = null)
  105.     {
  106.         if (null !== $format) {
  107.             $this->dateFormats[0] = $format;
  108.         }
  110.         if (null !== $dateIntervalFormat) {
  111.             $this->dateFormats[1] = $dateIntervalFormat;
  112.         }
  113.     }
  115.     /**
  116.      * Gets the default format to be used by the date filter.
  117.      *
  118.      * @return array The default date format string and the default date interval format string
  119.      */
  120.     public function getDateFormat()
  121.     {
  122.         return $this->dateFormats;
  123.     }
  125.     /**
  126.      * Sets the default timezone to be used by the date filter.
  127.      *
  128.      * @param \DateTimeZone|string $timezone The default timezone string or a \DateTimeZone object
  129.      */
  130.     public function setTimezone($timezone)
  131.     {
  132.         $this->timezone = $timezone instanceof \DateTimeZone ? $timezone : new \DateTimeZone($timezone);
  133.     }
  135.     /**
  136.      * Gets the default timezone to be used by the date filter.
  137.      *
  138.      * @return \DateTimeZone The default timezone currently in use
  139.      */
  140.     public function getTimezone()
  141.     {
  142.         if (null === $this->timezone) {
  143.             $this->timezone = new \DateTimeZone(date_default_timezone_get());
  144.         }
  146.         return $this->timezone;
  147.     }
  149.     /**
  150.      * Sets the default format to be used by the number_format filter.
  151.      *
  152.      * @param int    $decimal      the number of decimal places to use
  153.      * @param string $decimalPoint the character(s) to use for the decimal point
  154.      * @param string $thousandSep  the character(s) to use for the thousands separator
  155.      */
  156.     public function setNumberFormat($decimal, $decimalPoint, $thousandSep)
  157.     {
  158.         $this->numberFormat = [$decimal, $decimalPoint, $thousandSep];
  159.     }
  161.     /**
  162.      * Get the default format used by the number_format filter.
  163.      *
  164.      * @return array The arguments for number_format()
  165.      */
  166.     public function getNumberFormat()
  167.     {
  168.         return $this->numberFormat;
  169.     }
  171.     public function getTokenParsers(): array
  172.     {
  173.         return [
  174.             new ApplyTokenParser(),
  175.             new ForTokenParser(),
  176.             new IfTokenParser(),
  177.             new ExtendsTokenParser(),
  178.             new IncludeTokenParser(),
  179.             new BlockTokenParser(),
  180.             new UseTokenParser(),
  181.             new MacroTokenParser(),
  182.             new ImportTokenParser(),
  183.             new FromTokenParser(),
  184.             new SetTokenParser(),
  185.             new FlushTokenParser(),
  186.             new DoTokenParser(),
  187.             new EmbedTokenParser(),
  188.             new WithTokenParser(),
  189.             new DeprecatedTokenParser(),
  190.         ];
  191.     }
  193.     public function getFilters(): array
  194.     {
  195.         return [
  196.             // formatting filters
  197.             new TwigFilter('date', [$this, 'formatDate']),
  198.             new TwigFilter('date_modify', [$this, 'modifyDate']),
  199.             new TwigFilter('format', [self::class, 'sprintf']),
  200.             new TwigFilter('replace', [self::class, 'replace']),
  201.             new TwigFilter('number_format', [$this, 'formatNumber']),
  202.             new TwigFilter('abs', 'abs'),
  203.             new TwigFilter('round', [self::class, 'round']),
  205.             // encoding
  206.             new TwigFilter('url_encode', [self::class, 'urlencode']),
  207.             new TwigFilter('json_encode', 'json_encode'),
  208.             new TwigFilter('convert_encoding', [self::class, 'convertEncoding']),
  210.             // string filters
  211.             new TwigFilter('title', [self::class, 'titleCase'], ['needs_charset' => true]),
  212.             new TwigFilter('capitalize', [self::class, 'capitalize'], ['needs_charset' => true]),
  213.             new TwigFilter('upper', [self::class, 'upper'], ['needs_charset' => true]),
  214.             new TwigFilter('lower', [self::class, 'lower'], ['needs_charset' => true]),
  215.             new TwigFilter('striptags', [self::class, 'striptags']),
  216.             new TwigFilter('trim', [self::class, 'trim']),
  217.             new TwigFilter('nl2br', [self::class, 'nl2br'], ['pre_escape' => 'html', 'is_safe' => ['html']]),
  218.             new TwigFilter('spaceless', [self::class, 'spaceless'], ['is_safe' => ['html'], 'deprecated' => '3.12', 'deprecating_package' => 'twig/twig']),
  220.             // array helpers
  221.             new TwigFilter('join', [self::class, 'join']),
  222.             new TwigFilter('split', [self::class, 'split'], ['needs_charset' => true]),
  223.             new TwigFilter('sort', [self::class, 'sort'], ['needs_environment' => true]),
  224.             new TwigFilter('merge', [self::class, 'merge']),
  225.             new TwigFilter('batch', [self::class, 'batch']),
  226.             new TwigFilter('column', [self::class, 'column']),
  227.             new TwigFilter('filter', [self::class, 'filter'], ['needs_environment' => true]),
  228.             new TwigFilter('map', [self::class, 'map'], ['needs_environment' => true]),
  229.             new TwigFilter('reduce', [self::class, 'reduce'], ['needs_environment' => true]),
  230.             new TwigFilter('find', [self::class, 'find'], ['needs_environment' => true]),
  232.             // string/array filters
  233.             new TwigFilter('reverse', [self::class, 'reverse'], ['needs_charset' => true]),
  234.             new TwigFilter('shuffle', [self::class, 'shuffle'], ['needs_charset' => true]),
  235.             new TwigFilter('length', [self::class, 'length'], ['needs_charset' => true]),
  236.             new TwigFilter('slice', [self::class, 'slice'], ['needs_charset' => true]),
  237.             new TwigFilter('first', [self::class, 'first'], ['needs_charset' => true]),
  238.             new TwigFilter('last', [self::class, 'last'], ['needs_charset' => true]),
  240.             // iteration and runtime
  241.             new TwigFilter('default', [self::class, 'default'], ['node_class' => DefaultFilter::class]),
  242.             new TwigFilter('keys', [self::class, 'keys']),
  243.         ];
  244.     }
  246.     public function getFunctions(): array
  247.     {
  248.         return [
  249.             new TwigFunction('parent', null, ['parser_callable' => [self::class, 'parseParentFunction']]),
  250.             new TwigFunction('block', null, ['parser_callable' => [self::class, 'parseBlockFunction']]),
  251.             new TwigFunction('attribute', null, ['parser_callable' => [self::class, 'parseAttributeFunction']]),
  252.             new TwigFunction('max', 'max'),
  253.             new TwigFunction('min', 'min'),
  254.             new TwigFunction('range', 'range'),
  255.             new TwigFunction('constant', [self::class, 'constant']),
  256.             new TwigFunction('cycle', [self::class, 'cycle']),
  257.             new TwigFunction('random', [self::class, 'random'], ['needs_charset' => true]),
  258.             new TwigFunction('date', [$this, 'convertDate']),
  259.             new TwigFunction('include', [self::class, 'include'], ['needs_environment' => true, 'needs_context' => true, 'is_safe' => ['all']]),
  260.             new TwigFunction('source', [self::class, 'source'], ['needs_environment' => true, 'is_safe' => ['all']]),
  261.             new TwigFunction('enum_cases', [self::class, 'enumCases'], ['node_class' => EnumCasesFunction::class]),
  262.         ];
  263.     }
  265.     public function getTests(): array
  266.     {
  267.         return [
  268.             new TwigTest('even', null, ['node_class' => EvenTest::class]),
  269.             new TwigTest('odd', null, ['node_class' => OddTest::class]),
  270.             new TwigTest('defined', null, ['node_class' => DefinedTest::class]),
  271.             new TwigTest('same as', null, ['node_class' => SameasTest::class, 'one_mandatory_argument' => true]),
  272.             new TwigTest('none', null, ['node_class' => NullTest::class]),
  273.             new TwigTest('null', null, ['node_class' => NullTest::class]),
  274.             new TwigTest('divisible by', null, ['node_class' => DivisiblebyTest::class, 'one_mandatory_argument' => true]),
  275.             new TwigTest('constant', null, ['node_class' => ConstantTest::class]),
  276.             new TwigTest('empty', [self::class, 'testEmpty']),
  277.             new TwigTest('iterable', 'is_iterable'),
  278.             new TwigTest('sequence', [self::class, 'testSequence']),
  279.             new TwigTest('mapping', [self::class, 'testMapping']),
  280.         ];
  281.     }
  283.     public function getNodeVisitors(): array
  284.     {
  285.         return [new MacroAutoImportNodeVisitor()];
  286.     }
  288.     public function getOperators(): array
  289.     {
  290.         return [
  291.             [
  292.                 'not' => ['precedence' => 50, 'class' => NotUnary::class],
  293.                 '-' => ['precedence' => 500, 'class' => NegUnary::class],
  294.                 '+' => ['precedence' => 500, 'class' => PosUnary::class],
  295.             ],
  296.             [
  297.                 'or' => ['precedence' => 10, 'class' => OrBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  298.                 'and' => ['precedence' => 15, 'class' => AndBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  299.                 'b-or' => ['precedence' => 16, 'class' => BitwiseOrBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  300.                 'b-xor' => ['precedence' => 17, 'class' => BitwiseXorBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  301.                 'b-and' => ['precedence' => 18, 'class' => BitwiseAndBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  302.                 '==' => ['precedence' => 20, 'class' => EqualBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  303.                 '!=' => ['precedence' => 20, 'class' => NotEqualBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  304.                 '<=>' => ['precedence' => 20, 'class' => SpaceshipBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  305.                 '<' => ['precedence' => 20, 'class' => LessBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  306.                 '>' => ['precedence' => 20, 'class' => GreaterBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  307.                 '>=' => ['precedence' => 20, 'class' => GreaterEqualBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  308.                 '<=' => ['precedence' => 20, 'class' => LessEqualBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  309.                 'not in' => ['precedence' => 20, 'class' => NotInBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  310.                 'in' => ['precedence' => 20, 'class' => InBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  311.                 'matches' => ['precedence' => 20, 'class' => MatchesBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  312.                 'starts with' => ['precedence' => 20, 'class' => StartsWithBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  313.                 'ends with' => ['precedence' => 20, 'class' => EndsWithBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  314.                 'has some' => ['precedence' => 20, 'class' => HasSomeBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  315.                 'has every' => ['precedence' => 20, 'class' => HasEveryBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  316.                 '..' => ['precedence' => 25, 'class' => RangeBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  317.                 '+' => ['precedence' => 30, 'class' => AddBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  318.                 '-' => ['precedence' => 30, 'class' => SubBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  319.                 '~' => ['precedence' => 40, 'class' => ConcatBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  320.                 '*' => ['precedence' => 60, 'class' => MulBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  321.                 '/' => ['precedence' => 60, 'class' => DivBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  322.                 '//' => ['precedence' => 60, 'class' => FloorDivBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  323.                 '%' => ['precedence' => 60, 'class' => ModBinary::class, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  324.                 'is' => ['precedence' => 100, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  325.                 'is not' => ['precedence' => 100, 'associativity' => ExpressionParser::OPERATOR_LEFT],
  326.                 '**' => ['precedence' => 200, 'class' => PowerBinary::class, 'associativity' => ExpressionParser::OPERATOR_RIGHT],
  327.                 '??' => ['precedence' => 300, 'class' => NullCoalesceExpression::class, 'associativity' => ExpressionParser::OPERATOR_RIGHT],
  328.             ],
  329.         ];
  330.     }
  332.     /**
  333.      * Cycles over a value.
  334.      *
  335.      * @param \ArrayAccess|array $values
  336.      * @param int                $position The cycle position
  337.      *
  338.      * @return string The next value in the cycle
  339.      *
  340.      * @internal
  341.      */
  342.     public static function cycle($values, $position): string
  343.     {
  344.         if (!\is_array($values) && !$values instanceof \ArrayAccess) {
  345.             return $values;
  346.         }
  348.         if (!\count($values)) {
  349.             throw new RuntimeError('The "cycle" function does not work on empty sequences/mappings.');
  350.         }
  352.         return $values[$position % \count($values)];
  353.     }
  355.     /**
  356.      * Returns a random value depending on the supplied parameter type:
  357.      * - a random item from a \Traversable or array
  358.      * - a random character from a string
  359.      * - a random integer between 0 and the integer parameter.
  360.      *
  361.      * @param \Traversable|array|int|float|string $values The values to pick a random item from
  362.      * @param int|null                            $max    Maximum value used when $values is an int
  363.      *
  364.      * @return mixed A random value from the given sequence
  365.      *
  366.      * @throws RuntimeError when $values is an empty array (does not apply to an empty string which is returned as is)
  367.      *
  368.      * @internal
  369.      */
  370.     public static function random(string $charset, $values = null, $max = null)
  371.     {
  372.         if (null === $values) {
  373.             return null === $max ? mt_rand() : mt_rand(0, (int) $max);
  374.         }
  376.         if (\is_int($values) || \is_float($values)) {
  377.             if (null === $max) {
  378.                 if ($values < 0) {
  379.                     $max = 0;
  380.                     $min = $values;
  381.                 } else {
  382.                     $max = $values;
  383.                     $min = 0;
  384.                 }
  385.             } else {
  386.                 $min = $values;
  387.             }
  389.             return mt_rand((int) $min, (int) $max);
  390.         }
  392.         if (\is_string($values)) {
  393.             if ('' === $values) {
  394.                 return '';
  395.             }
  397.             if ('UTF-8' !== $charset) {
  398.                 $values = self::convertEncoding($values, 'UTF-8', $charset);
  399.             }
  401.             // unicode version of str_split()
  402.             // split at all positions, but not after the start and not before the end
  403.             $values = preg_split('/(?<!^)(?!$)/u', $values);
  405.             if ('UTF-8' !== $charset) {
  406.                 foreach ($values as $i => $value) {
  407.                     $values[$i] = self::convertEncoding($value, $charset, 'UTF-8');
  408.                 }
  409.             }
  410.         }
  412.         if (!is_iterable($values)) {
  413.             return $values;
  414.         }
  416.         $values = self::toArray($values);
  418.         if (0 === \count($values)) {
  419.             throw new RuntimeError('The random function cannot pick from an empty sequence/mapping.');
  420.         }
  422.         return $values[array_rand($values, 1)];
  423.     }
  425.     /**
  426.      * Formats a date.
  427.      *
  428.      *   {{ post.published_at|date("m/d/Y") }}
  429.      *
  430.      * @param \DateTimeInterface|\DateInterval|string $date     A date
  431.      * @param string|null                             $format   The target format, null to use the default
  432.      * @param \DateTimeZone|string|false|null         $timezone The target timezone, null to use the default, false to leave unchanged
  433.      */
  434.     public function formatDate($date, $format = null, $timezone = null): string
  435.     {
  436.         if (null === $format) {
  437.             $formats = $this->getDateFormat();
  438.             $format = $date instanceof \DateInterval ? $formats[1] : $formats[0];
  439.         }
  441.         if ($date instanceof \DateInterval) {
  442.             return $date->format($format);
  443.         }
  445.         return $this->convertDate($date, $timezone)->format($format);
  446.     }
  448.     /**
  449.      * Returns a new date object modified.
  450.      *
  451.      *   {{ post.published_at|date_modify("-1day")|date("m/d/Y") }}
  452.      *
  453.      * @param \DateTimeInterface|string $date     A date
  454.      * @param string                    $modifier A modifier string
  455.      *
  456.      * @return \DateTime|\DateTimeImmutable
  457.      *
  458.      * @internal
  459.      */
  460.     public function modifyDate($date, $modifier)
  461.     {
  462.         return $this->convertDate($date, false)->modify($modifier);
  463.     }
  465.     /**
  466.      * Returns a formatted string.
  467.      *
  468.      * @param string|null $format
  469.      * @param ...$values
  470.      *
  471.      * @internal
  472.      */
  473.     public static function sprintf($format, ...$values): string
  474.     {
  475.         return \sprintf($format ?? '', ...$values);
  476.     }
  478.     /**
  479.      * @internal
  480.      */
  481.     public static function dateConverter(Environment $env, $date, $format = null, $timezone = null): string
  482.     {
  483.         return $env->getExtension(self::class)->formatDate($date, $format, $timezone);
  484.     }
  486.     /**
  487.      * Converts an input to a \DateTime instance.
  488.      *
  489.      *    {% if date(user.created_at) < date('+2days') %}
  490.      *      {# do something #}
  491.      *    {% endif %}
  492.      *
  493.      * @param \DateTimeInterface|string|null  $date     A date or null to use the current time
  494.      * @param \DateTimeZone|string|false|null $timezone The target timezone, null to use the default, false to leave unchanged
  495.      *
  496.      * @return \DateTime|\DateTimeImmutable
  497.      */
  498.     public function convertDate($date = null, $timezone = null)
  499.     {
  500.         // determine the timezone
  501.         if (false !== $timezone) {
  502.             if (null === $timezone) {
  503.                 $timezone = $this->getTimezone();
  504.             } elseif (!$timezone instanceof \DateTimeZone) {
  505.                 $timezone = new \DateTimeZone($timezone);
  506.             }
  507.         }
  509.         // immutable dates
  510.         if ($date instanceof \DateTimeImmutable) {
  511.             return false !== $timezone ? $date->setTimezone($timezone) : $date;
  512.         }
  514.         if ($date instanceof \DateTime) {
  515.             $date = clone $date;
  516.             if (false !== $timezone) {
  517.                 $date->setTimezone($timezone);
  518.             }
  520.             return $date;
  521.         }
  523.         if (null === $date || 'now' === $date) {
  524.             if (null === $date) {
  525.                 $date = 'now';
  526.             }
  528.             return new \DateTime($date, false !== $timezone ? $timezone : $this->getTimezone());
  529.         }
  531.         $asString = (string) $date;
  532.         if (ctype_digit($asString) || (!empty($asString) && '-' === $asString[0] && ctype_digit(substr($asString, 1)))) {
  533.             $date = new \DateTime('@'.$date);
  534.         } else {
  535.             $date = new \DateTime($date, $this->getTimezone());
  536.         }
  538.         if (false !== $timezone) {
  539.             $date->setTimezone($timezone);
  540.         }
  542.         return $date;
  543.     }
  545.     /**
  546.      * Replaces strings within a string.
  547.      *
  548.      * @param string|null        $str  String to replace in
  549.      * @param array|\Traversable $from Replace values
  550.      *
  551.      * @internal
  552.      */
  553.     public static function replace($str, $from): string
  554.     {
  555.         if (!is_iterable($from)) {
  556.             throw new RuntimeError(\sprintf('The "replace" filter expects a sequence/mapping or "Traversable" as replace values, got "%s".', \is_object($from) ? \get_class($from) : \gettype($from)));
  557.         }
  559.         return strtr($str ?? '', self::toArray($from));
  560.     }
  562.     /**
  563.      * Rounds a number.
  564.      *
  565.      * @param int|float|string|null $value     The value to round
  566.      * @param int|float             $precision The rounding precision
  567.      * @param string                $method    The method to use for rounding
  568.      *
  569.      * @return int|float The rounded number
  570.      *
  571.      * @internal
  572.      */
  573.     public static function round($value, $precision = 0, $method = 'common')
  574.     {
  575.         $value = (float) $value;
  577.         if ('common' === $method) {
  578.             return round($value, $precision);
  579.         }
  581.         if ('ceil' !== $method && 'floor' !== $method) {
  582.             throw new RuntimeError('The round filter only supports the "common", "ceil", and "floor" methods.');
  583.         }
  585.         return $method($value * 10 ** $precision) / 10 ** $precision;
  586.     }
  588.     /**
  589.      * Formats a number.
  590.      *
  591.      * All of the formatting options can be left null, in that case the defaults will
  592.      * be used. Supplying any of the parameters will override the defaults set in the
  593.      * environment object.
  594.      *
  595.      * @param mixed       $number       A float/int/string of the number to format
  596.      * @param int|null    $decimal      the number of decimal points to display
  597.      * @param string|null $decimalPoint the character(s) to use for the decimal point
  598.      * @param string|null $thousandSep  the character(s) to use for the thousands separator
  599.      */
  600.     public function formatNumber($number, $decimal = null, $decimalPoint = null, $thousandSep = null): string
  601.     {
  602.         $defaults = $this->getNumberFormat();
  603.         if (null === $decimal) {
  604.             $decimal = $defaults[0];
  605.         }
  607.         if (null === $decimalPoint) {
  608.             $decimalPoint = $defaults[1];
  609.         }
  611.         if (null === $thousandSep) {
  612.             $thousandSep = $defaults[2];
  613.         }
  615.         return number_format((float) $number, $decimal, $decimalPoint, $thousandSep);
  616.     }
  618.     /**
  619.      * URL encodes (RFC 3986) a string as a path segment or an array as a query string.
  620.      *
  621.      * @param string|array|null $url A URL or an array of query parameters
  622.      *
  623.      * @internal
  624.      */
  625.     public static function urlencode($url): string
  626.     {
  627.         if (\is_array($url)) {
  628.             return http_build_query($url, '', '&', \PHP_QUERY_RFC3986);
  629.         }
  631.         return rawurlencode($url ?? '');
  632.     }
  634.     /**
  635.      * Merges any number of arrays or Traversable objects.
  636.      *
  637.      *  {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %}
  638.      *
  639.      *  {% set items = items|merge({ 'peugeot': 'car' }, { 'banana': 'fruit' }) %}
  640.      *
  641.      *  {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'banana': 'fruit' } #}
  642.      *
  643.      * @param array|\Traversable ...$arrays Any number of arrays or Traversable objects to merge
  644.      *
  645.      * @internal
  646.      */
  647.     public static function merge(...$arrays): array
  648.     {
  649.         $result = [];
  651.         foreach ($arrays as $argNumber => $array) {
  652.             if (!is_iterable($array)) {
  653.                 throw new RuntimeError(\sprintf('The merge filter only works with sequences/mappings or "Traversable", got "%s" for argument %d.', \gettype($array), $argNumber + 1));
  654.             }
  656.             $result = array_merge($result, self::toArray($array));
  657.         }
  659.         return $result;
  660.     }
  662.     /**
  663.      * Slices a variable.
  664.      *
  665.      * @param mixed $item         A variable
  666.      * @param int   $start        Start of the slice
  667.      * @param int   $length       Size of the slice
  668.      * @param bool  $preserveKeys Whether to preserve key or not (when the input is an array)
  669.      *
  670.      * @return mixed The sliced variable
  671.      *
  672.      * @internal
  673.      */
  674.     public static function slice(string $charset, $item, $start, $length = null, $preserveKeys = false)
  675.     {
  676.         if ($item instanceof \Traversable) {
  677.             while ($item instanceof \IteratorAggregate) {
  678.                 $item = $item->getIterator();
  679.             }
  681.             if ($start >= 0 && $length >= 0 && $item instanceof \Iterator) {
  682.                 try {
  683.                     return iterator_to_array(new \LimitIterator($item, $start, $length ?? -1), $preserveKeys);
  684.                 } catch (\OutOfBoundsException $e) {
  685.                     return [];
  686.                 }
  687.             }
  689.             $item = iterator_to_array($item, $preserveKeys);
  690.         }
  692.         if (\is_array($item)) {
  693.             return \array_slice($item, $start, $length, $preserveKeys);
  694.         }
  696.         return mb_substr((string) $item, $start, $length, $charset);
  697.     }
  699.     /**
  700.      * Returns the first element of the item.
  701.      *
  702.      * @param mixed $item A variable
  703.      *
  704.      * @return mixed The first element of the item
  705.      *
  706.      * @internal
  707.      */
  708.     public static function first(string $charset, $item)
  709.     {
  710.         $elements = self::slice($charset, $item, 0, 1, false);
  712.         return \is_string($elements) ? $elements : current($elements);
  713.     }
  715.     /**
  716.      * Returns the last element of the item.
  717.      *
  718.      * @param mixed $item A variable
  719.      *
  720.      * @return mixed The last element of the item
  721.      *
  722.      * @internal
  723.      */
  724.     public static function last(string $charset, $item)
  725.     {
  726.         $elements = self::slice($charset, $item, -1, 1, false);
  728.         return \is_string($elements) ? $elements : current($elements);
  729.     }
  731.     /**
  732.      * Joins the values to a string.
  733.      *
  734.      * The separators between elements are empty strings per default, you can define them with the optional parameters.
  735.      *
  736.      *  {{ [1, 2, 3]|join(', ', ' and ') }}
  737.      *  {# returns 1, 2 and 3 #}
  738.      *
  739.      *  {{ [1, 2, 3]|join('|') }}
  740.      *  {# returns 1|2|3 #}
  741.      *
  742.      *  {{ [1, 2, 3]|join }}
  743.      *  {# returns 123 #}
  744.      *
  745.      * @param array       $value An array
  746.      * @param string      $glue  The separator
  747.      * @param string|null $and   The separator for the last pair
  748.      *
  749.      * @internal
  750.      */
  751.     public static function join($value, $glue = '', $and = null): string
  752.     {
  753.         if (!is_iterable($value)) {
  754.             $value = (array) $value;
  755.         }
  757.         $value = self::toArray($value, false);
  759.         if (0 === \count($value)) {
  760.             return '';
  761.         }
  763.         if (null === $and || $and === $glue) {
  764.             return implode($glue, $value);
  765.         }
  767.         if (1 === \count($value)) {
  768.             return $value[0];
  769.         }
  771.         return implode($glue, \array_slice($value, 0, -1)).$and.$value[\count($value) - 1];
  772.     }
  774.     /**
  775.      * Splits the string into an array.
  776.      *
  777.      *  {{ "one,two,three"|split(',') }}
  778.      *  {# returns [one, two, three] #}
  779.      *
  780.      *  {{ "one,two,three,four,five"|split(',', 3) }}
  781.      *  {# returns [one, two, "three,four,five"] #}
  782.      *
  783.      *  {{ "123"|split('') }}
  784.      *  {# returns [1, 2, 3] #}
  785.      *
  786.      *  {{ "aabbcc"|split('', 2) }}
  787.      *  {# returns [aa, bb, cc] #}
  788.      *
  789.      * @param string|null $value     A string
  790.      * @param string      $delimiter The delimiter
  791.      * @param int|null    $limit     The limit
  792.      *
  793.      * @internal
  794.      */
  795.     public static function split(string $charset, $value, $delimiter, $limit = null): array
  796.     {
  797.         $value = $value ?? '';
  799.         if ('' !== $delimiter) {
  800.             return null === $limit ? explode($delimiter, $value) : explode($delimiter, $value, $limit);
  801.         }
  803.         if ($limit <= 1) {
  804.             return preg_split('/(?<!^)(?!$)/u', $value);
  805.         }
  807.         $length = mb_strlen($value, $charset);
  808.         if ($length < $limit) {
  809.             return [$value];
  810.         }
  812.         $r = [];
  813.         for ($i = 0; $i < $length; $i += $limit) {
  814.             $r[] = mb_substr($value, $i, $limit, $charset);
  815.         }
  817.         return $r;
  818.     }
  820.     /**
  821.      * @internal
  822.      */
  823.     public static function default($value, $default = '')
  824.     {
  825.         if (self::testEmpty($value)) {
  826.             return $default;
  827.         }
  829.         return $value;
  830.     }
  832.     /**
  833.      * Returns the keys for the given array.
  834.      *
  835.      * It is useful when you want to iterate over the keys of an array:
  836.      *
  837.      *  {% for key in array|keys %}
  838.      *      {# ... #}
  839.      *  {% endfor %}
  840.      *
  841.      * @internal
  842.      */
  843.     public static function keys($array): array
  844.     {
  845.         if ($array instanceof \Traversable) {
  846.             while ($array instanceof \IteratorAggregate) {
  847.                 $array = $array->getIterator();
  848.             }
  850.             $keys = [];
  851.             if ($array instanceof \Iterator) {
  852.                 $array->rewind();
  853.                 while ($array->valid()) {
  854.                     $keys[] = $array->key();
  855.                     $array->next();
  856.                 }
  858.                 return $keys;
  859.             }
  861.             foreach ($array as $key => $item) {
  862.                 $keys[] = $key;
  863.             }
  865.             return $keys;
  866.         }
  868.         if (!\is_array($array)) {
  869.             return [];
  870.         }
  872.         return array_keys($array);
  873.     }
  875.     /**
  876.      * Reverses a variable.
  877.      *
  878.      * @param array|\Traversable|string|null $item         An array, a \Traversable instance, or a string
  879.      * @param bool                           $preserveKeys Whether to preserve key or not
  880.      *
  881.      * @return mixed The reversed input
  882.      *
  883.      * @internal
  884.      */
  885.     public static function reverse(string $charset, $item, $preserveKeys = false)
  886.     {
  887.         if ($item instanceof \Traversable) {
  888.             return array_reverse(iterator_to_array($item), $preserveKeys);
  889.         }
  891.         if (\is_array($item)) {
  892.             return array_reverse($item, $preserveKeys);
  893.         }
  895.         $string = (string) $item;
  897.         if ('UTF-8' !== $charset) {
  898.             $string = self::convertEncoding($string, 'UTF-8', $charset);
  899.         }
  901.         preg_match_all('/./us', $string, $matches);
  903.         $string = implode('', array_reverse($matches[0]));
  905.         if ('UTF-8' !== $charset) {
  906.             $string = self::convertEncoding($string, $charset, 'UTF-8');
  907.         }
  909.         return $string;
  910.     }
  912.     /**
  913.      * Shuffles an array, a \Traversable instance, or a string.
  914.      * The function does not preserve keys.
  915.      *
  916.      * @param array|\Traversable|string|null $item
  917.      *
  918.      * @return mixed
  919.      *
  920.      * @internal
  921.      */
  922.     public static function shuffle(string $charset, $item)
  923.     {
  924.         if (\is_string($item)) {
  925.             if ('UTF-8' !== $charset) {
  926.                 $item = self::convertEncoding($item, 'UTF-8', $charset);
  927.             }
  929.             $item = preg_split('/(?<!^)(?!$)/u', $item, -1);
  930.             shuffle($item);
  931.             $item = implode('', $item);
  933.             if ('UTF-8' !== $charset) {
  934.                 $item = self::convertEncoding($item, $charset, 'UTF-8');
  935.             }
  937.             return $item;
  938.         }
  940.         if (is_iterable($item)) {
  941.             $item = self::toArray($item, false);
  942.             shuffle($item);
  943.         }
  945.         return $item;
  946.     }
  948.     /**
  949.      * Sorts an array.
  950.      *
  951.      * @param array|\Traversable $array
  952.      *
  953.      * @internal
  954.      */
  955.     public static function sort(Environment $env, $array, $arrow = null): array
  956.     {
  957.         if ($array instanceof \Traversable) {
  958.             $array = iterator_to_array($array);
  959.         } elseif (!\is_array($array)) {
  960.             throw new RuntimeError(\sprintf('The sort filter only works with sequences/mappings or "Traversable", got "%s".', \gettype($array)));
  961.         }
  963.         if (null !== $arrow) {
  964.             self::checkArrowInSandbox($env, $arrow, 'sort', 'filter');
  966.             uasort($array, $arrow);
  967.         } else {
  968.             asort($array);
  969.         }
  971.         return $array;
  972.     }
  974.     /**
  975.      * @internal
  976.      */
  977.     public static function inFilter($value, $compare)
  978.     {
  979.         if ($value instanceof Markup) {
  980.             $value = (string) $value;
  981.         }
  982.         if ($compare instanceof Markup) {
  983.             $compare = (string) $compare;
  984.         }
  986.         if (\is_string($compare)) {
  987.             if (\is_string($value) || \is_int($value) || \is_float($value)) {
  988.                 return '' === $value || str_contains($compare, (string) $value);
  989.             }
  991.             return false;
  992.         }
  994.         if (!is_iterable($compare)) {
  995.             return false;
  996.         }
  998.         if (\is_object($value) || \is_resource($value)) {
  999.             if (!\is_array($compare)) {
  1000.                 foreach ($compare as $item) {
  1001.                     if ($item === $value) {
  1002.                         return true;
  1003.                     }
  1004.                 }
  1006.                 return false;
  1007.             }
  1009.             return \in_array($value, $compare, true);
  1010.         }
  1012.         foreach ($compare as $item) {
  1013.             if (0 === self::compare($value, $item)) {
  1014.                 return true;
  1015.             }
  1016.         }
  1018.         return false;
  1019.     }
  1021.     /**
  1022.      * Compares two values using a more strict version of the PHP non-strict comparison operator.
  1023.      *
  1024.      * @see https://wiki.php.net/rfc/string_to_number_comparison
  1025.      * @see https://wiki.php.net/rfc/trailing_whitespace_numerics
  1026.      *
  1027.      * @internal
  1028.      */
  1029.     public static function compare($a, $b)
  1030.     {
  1031.         // int <=> string
  1032.         if (\is_int($a) && \is_string($b)) {
  1033.             $bTrim = trim($b, " \t\n\r\v\f");
  1034.             if (!is_numeric($bTrim)) {
  1035.                 return (string) $a <=> $b;
  1036.             }
  1037.             if ((int) $bTrim == $bTrim) {
  1038.                 return $a <=> (int) $bTrim;
  1039.             } else {
  1040.                 return (float) $a <=> (float) $bTrim;
  1041.             }
  1042.         }
  1043.         if (\is_string($a) && \is_int($b)) {
  1044.             $aTrim = trim($a, " \t\n\r\v\f");
  1045.             if (!is_numeric($aTrim)) {
  1046.                 return $a <=> (string) $b;
  1047.             }
  1048.             if ((int) $aTrim == $aTrim) {
  1049.                 return (int) $aTrim <=> $b;
  1050.             } else {
  1051.                 return (float) $aTrim <=> (float) $b;
  1052.             }
  1053.         }
  1055.         // float <=> string
  1056.         if (\is_float($a) && \is_string($b)) {
  1057.             if (is_nan($a)) {
  1058.                 return 1;
  1059.             }
  1060.             $bTrim = trim($b, " \t\n\r\v\f");
  1061.             if (!is_numeric($bTrim)) {
  1062.                 return (string) $a <=> $b;
  1063.             }
  1065.             return $a <=> (float) $bTrim;
  1066.         }
  1067.         if (\is_string($a) && \is_float($b)) {
  1068.             if (is_nan($b)) {
  1069.                 return 1;
  1070.             }
  1071.             $aTrim = trim($a, " \t\n\r\v\f");
  1072.             if (!is_numeric($aTrim)) {
  1073.                 return $a <=> (string) $b;
  1074.             }
  1076.             return (float) $aTrim <=> $b;
  1077.         }
  1079.         // fallback to <=>
  1080.         return $a <=> $b;
  1081.     }
  1083.     /**
  1084.      * @throws RuntimeError When an invalid pattern is used
  1085.      *
  1086.      * @internal
  1087.      */
  1088.     public static function matches(string $regexp, ?string $str): int
  1089.     {
  1090.         set_error_handler(function ($t, $m) use ($regexp) {
  1091.             throw new RuntimeError(\sprintf('Regexp "%s" passed to "matches" is not valid', $regexp).substr($m, 12));
  1092.         });
  1093.         try {
  1094.             return preg_match($regexp, $str ?? '');
  1095.         } finally {
  1096.             restore_error_handler();
  1097.         }
  1098.     }
  1100.     /**
  1101.      * Returns a trimmed string.
  1102.      *
  1103.      * @param string|null $string
  1104.      * @param string|null $characterMask
  1105.      * @param string      $side
  1106.      *
  1107.      * @throws RuntimeError When an invalid trimming side is used (not a string or not 'left', 'right', or 'both')
  1108.      *
  1109.      * @internal
  1110.      */
  1111.     public static function trim($string, $characterMask = null, $side = 'both'): string
  1112.     {
  1113.         if (null === $characterMask) {
  1114.             $characterMask = " \t\n\r\0\x0B";
  1115.         }
  1117.         switch ($side) {
  1118.             case 'both':
  1119.                 return trim($string ?? '', $characterMask);
  1120.             case 'left':
  1121.                 return ltrim($string ?? '', $characterMask);
  1122.             case 'right':
  1123.                 return rtrim($string ?? '', $characterMask);
  1124.             default:
  1125.                 throw new RuntimeError('Trimming side must be "left", "right" or "both".');
  1126.         }
  1127.     }
  1129.     /**
  1130.      * Inserts HTML line breaks before all newlines in a string.
  1131.      *
  1132.      * @param string|null $string
  1133.      *
  1134.      * @internal
  1135.      */
  1136.     public static function nl2br($string): string
  1137.     {
  1138.         return nl2br($string ?? '');
  1139.     }
  1141.     /**
  1142.      * Removes whitespaces between HTML tags.
  1143.      *
  1144.      * @param string|null $content
  1145.      *
  1146.      * @internal
  1147.      */
  1148.     public static function spaceless($content): string
  1149.     {
  1150.         return trim(preg_replace('/>\s+</', '><', $content ?? ''));
  1151.     }
  1153.     /**
  1154.      * @param string|null $string
  1155.      * @param string      $to
  1156.      * @param string      $from
  1157.      *
  1158.      * @internal
  1159.      */
  1160.     public static function convertEncoding($string, $to, $from): string
  1161.     {
  1162.         if (!\function_exists('iconv')) {
  1163.             throw new RuntimeError('Unable to convert encoding: required function iconv() does not exist. You should install ext-iconv or symfony/polyfill-iconv.');
  1164.         }
  1166.         return iconv($from, $to, $string ?? '');
  1167.     }
  1169.     /**
  1170.      * Returns the length of a variable.
  1171.      *
  1172.      * @param mixed $thing A variable
  1173.      *
  1174.      * @internal
  1175.      */
  1176.     public static function length(string $charset, $thing): int
  1177.     {
  1178.         if (null === $thing) {
  1179.             return 0;
  1180.         }
  1182.         if (\is_scalar($thing)) {
  1183.             return mb_strlen($thing, $charset);
  1184.         }
  1186.         if ($thing instanceof \Countable || \is_array($thing) || $thing instanceof \SimpleXMLElement) {
  1187.             return \count($thing);
  1188.         }
  1190.         if ($thing instanceof \Traversable) {
  1191.             return iterator_count($thing);
  1192.         }
  1194.         if ($thing instanceof \Stringable) {
  1195.             return mb_strlen((string) $thing, $charset);
  1196.         }
  1198.         return 1;
  1199.     }
  1201.     /**
  1202.      * Converts a string to uppercase.
  1203.      *
  1204.      * @param string|null $string A string
  1205.      *
  1206.      * @internal
  1207.      */
  1208.     public static function upper(string $charset, $string): string
  1209.     {
  1210.         return mb_strtoupper($string ?? '', $charset);
  1211.     }
  1213.     /**
  1214.      * Converts a string to lowercase.
  1215.      *
  1216.      * @param string|null $string A string
  1217.      *
  1218.      * @internal
  1219.      */
  1220.     public static function lower(string $charset, $string): string
  1221.     {
  1222.         return mb_strtolower($string ?? '', $charset);
  1223.     }
  1225.     /**
  1226.      * Strips HTML and PHP tags from a string.
  1227.      *
  1228.      * @param string|null          $string
  1229.      * @param string[]|string|null $allowable_tags
  1230.      *
  1231.      * @internal
  1232.      */
  1233.     public static function striptags($string, $allowable_tags = null): string
  1234.     {
  1235.         return strip_tags($string ?? '', $allowable_tags);
  1236.     }
  1238.     /**
  1239.      * Returns a titlecased string.
  1240.      *
  1241.      * @param string|null $string A string
  1242.      *
  1243.      * @internal
  1244.      */
  1245.     public static function titleCase(string $charset, $string): string
  1246.     {
  1247.         return mb_convert_case($string ?? '', \MB_CASE_TITLE, $charset);
  1248.     }
  1250.     /**
  1251.      * Returns a capitalized string.
  1252.      *
  1253.      * @param string|null $string A string
  1254.      *
  1255.      * @internal
  1256.      */
  1257.     public static function capitalize(string $charset, $string): string
  1258.     {
  1259.         return mb_strtoupper(mb_substr($string ?? '', 0, 1, $charset), $charset).mb_strtolower(mb_substr($string ?? '', 1, null, $charset), $charset);
  1260.     }
  1262.     /**
  1263.      * @internal
  1264.      */
  1265.     public static function callMacro(Template $template, string $method, array $args, int $lineno, array $context, Source $source)
  1266.     {
  1267.         if (!method_exists($template, $method)) {
  1268.             $parent = $template;
  1269.             while ($parent = $parent->getParent($context)) {
  1270.                 if (method_exists($parent, $method)) {
  1271.                     return $parent->$method(...$args);
  1272.                 }
  1273.             }
  1275.             throw new RuntimeError(\sprintf('Macro "%s" is not defined in template "%s".', substr($method, \strlen('macro_')), $template->getTemplateName()), $lineno, $source);
  1276.         }
  1278.         return $template->$method(...$args);
  1279.     }
  1281.     /**
  1282.      * @template TSequence
  1283.      *
  1284.      * @param TSequence $seq
  1285.      *
  1286.      * @return ($seq is iterable ? TSequence : array{})
  1287.      *
  1288.      * @internal
  1289.      */
  1290.     public static function ensureTraversable($seq)
  1291.     {
  1292.         if (is_iterable($seq)) {
  1293.             return $seq;
  1294.         }
  1296.         return [];
  1297.     }
  1299.     /**
  1300.      * @internal
  1301.      */
  1302.     public static function toArray($seq, $preserveKeys = true)
  1303.     {
  1304.         if ($seq instanceof \Traversable) {
  1305.             return iterator_to_array($seq, $preserveKeys);
  1306.         }
  1308.         if (!\is_array($seq)) {
  1309.             return $seq;
  1310.         }
  1312.         return $preserveKeys ? $seq : array_values($seq);
  1313.     }
  1315.     /**
  1316.      * Checks if a variable is empty.
  1317.      *
  1318.      *    {# evaluates to true if the foo variable is null, false, or the empty string #}
  1319.      *    {% if foo is empty %}
  1320.      *        {# ... #}
  1321.      *    {% endif %}
  1322.      *
  1323.      * @param mixed $value A variable
  1324.      *
  1325.      * @internal
  1326.      */
  1327.     public static function testEmpty($value): bool
  1328.     {
  1329.         if ($value instanceof \Countable) {
  1330.             return 0 === \count($value);
  1331.         }
  1333.         if ($value instanceof \Traversable) {
  1334.             return !iterator_count($value);
  1335.         }
  1337.         if ($value instanceof \Stringable) {
  1338.             return '' === (string) $value;
  1339.         }
  1341.         return '' === $value || false === $value || null === $value || [] === $value;
  1342.     }
  1344.     /**
  1345.      * Checks if a variable is a sequence.
  1346.      *
  1347.      *    {# evaluates to true if the foo variable is a sequence #}
  1348.      *    {% if foo is sequence %}
  1349.      *        {# ... #}
  1350.      *    {% endif %}
  1351.      *
  1352.      * @param mixed $value
  1353.      *
  1354.      * @internal
  1355.      */
  1356.     public static function testSequence($value): bool
  1357.     {
  1358.         if ($value instanceof \ArrayObject) {
  1359.             $value = $value->getArrayCopy();
  1360.         }
  1362.         if ($value instanceof \Traversable) {
  1363.             $value = iterator_to_array($value);
  1364.         }
  1366.         return \is_array($value) && array_is_list($value);
  1367.     }
  1369.     /**
  1370.      * Checks if a variable is a mapping.
  1371.      *
  1372.      *    {# evaluates to true if the foo variable is a mapping #}
  1373.      *    {% if foo is mapping %}
  1374.      *        {# ... #}
  1375.      *    {% endif %}
  1376.      *
  1377.      * @param mixed $value
  1378.      *
  1379.      * @internal
  1380.      */
  1381.     public static function testMapping($value): bool
  1382.     {
  1383.         if ($value instanceof \ArrayObject) {
  1384.             $value = $value->getArrayCopy();
  1385.         }
  1387.         if ($value instanceof \Traversable) {
  1388.             $value = iterator_to_array($value);
  1389.         }
  1391.         return (\is_array($value) && !array_is_list($value)) || \is_object($value);
  1392.     }
  1394.     /**
  1395.      * Renders a template.
  1396.      *
  1397.      * @param array                        $context
  1398.      * @param string|array|TemplateWrapper $template      The template to render or an array of templates to try consecutively
  1399.      * @param array                        $variables     The variables to pass to the template
  1400.      * @param bool                         $withContext
  1401.      * @param bool                         $ignoreMissing Whether to ignore missing templates or not
  1402.      * @param bool                         $sandboxed     Whether to sandbox the template or not
  1403.      *
  1404.      * @internal
  1405.      */
  1406.     public static function include(Environment $env, $context, $template, $variables = [], $withContext = true, $ignoreMissing = false, $sandboxed = false): string
  1407.     {
  1408.         $alreadySandboxed = false;
  1409.         $sandbox = null;
  1410.         if ($withContext) {
  1411.             $variables = array_merge($context, $variables);
  1412.         }
  1414.         if ($isSandboxed = $sandboxed && $env->hasExtension(SandboxExtension::class)) {
  1415.             $sandbox = $env->getExtension(SandboxExtension::class);
  1416.             if (!$alreadySandboxed = $sandbox->isSandboxed()) {
  1417.                 $sandbox->enableSandbox();
  1418.             }
  1420.             foreach ((\is_array($template) ? $template : [$template]) as $name) {
  1421.                 // if a Template instance is passed, it might have been instantiated outside of a sandbox, check security
  1422.                 if ($name instanceof TemplateWrapper || $name instanceof Template) {
  1423.                     $name->unwrap()->checkSecurity();
  1424.                 }
  1425.             }
  1426.         }
  1428.         try {
  1429.             $loaded = null;
  1430.             try {
  1431.                 $loaded = $env->resolveTemplate($template);
  1432.             } catch (LoaderError $e) {
  1433.                 if (!$ignoreMissing) {
  1434.                     throw $e;
  1435.                 }
  1436.             }
  1438.             return $loaded ? $loaded->render($variables) : '';
  1439.         } finally {
  1440.             if ($isSandboxed && !$alreadySandboxed) {
  1441.                 $sandbox->disableSandbox();
  1442.             }
  1443.         }
  1444.     }
  1446.     /**
  1447.      * Returns a template content without rendering it.
  1448.      *
  1449.      * @param string $name          The template name
  1450.      * @param bool   $ignoreMissing Whether to ignore missing templates or not
  1451.      *
  1452.      * @internal
  1453.      */
  1454.     public static function source(Environment $env, $name, $ignoreMissing = false): string
  1455.     {
  1456.         $loader = $env->getLoader();
  1457.         try {
  1458.             return $loader->getSourceContext($name)->getCode();
  1459.         } catch (LoaderError $e) {
  1460.             if (!$ignoreMissing) {
  1461.                 throw $e;
  1462.             }
  1464.             return '';
  1465.         }
  1466.     }
  1468.     /**
  1469.      * Returns the list of cases of the enum.
  1470.      *
  1471.      * @template T of \UnitEnum
  1472.      *
  1473.      * @param class-string<T> $enum
  1474.      *
  1475.      * @return list<T>
  1476.      *
  1477.      * @internal
  1478.      */
  1479.     public static function enumCases(string $enum): array
  1480.     {
  1481.         if (!enum_exists($enum)) {
  1482.             throw new RuntimeError(\sprintf('Enum "%s" does not exist.', $enum));
  1483.         }
  1485.         return $enum::cases();
  1486.     }
  1488.     /**
  1489.      * Provides the ability to get constants from instances as well as class/global constants.
  1490.      *
  1491.      * @param string      $constant     The name of the constant
  1492.      * @param object|null $object       The object to get the constant from
  1493.      * @param bool        $checkDefined Whether to check if the constant is defined or not
  1494.      *
  1495.      * @return mixed Class constants can return many types like scalars, arrays, and
  1496.      *               objects depending on the PHP version (\BackedEnum, \UnitEnum, etc.)
  1497.      *               When $checkDefined is true, returns true when the constant is defined, false otherwise
  1498.      *
  1499.      * @internal
  1500.      */
  1501.     public static function constant($constant, $object = null, bool $checkDefined = false)
  1502.     {
  1503.         if (null !== $object) {
  1504.             if ('class' === $constant) {
  1505.                 return $checkDefined ? true : \get_class($object);
  1506.             }
  1508.             $constant = \get_class($object).'::'.$constant;
  1509.         }
  1511.         if (!\defined($constant)) {
  1512.             if ($checkDefined) {
  1513.                 return false;
  1514.             }
  1516.             if ('::class' === strtolower(substr($constant, -7))) {
  1517.                 throw new RuntimeError(\sprintf('You cannot use the Twig function "constant()" to access "%s". You could provide an object and call constant("class", $object) or use the class name directly as a string.', $constant));
  1518.             }
  1520.             throw new RuntimeError(\sprintf('Constant "%s" is undefined.', $constant));
  1521.         }
  1523.         return $checkDefined ? true : \constant($constant);
  1524.     }
  1526.     /**
  1527.      * Batches item.
  1528.      *
  1529.      * @param array $items An array of items
  1530.      * @param int   $size  The size of the batch
  1531.      * @param mixed $fill  A value used to fill missing items
  1532.      *
  1533.      * @internal
  1534.      */
  1535.     public static function batch($items, $size, $fill = null, $preserveKeys = true): array
  1536.     {
  1537.         if (!is_iterable($items)) {
  1538.             throw new RuntimeError(\sprintf('The "batch" filter expects a sequence/mapping or "Traversable", got "%s".', \is_object($items) ? \get_class($items) : \gettype($items)));
  1539.         }
  1541.         $size = (int) ceil($size);
  1543.         $result = array_chunk(self::toArray($items, $preserveKeys), $size, $preserveKeys);
  1545.         if (null !== $fill && $result) {
  1546.             $last = \count($result) - 1;
  1547.             if ($fillCount = $size - \count($result[$last])) {
  1548.                 for ($i = 0; $i < $fillCount; ++$i) {
  1549.                     $result[$last][] = $fill;
  1550.                 }
  1551.             }
  1552.         }
  1554.         return $result;
  1555.     }
  1557.     /**
  1558.      * Returns the attribute value for a given array/object.
  1559.      *
  1560.      * @param mixed  $object            The object or array from where to get the item
  1561.      * @param mixed  $item              The item to get from the array or object
  1562.      * @param array  $arguments         An array of arguments to pass if the item is an object method
  1563.      * @param string $type              The type of attribute (@see \Twig\Template constants)
  1564.      * @param bool   $isDefinedTest     Whether this is only a defined check
  1565.      * @param bool   $ignoreStrictCheck Whether to ignore the strict attribute check or not
  1566.      * @param int    $lineno            The template line where the attribute was called
  1567.      *
  1568.      * @return mixed The attribute value, or a Boolean when $isDefinedTest is true, or null when the attribute is not set and $ignoreStrictCheck is true
  1569.      *
  1570.      * @throws RuntimeError if the attribute does not exist and Twig is running in strict mode and $isDefinedTest is false
  1571.      *
  1572.      * @internal
  1573.      */
  1574.     public static function getAttribute(Environment $env, Source $source, $object, $item, array $arguments = [], $type = Template::ANY_CALL, $isDefinedTest = false, $ignoreStrictCheck = false, $sandboxed = false, int $lineno = -1)
  1575.     {
  1576.         // array
  1577.         if (Template::METHOD_CALL !== $type) {
  1578.             $arrayItem = \is_bool($item) || \is_float($item) ? (int) $item : $item;
  1580.             if (((\is_array($object) || $object instanceof \ArrayObject) && (isset($object[$arrayItem]) || \array_key_exists($arrayItem, (array) $object)))
  1581.                 || ($object instanceof \ArrayAccess && isset($object[$arrayItem]))
  1582.             ) {
  1583.                 if ($isDefinedTest) {
  1584.                     return true;
  1585.                 }
  1587.                 return $object[$arrayItem];
  1588.             }
  1590.             if (Template::ARRAY_CALL === $type || !\is_object($object)) {
  1591.                 if ($isDefinedTest) {
  1592.                     return false;
  1593.                 }
  1595.                 if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1596.                     return;
  1597.                 }
  1599.                 if ($object instanceof \ArrayAccess) {
  1600.                     $message = \sprintf('Key "%s" in object with ArrayAccess of class "%s" does not exist.', $arrayItem, \get_class($object));
  1601.                 } elseif (\is_object($object)) {
  1602.                     $message = \sprintf('Impossible to access a key "%s" on an object of class "%s" that does not implement ArrayAccess interface.', $item, \get_class($object));
  1603.                 } elseif (\is_array($object)) {
  1604.                     if (empty($object)) {
  1605.                         $message = \sprintf('Key "%s" does not exist as the sequence/mapping is empty.', $arrayItem);
  1606.                     } else {
  1607.                         $message = \sprintf('Key "%s" for sequence/mapping with keys "%s" does not exist.', $arrayItem, implode(', ', array_keys($object)));
  1608.                     }
  1609.                 } elseif (Template::ARRAY_CALL === $type) {
  1610.                     if (null === $object) {
  1611.                         $message = \sprintf('Impossible to access a key ("%s") on a null variable.', $item);
  1612.                     } else {
  1613.                         $message = \sprintf('Impossible to access a key ("%s") on a %s variable ("%s").', $item, \gettype($object), $object);
  1614.                     }
  1615.                 } elseif (null === $object) {
  1616.                     $message = \sprintf('Impossible to access an attribute ("%s") on a null variable.', $item);
  1617.                 } else {
  1618.                     $message = \sprintf('Impossible to access an attribute ("%s") on a %s variable ("%s").', $item, \gettype($object), $object);
  1619.                 }
  1621.                 throw new RuntimeError($message, $lineno, $source);
  1622.             }
  1623.         }
  1625.         if (!\is_object($object)) {
  1626.             if ($isDefinedTest) {
  1627.                 return false;
  1628.             }
  1630.             if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1631.                 return;
  1632.             }
  1634.             if (null === $object) {
  1635.                 $message = \sprintf('Impossible to invoke a method ("%s") on a null variable.', $item);
  1636.             } elseif (\is_array($object)) {
  1637.                 $message = \sprintf('Impossible to invoke a method ("%s") on a sequence/mapping.', $item);
  1638.             } else {
  1639.                 $message = \sprintf('Impossible to invoke a method ("%s") on a %s variable ("%s").', $item, \gettype($object), $object);
  1640.             }
  1642.             throw new RuntimeError($message, $lineno, $source);
  1643.         }
  1645.         if ($object instanceof Template) {
  1646.             throw new RuntimeError('Accessing \Twig\Template attributes is forbidden.', $lineno, $source);
  1647.         }
  1649.         // object property
  1650.         if (Template::METHOD_CALL !== $type) {
  1651.             if (isset($object->$item) || \array_key_exists((string) $item, (array) $object)) {
  1652.                 if ($isDefinedTest) {
  1653.                     return true;
  1654.                 }
  1656.                 if ($sandboxed) {
  1657.                     $env->getExtension(SandboxExtension::class)->checkPropertyAllowed($object, $item, $lineno, $source);
  1658.                 }
  1660.                 return $object->$item;
  1661.             }
  1662.         }
  1664.         static $cache = [];
  1666.         $class = \get_class($object);
  1668.         // object method
  1669.         // precedence: getXxx() > isXxx() > hasXxx()
  1670.         if (!isset($cache[$class])) {
  1671.             $methods = get_class_methods($object);
  1672.             sort($methods);
  1673.             $lcMethods = array_map(function ($value) { return strtr($value, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'); }, $methods);
  1674.             $classCache = [];
  1675.             foreach ($methods as $i => $method) {
  1676.                 $classCache[$method] = $method;
  1677.                 $classCache[$lcName = $lcMethods[$i]] = $method;
  1679.                 if ('g' === $lcName[0] && str_starts_with($lcName, 'get')) {
  1680.                     $name = substr($method, 3);
  1681.                     $lcName = substr($lcName, 3);
  1682.                 } elseif ('i' === $lcName[0] && str_starts_with($lcName, 'is')) {
  1683.                     $name = substr($method, 2);
  1684.                     $lcName = substr($lcName, 2);
  1685.                 } elseif ('h' === $lcName[0] && str_starts_with($lcName, 'has')) {
  1686.                     $name = substr($method, 3);
  1687.                     $lcName = substr($lcName, 3);
  1688.                     if (\in_array('is'.$lcName, $lcMethods)) {
  1689.                         continue;
  1690.                     }
  1691.                 } else {
  1692.                     continue;
  1693.                 }
  1695.                 // skip get() and is() methods (in which case, $name is empty)
  1696.                 if ($name) {
  1697.                     if (!isset($classCache[$name])) {
  1698.                         $classCache[$name] = $method;
  1699.                     }
  1701.                     if (!isset($classCache[$lcName])) {
  1702.                         $classCache[$lcName] = $method;
  1703.                     }
  1704.                 }
  1705.             }
  1706.             $cache[$class] = $classCache;
  1707.         }
  1709.         $call = false;
  1710.         if (isset($cache[$class][$item])) {
  1711.             $method = $cache[$class][$item];
  1712.         } elseif (isset($cache[$class][$lcItem = strtr($item, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')])) {
  1713.             $method = $cache[$class][$lcItem];
  1714.         } elseif (isset($cache[$class]['__call'])) {
  1715.             $method = $item;
  1716.             $call = true;
  1717.         } else {
  1718.             if ($isDefinedTest) {
  1719.                 return false;
  1720.             }
  1722.             if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1723.                 return;
  1724.             }
  1726.             throw new RuntimeError(\sprintf('Neither the property "%1$s" nor one of the methods "%1$s()", "get%1$s()"/"is%1$s()"/"has%1$s()" or "__call()" exist and have public access in class "%2$s".', $item, $class), $lineno, $source);
  1727.         }
  1729.         if ($isDefinedTest) {
  1730.             return true;
  1731.         }
  1733.         if ($sandboxed) {
  1734.             $env->getExtension(SandboxExtension::class)->checkMethodAllowed($object, $method, $lineno, $source);
  1735.         }
  1737.         // Some objects throw exceptions when they have __call, and the method we try
  1738.         // to call is not supported. If ignoreStrictCheck is true, we should return null.
  1739.         try {
  1740.             $ret = $object->$method(...$arguments);
  1741.         } catch (\BadMethodCallException $e) {
  1742.             if ($call && ($ignoreStrictCheck || !$env->isStrictVariables())) {
  1743.                 return;
  1744.             }
  1745.             throw $e;
  1746.         }
  1748.         return $ret;
  1749.     }
  1751.     /**
  1752.      * Returns the values from a single column in the input array.
  1753.      *
  1754.      * <pre>
  1755.      *  {% set items = [{ 'fruit' : 'apple'}, {'fruit' : 'orange' }] %}
  1756.      *
  1757.      *  {% set fruits = items|column('fruit') %}
  1758.      *
  1759.      *  {# fruits now contains ['apple', 'orange'] #}
  1760.      * </pre>
  1761.      *
  1762.      * @param array|\Traversable $array An array
  1763.      * @param int|string         $name  The column name
  1764.      * @param int|string|null    $index The column to use as the index/keys for the returned array
  1765.      *
  1766.      * @return array The array of values
  1767.      *
  1768.      * @internal
  1769.      */
  1770.     public static function column($array, $name, $index = null): array
  1771.     {
  1772.         if ($array instanceof \Traversable) {
  1773.             $array = iterator_to_array($array);
  1774.         } elseif (!\is_array($array)) {
  1775.             throw new RuntimeError(\sprintf('The column filter only works with sequences/mappings or "Traversable", got "%s" as first argument.', \gettype($array)));
  1776.         }
  1778.         return array_column($array, $name, $index);
  1779.     }
  1781.     /**
  1782.      * @internal
  1783.      */
  1784.     public static function filter(Environment $env, $array, $arrow)
  1785.     {
  1786.         if (!is_iterable($array)) {
  1787.             throw new RuntimeError(\sprintf('The "filter" filter expects a sequence/mapping or "Traversable", got "%s".', \is_object($array) ? \get_class($array) : \gettype($array)));
  1788.         }
  1790.         self::checkArrowInSandbox($env, $arrow, 'filter', 'filter');
  1792.         if (\is_array($array)) {
  1793.             return array_filter($array, $arrow, \ARRAY_FILTER_USE_BOTH);
  1794.         }
  1796.         // the IteratorIterator wrapping is needed as some internal PHP classes are \Traversable but do not implement \Iterator
  1797.         return new \CallbackFilterIterator(new \IteratorIterator($array), $arrow);
  1798.     }
  1800.     /**
  1801.      * @internal
  1802.      */
  1803.     public static function find(Environment $env, $array, $arrow)
  1804.     {
  1805.         self::checkArrowInSandbox($env, $arrow, 'find', 'filter');
  1807.         foreach ($array as $k => $v) {
  1808.             if ($arrow($v, $k)) {
  1809.                 return $v;
  1810.             }
  1811.         }
  1813.         return null;
  1814.     }
  1816.     /**
  1817.      * @internal
  1818.      */
  1819.     public static function map(Environment $env, $array, $arrow)
  1820.     {
  1821.         self::checkArrowInSandbox($env, $arrow, 'map', 'filter');
  1823.         $r = [];
  1824.         foreach ($array as $k => $v) {
  1825.             $r[$k] = $arrow($v, $k);
  1826.         }
  1828.         return $r;
  1829.     }
  1831.     /**
  1832.      * @internal
  1833.      */
  1834.     public static function reduce(Environment $env, $array, $arrow, $initial = null)
  1835.     {
  1836.         self::checkArrowInSandbox($env, $arrow, 'reduce', 'filter');
  1838.         if (!\is_array($array) && !$array instanceof \Traversable) {
  1839.             throw new RuntimeError(\sprintf('The "reduce" filter only works with sequences/mappings or "Traversable", got "%s" as first argument.', \gettype($array)));
  1840.         }
  1842.         $accumulator = $initial;
  1843.         foreach ($array as $key => $value) {
  1844.             $accumulator = $arrow($accumulator, $value, $key);
  1845.         }
  1847.         return $accumulator;
  1848.     }
  1850.     /**
  1851.      * @internal
  1852.      */
  1853.     public static function arraySome(Environment $env, $array, $arrow)
  1854.     {
  1855.         self::checkArrowInSandbox($env, $arrow, 'has some', 'operator');
  1857.         foreach ($array as $k => $v) {
  1858.             if ($arrow($v, $k)) {
  1859.                 return true;
  1860.             }
  1861.         }
  1863.         return false;
  1864.     }
  1866.     /**
  1867.      * @internal
  1868.      */
  1869.     public static function arrayEvery(Environment $env, $array, $arrow)
  1870.     {
  1871.         self::checkArrowInSandbox($env, $arrow, 'has every', 'operator');
  1873.         foreach ($array as $k => $v) {
  1874.             if (!$arrow($v, $k)) {
  1875.                 return false;
  1876.             }
  1877.         }
  1879.         return true;
  1880.     }
  1882.     /**
  1883.      * @internal
  1884.      */
  1885.     public static function checkArrowInSandbox(Environment $env, $arrow, $thing, $type)
  1886.     {
  1887.         if (!$arrow instanceof \Closure && $env->hasExtension(SandboxExtension::class) && $env->getExtension(SandboxExtension::class)->isSandboxed()) {
  1888.             throw new RuntimeError(\sprintf('The callable passed to the "%s" %s must be a Closure in sandbox mode.', $thing, $type));
  1889.         }
  1890.     }
  1892.     /**
  1893.      * @internal to be removed in Twig 4
  1894.      */
  1895.     public static function captureOutput(iterable $body): string
  1896.     {
  1897.         $level = ob_get_level();
  1898.         ob_start();
  1900.         try {
  1901.             foreach ($body as $data) {
  1902.                 echo $data;
  1903.             }
  1904.         } catch (\Throwable $e) {
  1905.             while (ob_get_level() > $level) {
  1906.                 ob_end_clean();
  1907.             }
  1909.             throw $e;
  1910.         }
  1912.         return ob_get_clean();
  1913.     }
  1915.     /**
  1916.      * @internal
  1917.      */
  1918.     public static function parseParentFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  1919.     {
  1920.         if (!$blockName = $parser->peekBlockStack()) {
  1921.             throw new SyntaxError('Calling the "parent" function outside of a block is forbidden.', $line, $parser->getStream()->getSourceContext());
  1922.         }
  1924.         if (!$parser->hasInheritance()) {
  1925.             throw new SyntaxError('Calling the "parent" function on a template that does not call "extends" or "use" is forbidden.', $line, $parser->getStream()->getSourceContext());
  1926.         }
  1928.         return new ParentExpression($blockName, $line);
  1929.     }
  1931.     /**
  1932.      * @internal
  1933.      */
  1934.     public static function parseBlockFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  1935.     {
  1936.         $fakeFunction = new TwigFunction('block', fn ($name, $template = null) => null);
  1937.         $args = (new CallableArgumentsExtractor($fakeNode, $fakeFunction))->extractArguments($args);
  1939.         return new BlockReferenceExpression($args[0], $args[1] ?? null, $line);
  1940.     }
  1942.     /**
  1943.      * @internal
  1944.      */
  1945.     public static function parseAttributeFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  1946.     {
  1947.         $fakeFunction = new TwigFunction('attribute', fn ($variable, $attribute, $arguments = null) => null);
  1948.         $args = (new CallableArgumentsExtractor($fakeNode, $fakeFunction))->extractArguments($args);
  1950.         return new GetAttrExpression($args[0], $args[1], $args[2] ?? null, Template::ANY_CALL, $line);
  1951.     }
  1952. }