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

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\DeprecatedCallableInfo;
  15. use Twig\Environment;
  16. use Twig\Error\LoaderError;
  17. use Twig\Error\RuntimeError;
  18. use Twig\Error\SyntaxError;
  19. use Twig\ExpressionParser\Infix\ArrowExpressionParser;
  20. use Twig\ExpressionParser\Infix\AssignmentExpressionParser;
  21. use Twig\ExpressionParser\Infix\BinaryOperatorExpressionParser;
  22. use Twig\ExpressionParser\Infix\ConditionalTernaryExpressionParser;
  23. use Twig\ExpressionParser\Infix\DotExpressionParser;
  24. use Twig\ExpressionParser\Infix\FilterExpressionParser;
  25. use Twig\ExpressionParser\Infix\FunctionExpressionParser;
  26. use Twig\ExpressionParser\Infix\IsExpressionParser;
  27. use Twig\ExpressionParser\Infix\IsNotExpressionParser;
  28. use Twig\ExpressionParser\Infix\SquareBracketExpressionParser;
  29. use Twig\ExpressionParser\InfixAssociativity;
  30. use Twig\ExpressionParser\PrecedenceChange;
  31. use Twig\ExpressionParser\Prefix\GroupingExpressionParser;
  32. use Twig\ExpressionParser\Prefix\LiteralExpressionParser;
  33. use Twig\ExpressionParser\Prefix\UnaryOperatorExpressionParser;
  34. use Twig\MacroNamespace;
  35. use Twig\Markup;
  36. use Twig\Node\Expression\AbstractExpression;
  37. use Twig\Node\Expression\Binary\AddBinary;
  38. use Twig\Node\Expression\Binary\AndBinary;
  39. use Twig\Node\Expression\Binary\BitwiseAndBinary;
  40. use Twig\Node\Expression\Binary\BitwiseOrBinary;
  41. use Twig\Node\Expression\Binary\BitwiseXorBinary;
  42. use Twig\Node\Expression\Binary\ConcatBinary;
  43. use Twig\Node\Expression\Binary\DivBinary;
  44. use Twig\Node\Expression\Binary\ElvisBinary;
  45. use Twig\Node\Expression\Binary\EndsWithBinary;
  46. use Twig\Node\Expression\Binary\EqualBinary;
  47. use Twig\Node\Expression\Binary\FloorDivBinary;
  48. use Twig\Node\Expression\Binary\GreaterBinary;
  49. use Twig\Node\Expression\Binary\GreaterEqualBinary;
  50. use Twig\Node\Expression\Binary\HasEveryBinary;
  51. use Twig\Node\Expression\Binary\HasSomeBinary;
  52. use Twig\Node\Expression\Binary\InBinary;
  53. use Twig\Node\Expression\Binary\LessBinary;
  54. use Twig\Node\Expression\Binary\LessEqualBinary;
  55. use Twig\Node\Expression\Binary\MatchesBinary;
  56. use Twig\Node\Expression\Binary\ModBinary;
  57. use Twig\Node\Expression\Binary\MulBinary;
  58. use Twig\Node\Expression\Binary\NotEqualBinary;
  59. use Twig\Node\Expression\Binary\NotInBinary;
  60. use Twig\Node\Expression\Binary\NotSameAsBinary;
  61. use Twig\Node\Expression\Binary\NullCoalesceBinary;
  62. use Twig\Node\Expression\Binary\OrBinary;
  63. use Twig\Node\Expression\Binary\PowerBinary;
  64. use Twig\Node\Expression\Binary\RangeBinary;
  65. use Twig\Node\Expression\Binary\SameAsBinary;
  66. use Twig\Node\Expression\Binary\SpaceshipBinary;
  67. use Twig\Node\Expression\Binary\StartsWithBinary;
  68. use Twig\Node\Expression\Binary\SubBinary;
  69. use Twig\Node\Expression\Binary\XorBinary;
  70. use Twig\Node\Expression\BlockReferenceExpression;
  71. use Twig\Node\Expression\Filter\DefaultFilter;
  72. use Twig\Node\Expression\FunctionNode\EnumCasesFunction;
  73. use Twig\Node\Expression\FunctionNode\EnumFunction;
  74. use Twig\Node\Expression\GetAttrExpression;
  75. use Twig\Node\Expression\ParentExpression;
  76. use Twig\Node\Expression\Test\ConstantTest;
  77. use Twig\Node\Expression\Test\DefinedTest;
  78. use Twig\Node\Expression\Test\DivisiblebyTest;
  79. use Twig\Node\Expression\Test\EvenTest;
  80. use Twig\Node\Expression\Test\NullTest;
  81. use Twig\Node\Expression\Test\OddTest;
  82. use Twig\Node\Expression\Test\SameasTest;
  83. use Twig\Node\Expression\Test\TrueTest;
  84. use Twig\Node\Expression\Unary\NegUnary;
  85. use Twig\Node\Expression\Unary\NotUnary;
  86. use Twig\Node\Expression\Unary\PosUnary;
  87. use Twig\Node\Expression\Unary\SpreadUnary;
  88. use Twig\Node\Node;
  89. use Twig\NodeVisitor\CorrectnessNodeVisitor;
  90. use Twig\Parser;
  91. use Twig\Sandbox\SecurityNotAllowedMethodError;
  92. use Twig\Sandbox\SecurityNotAllowedPropertyError;
  93. use Twig\Source;
  94. use Twig\Template;
  95. use Twig\TemplateWrapper;
  96. use Twig\TokenParser\ApplyTokenParser;
  97. use Twig\TokenParser\BlockTokenParser;
  98. use Twig\TokenParser\DeprecatedTokenParser;
  99. use Twig\TokenParser\DoTokenParser;
  100. use Twig\TokenParser\EmbedTokenParser;
  101. use Twig\TokenParser\ExtendsTokenParser;
  102. use Twig\TokenParser\FlushTokenParser;
  103. use Twig\TokenParser\ForTokenParser;
  104. use Twig\TokenParser\FromTokenParser;
  105. use Twig\TokenParser\GuardTokenParser;
  106. use Twig\TokenParser\IfTokenParser;
  107. use Twig\TokenParser\ImportTokenParser;
  108. use Twig\TokenParser\IncludeTokenParser;
  109. use Twig\TokenParser\MacroTokenParser;
  110. use Twig\TokenParser\SetTokenParser;
  111. use Twig\TokenParser\TypesTokenParser;
  112. use Twig\TokenParser\UseTokenParser;
  113. use Twig\TokenParser\WithTokenParser;
  114. use Twig\TwigFilter;
  115. use Twig\TwigFunction;
  116. use Twig\TwigTest;
  117. use Twig\Util\CallableArgumentsExtractor;
  119. final class CoreExtension extends AbstractExtension
  120. {
  121.     public const ARRAY_LIKE_CLASSES = [
  122.         'ArrayIterator',
  123.         'ArrayObject',
  124.         'CachingIterator',
  125.         'RecursiveArrayIterator',
  126.         'RecursiveCachingIterator',
  127.         'SplDoublyLinkedList',
  128.         'SplFixedArray',
  129.         'SplObjectStorage',
  130.         'SplQueue',
  131.         'SplStack',
  132.         'WeakMap',
  133.     ];
  135.     private const DEFAULT_TRIM_CHARS = " \t\n\r\0\x0B";
  137.     private $dateFormats = ['F j, Y H:i', '%d days'];
  138.     private $numberFormat = [0, '.', ','];
  139.     private $timezone;
  141.     /**
  142.      * Sets the default format to be used by the date filter.
  143.      *
  144.      * @param string|null $format             The default date format string
  145.      * @param string|null $dateIntervalFormat The default date interval format string
  146.      */
  147.     public function setDateFormat($format = null, $dateIntervalFormat = null): void
  148.     {
  149.         if (null !== $format) {
  150.             $this->dateFormats[0] = $format;
  151.         }
  153.         if (null !== $dateIntervalFormat) {
  154.             $this->dateFormats[1] = $dateIntervalFormat;
  155.         }
  156.     }
  158.     /**
  159.      * Gets the default format to be used by the date filter.
  160.      *
  161.      * @return array The default date format string and the default date interval format string
  162.      */
  163.     public function getDateFormat()
  164.     {
  165.         return $this->dateFormats;
  166.     }
  168.     /**
  169.      * Sets the default timezone to be used by the date filter.
  170.      *
  171.      * @param \DateTimeZone|string $timezone The default timezone string or a \DateTimeZone object
  172.      */
  173.     public function setTimezone($timezone): void
  174.     {
  175.         $this->timezone = $timezone instanceof \DateTimeZone ? $timezone : new \DateTimeZone($timezone);
  176.     }
  178.     /**
  179.      * Gets the default timezone to be used by the date filter.
  180.      *
  181.      * @return \DateTimeZone The default timezone currently in use
  182.      */
  183.     public function getTimezone()
  184.     {
  185.         if (null === $this->timezone) {
  186.             $this->timezone = new \DateTimeZone(date_default_timezone_get());
  187.         }
  189.         return $this->timezone;
  190.     }
  192.     /**
  193.      * Sets the default format to be used by the number_format filter.
  194.      *
  195.      * @param int    $decimal      the number of decimal places to use
  196.      * @param string $decimalPoint the character(s) to use for the decimal point
  197.      * @param string $thousandSep  the character(s) to use for the thousands separator
  198.      */
  199.     public function setNumberFormat($decimal, $decimalPoint, $thousandSep): void
  200.     {
  201.         $this->numberFormat = [$decimal, $decimalPoint, $thousandSep];
  202.     }
  204.     /**
  205.      * Get the default format used by the number_format filter.
  206.      *
  207.      * @return array The arguments for number_format()
  208.      */
  209.     public function getNumberFormat()
  210.     {
  211.         return $this->numberFormat;
  212.     }
  214.     public function getTokenParsers(): array
  215.     {
  216.         return [
  217.             new ApplyTokenParser(),
  218.             new ForTokenParser(),
  219.             new IfTokenParser(),
  220.             new ExtendsTokenParser(),
  221.             new IncludeTokenParser(),
  222.             new BlockTokenParser(),
  223.             new UseTokenParser(),
  224.             new MacroTokenParser(),
  225.             new ImportTokenParser(),
  226.             new FromTokenParser(),
  227.             new SetTokenParser(),
  228.             new TypesTokenParser(),
  229.             new FlushTokenParser(),
  230.             new DoTokenParser(),
  231.             new EmbedTokenParser(),
  232.             new WithTokenParser(),
  233.             new DeprecatedTokenParser(),
  234.             new GuardTokenParser(),
  235.         ];
  236.     }
  238.     public function getFilters(): array
  239.     {
  240.         return [
  241.             // formatting filters
  242.             new TwigFilter('date', [$this, 'formatDate']),
  243.             new TwigFilter('date_modify', [$this, 'modifyDate']),
  244.             new TwigFilter('format', [self::class, 'sprintf']),
  245.             new TwigFilter('replace', [self::class, 'replace']),
  246.             new TwigFilter('number_format', [$this, 'formatNumber']),
  247.             new TwigFilter('abs', 'abs'),
  248.             new TwigFilter('round', [self::class, 'round']),
  250.             // encoding
  251.             new TwigFilter('url_encode', [self::class, 'urlencode']),
  252.             new TwigFilter('json_encode', 'json_encode'),
  253.             new TwigFilter('convert_encoding', [self::class, 'convertEncoding']),
  255.             // string filters
  256.             new TwigFilter('title', [self::class, 'titleCase'], ['needs_charset' => true]),
  257.             new TwigFilter('capitalize', [self::class, 'capitalize'], ['needs_charset' => true]),
  258.             new TwigFilter('upper', [self::class, 'upper'], ['needs_charset' => true]),
  259.             new TwigFilter('lower', [self::class, 'lower'], ['needs_charset' => true]),
  260.             new TwigFilter('striptags', [self::class, 'striptags']),
  261.             new TwigFilter('trim', [self::class, 'trim']),
  262.             new TwigFilter('nl2br', [self::class, 'nl2br'], ['pre_escape' => 'html', 'is_safe' => ['html']]),
  263.             new TwigFilter('spaceless', [self::class, 'spaceless'], ['pre_escape' => 'html', 'is_safe' => ['html'], 'deprecation_info' => new DeprecatedCallableInfo('twig/twig', '3.12')]),
  265.             // array helpers
  266.             new TwigFilter('join', [self::class, 'join']),
  267.             new TwigFilter('split', [self::class, 'split'], ['needs_charset' => true]),
  268.             new TwigFilter('sort', [self::class, 'sort'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  269.             new TwigFilter('merge', [self::class, 'merge']),
  270.             new TwigFilter('batch', [self::class, 'batch']),
  271.             new TwigFilter('column', [self::class, 'column'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  272.             new TwigFilter('filter', [self::class, 'filter'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  273.             new TwigFilter('map', [self::class, 'map'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  274.             new TwigFilter('reduce', [self::class, 'reduce'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  275.             new TwigFilter('find', [self::class, 'find'], ['needs_environment' => true, 'needs_is_sandboxed' => true]),
  277.             // string/array filters
  278.             new TwigFilter('reverse', [self::class, 'reverse'], ['needs_charset' => true]),
  279.             new TwigFilter('shuffle', [self::class, 'shuffle'], ['needs_charset' => true]),
  280.             new TwigFilter('length', [self::class, 'length'], ['needs_charset' => true]),
  281.             new TwigFilter('slice', [self::class, 'slice'], ['needs_charset' => true]),
  282.             new TwigFilter('first', [self::class, 'first'], ['needs_charset' => true]),
  283.             new TwigFilter('last', [self::class, 'last'], ['needs_charset' => true]),
  285.             // iteration and runtime
  286.             new TwigFilter('default', [self::class, 'default'], ['node_class' => DefaultFilter::class]),
  287.             new TwigFilter('keys', [self::class, 'keys']),
  288.             new TwigFilter('invoke', [self::class, 'invoke']),
  289.         ];
  290.     }
  292.     public function getFunctions(): array
  293.     {
  294.         return [
  295.             new TwigFunction('parent', null, ['parser_callable' => [self::class, 'parseParentFunction']]),
  296.             new TwigFunction('block', null, ['parser_callable' => [self::class, 'parseBlockFunction']]),
  297.             new TwigFunction('attribute', null, ['parser_callable' => [self::class, 'parseAttributeFunction']]),
  298.             new TwigFunction('max', 'max'),
  299.             new TwigFunction('min', 'min'),
  300.             new TwigFunction('range', 'range'),
  301.             new TwigFunction('constant', [self::class, 'constant']),
  302.             new TwigFunction('cycle', [self::class, 'cycle']),
  303.             new TwigFunction('random', [self::class, 'random'], ['needs_charset' => true]),
  304.             new TwigFunction('date', [$this, 'convertDate']),
  305.             new TwigFunction('include', [self::class, 'include'], ['needs_environment' => true, 'needs_context' => true, 'is_safe' => ['all']]),
  306.             new TwigFunction('include_only', [self::class, 'includeOnly'], ['needs_environment' => true, 'is_safe' => ['all']]),
  307.             new TwigFunction('source', [self::class, 'source'], ['needs_environment' => true, 'is_safe' => ['all']]),
  308.             new TwigFunction('enum_cases', [self::class, 'enumCases'], ['node_class' => EnumCasesFunction::class]),
  309.             new TwigFunction('enum', [self::class, 'enum'], ['node_class' => EnumFunction::class]),
  310.         ];
  311.     }
  313.     public function getTests(): array
  314.     {
  315.         return [
  316.             new TwigTest('even', null, ['node_class' => EvenTest::class, 'always_allowed_in_sandbox' => true]),
  317.             new TwigTest('odd', null, ['node_class' => OddTest::class, 'always_allowed_in_sandbox' => true]),
  318.             new TwigTest('defined', null, ['node_class' => DefinedTest::class, 'always_allowed_in_sandbox' => true]),
  319.             new TwigTest('same as', null, ['node_class' => SameasTest::class, 'one_mandatory_argument' => true, 'always_allowed_in_sandbox' => true]),
  320.             new TwigTest('none', null, ['node_class' => NullTest::class, 'always_allowed_in_sandbox' => true]),
  321.             new TwigTest('null', null, ['node_class' => NullTest::class, 'always_allowed_in_sandbox' => true]),
  322.             new TwigTest('divisible by', null, ['node_class' => DivisiblebyTest::class, 'one_mandatory_argument' => true, 'always_allowed_in_sandbox' => true]),
  323.             new TwigTest('constant', null, ['node_class' => ConstantTest::class]),
  324.             new TwigTest('empty', [self::class, 'testEmpty'], ['always_allowed_in_sandbox' => true]),
  325.             new TwigTest('iterable', 'is_iterable', ['always_allowed_in_sandbox' => true]),
  326.             new TwigTest('sequence', [self::class, 'testSequence'], ['always_allowed_in_sandbox' => true]),
  327.             new TwigTest('mapping', [self::class, 'testMapping'], ['always_allowed_in_sandbox' => true]),
  328.             new TwigTest('true', null, ['node_class' => TrueTest::class, 'always_allowed_in_sandbox' => true]),
  329.         ];
  330.     }
  332.     public function getNodeVisitors(): array
  333.     {
  334.         return [
  335.             new CorrectnessNodeVisitor(),
  336.         ];
  337.     }
  339.     public function getExpressionParsers(): array
  340.     {
  341.         return [
  342.             // unary operators
  343.             new UnaryOperatorExpressionParser(NotUnary::class, 'not', 50, new PrecedenceChange('twig/twig', '3.15', 70)),
  344.             new UnaryOperatorExpressionParser(SpreadUnary::class, '...', 512, description: 'Spread operator', operandPrecedence: 0),
  345.             new UnaryOperatorExpressionParser(NegUnary::class, '-', 500),
  346.             new UnaryOperatorExpressionParser(PosUnary::class, '+', 500),
  348.             // binary operators
  349.             new BinaryOperatorExpressionParser(ElvisBinary::class, '?:', 5, InfixAssociativity::Right, description: 'Elvis operator (a ?: b)', aliases: ['? :']),
  350.             new BinaryOperatorExpressionParser(NullCoalesceBinary::class, '??', 300, InfixAssociativity::Right, new PrecedenceChange('twig/twig', '3.15', 5), description: 'Null coalescing operator (a ?? b)'),
  351.             new BinaryOperatorExpressionParser(OrBinary::class, 'or', 10),
  352.             new BinaryOperatorExpressionParser(XorBinary::class, 'xor', 12),
  353.             new BinaryOperatorExpressionParser(AndBinary::class, 'and', 15),
  354.             new BinaryOperatorExpressionParser(BitwiseOrBinary::class, 'b-or', 16),
  355.             new BinaryOperatorExpressionParser(BitwiseXorBinary::class, 'b-xor', 17),
  356.             new BinaryOperatorExpressionParser(BitwiseAndBinary::class, 'b-and', 18),
  357.             new BinaryOperatorExpressionParser(EqualBinary::class, '==', 20),
  358.             new BinaryOperatorExpressionParser(NotEqualBinary::class, '!=', 20),
  359.             new BinaryOperatorExpressionParser(SpaceshipBinary::class, '<=>', 20),
  360.             new BinaryOperatorExpressionParser(LessBinary::class, '<', 20),
  361.             new BinaryOperatorExpressionParser(GreaterBinary::class, '>', 20),
  362.             new BinaryOperatorExpressionParser(GreaterEqualBinary::class, '>=', 20),
  363.             new BinaryOperatorExpressionParser(LessEqualBinary::class, '<=', 20),
  364.             new BinaryOperatorExpressionParser(NotInBinary::class, 'not in', 20),
  365.             new BinaryOperatorExpressionParser(InBinary::class, 'in', 20),
  366.             new BinaryOperatorExpressionParser(MatchesBinary::class, 'matches', 20),
  367.             new BinaryOperatorExpressionParser(StartsWithBinary::class, 'starts with', 20),
  368.             new BinaryOperatorExpressionParser(EndsWithBinary::class, 'ends with', 20),
  369.             new BinaryOperatorExpressionParser(HasSomeBinary::class, 'has some', 20),
  370.             new BinaryOperatorExpressionParser(HasEveryBinary::class, 'has every', 20),
  371.             new BinaryOperatorExpressionParser(SameAsBinary::class, '===', 20),
  372.             new BinaryOperatorExpressionParser(NotSameAsBinary::class, '!==', 20),
  373.             new BinaryOperatorExpressionParser(RangeBinary::class, '..', 25),
  374.             new BinaryOperatorExpressionParser(AddBinary::class, '+', 30),
  375.             new BinaryOperatorExpressionParser(SubBinary::class, '-', 30),
  376.             new BinaryOperatorExpressionParser(ConcatBinary::class, '~', 40, precedenceChange: new PrecedenceChange('twig/twig', '3.15', 27)),
  377.             new BinaryOperatorExpressionParser(MulBinary::class, '*', 60),
  378.             new BinaryOperatorExpressionParser(DivBinary::class, '/', 60),
  379.             new BinaryOperatorExpressionParser(FloorDivBinary::class, '//', 60, description: 'Floor division'),
  380.             new BinaryOperatorExpressionParser(ModBinary::class, '%', 60),
  381.             new BinaryOperatorExpressionParser(PowerBinary::class, '**', 200, InfixAssociativity::Right, description: 'Exponentiation operator'),
  383.             // ternary operator
  384.             new ConditionalTernaryExpressionParser(),
  386.             // assignment operator
  387.             new AssignmentExpressionParser('='),
  389.             // Twig callables
  390.             new IsExpressionParser(),
  391.             new IsNotExpressionParser(),
  392.             new FilterExpressionParser(),
  393.             new FunctionExpressionParser(),
  395.             // get attribute operators
  396.             new DotExpressionParser(),
  397.             new SquareBracketExpressionParser(),
  399.             // group expression
  400.             new GroupingExpressionParser(),
  402.             // arrow function
  403.             new ArrowExpressionParser(),
  405.             // all literals
  406.             new LiteralExpressionParser(),
  407.         ];
  408.     }
  410.     /**
  411.      * Cycles over a sequence.
  412.      *
  413.      * @param array|\ArrayAccess $values   A non-empty sequence of values
  414.      * @param int<0, max>        $position The position of the value to return in the cycle
  415.      *
  416.      * @return mixed The value at the given position in the sequence, wrapping around as needed
  417.      *
  418.      * @internal
  419.      */
  420.     public static function cycle($values, $position): mixed
  421.     {
  422.         if (!\is_array($values)) {
  423.             if (!$values instanceof \ArrayAccess) {
  424.                 throw new RuntimeError('The "cycle" function expects an array or "ArrayAccess" as first argument.');
  425.             }
  427.             if (!is_countable($values)) {
  428.                 // To be uncommented in 4.0
  429.                 // throw new RuntimeError('The "cycle" function expects a countable sequence as first argument.');
  431.                 trigger_deprecation('twig/twig', '3.12', 'Passing a non-countable sequence of values to "%s()" is deprecated.', __METHOD__);
  433.                 $values = self::toArray($values, false);
  434.             }
  435.         }
  437.         if (!$count = \count($values)) {
  438.             throw new RuntimeError('The "cycle" function expects a non-empty sequence.');
  439.         }
  441.         return $values[$position % $count];
  442.     }
  444.     /**
  445.      * Returns a random value depending on the supplied parameter type:
  446.      * - a random item from a \Traversable or array
  447.      * - a random character from a string
  448.      * - a random integer between 0 and the integer parameter.
  449.      *
  450.      * @param \Traversable|array|int|float|string $values The values to pick a random item from
  451.      * @param int|null                            $max    Maximum value used when $values is an int
  452.      *
  453.      * @return mixed A random value from the given sequence
  454.      *
  455.      * @throws RuntimeError when $values is an empty array (does not apply to an empty string which is returned as is)
  456.      *
  457.      * @internal
  458.      */
  459.     public static function random(string $charset, $values = null, $max = null)
  460.     {
  461.         if (null === $values) {
  462.             return null === $max ? mt_rand() : mt_rand(0, (int) $max);
  463.         }
  465.         if (\is_int($values) || \is_float($values)) {
  466.             if (null === $max) {
  467.                 if ($values < 0) {
  468.                     $max = 0;
  469.                     $min = $values;
  470.                 } else {
  471.                     $max = $values;
  472.                     $min = 0;
  473.                 }
  474.             } else {
  475.                 $min = $values;
  476.             }
  478.             return mt_rand((int) $min, (int) $max);
  479.         }
  481.         if (\is_string($values)) {
  482.             if ('' === $values) {
  483.                 return '';
  484.             }
  486.             if ('UTF-8' !== $charset) {
  487.                 $values = self::convertEncoding($values, 'UTF-8', $charset);
  488.             }
  490.             $values = self::splitIntoCharacters($values, 'random');
  492.             if ('UTF-8' !== $charset) {
  493.                 foreach ($values as $i => $value) {
  494.                     $values[$i] = self::convertEncoding($value, $charset, 'UTF-8');
  495.                 }
  496.             }
  497.         }
  499.         if (!is_iterable($values)) {
  500.             return $values;
  501.         }
  503.         $values = self::toArray($values);
  505.         if (0 === \count($values)) {
  506.             throw new RuntimeError('The "random" function cannot pick from an empty sequence or mapping.');
  507.         }
  509.         return $values[array_rand($values, 1)];
  510.     }
  512.     /**
  513.      * Formats a date.
  514.      *
  515.      *   {{ post.published_at|date("m/d/Y") }}
  516.      *
  517.      * @param \DateTimeInterface|\DateInterval|string|int|null $date     A date, a timestamp or null to use the current time
  518.      * @param string|null                                      $format   The target format, null to use the default
  519.      * @param \DateTimeZone|string|false|null                  $timezone The target timezone, null to use the default, false to leave unchanged
  520.      */
  521.     public function formatDate($date, $format = null, $timezone = null): string
  522.     {
  523.         if (null === $format) {
  524.             $formats = $this->getDateFormat();
  525.             $format = $date instanceof \DateInterval ? $formats[1] : $formats[0];
  526.         }
  528.         if ($date instanceof \DateInterval) {
  529.             return $date->format($format);
  530.         }
  532.         return $this->convertDate($date, $timezone)->format($format);
  533.     }
  535.     /**
  536.      * Returns a new date object modified.
  537.      *
  538.      *   {{ post.published_at|date_modify("-1day")|date("m/d/Y") }}
  539.      *
  540.      * @param \DateTimeInterface|string|int|null $date     A date, a timestamp or null to use the current time
  541.      * @param string                             $modifier A modifier string
  542.      *
  543.      * @return \DateTime|\DateTimeImmutable
  544.      *
  545.      * @internal
  546.      */
  547.     public function modifyDate($date, $modifier)
  548.     {
  549.         return $this->convertDate($date, false)->modify($modifier);
  550.     }
  552.     /**
  553.      * Returns a formatted string.
  554.      *
  555.      * @param string|null $format
  556.      *
  557.      * @internal
  558.      */
  559.     public static function sprintf($format, ...$values): string
  560.     {
  561.         return \sprintf($format ?? '', ...$values);
  562.     }
  564.     /**
  565.      * @internal
  566.      */
  567.     public static function dateConverter(Environment $env, $date, $format = null, $timezone = null): string
  568.     {
  569.         return $env->getExtension(self::class)->formatDate($date, $format, $timezone);
  570.     }
  572.     /**
  573.      * Converts an input to a \DateTime instance.
  574.      *
  575.      *    {% if date(user.created_at) < date('+2days') %}
  576.      *      {# do something #}
  577.      *    {% endif %}
  578.      *
  579.      * @param \DateTimeInterface|string|int|null $date     A date, a timestamp or null to use the current time
  580.      * @param \DateTimeZone|string|false|null    $timezone The target timezone, null to use the default, false to leave unchanged
  581.      *
  582.      * @return \DateTime|\DateTimeImmutable
  583.      */
  584.     public function convertDate($date = null, $timezone = null)
  585.     {
  586.         // determine the timezone
  587.         if (false !== $timezone) {
  588.             if (null === $timezone) {
  589.                 $timezone = $this->getTimezone();
  590.             } elseif (!$timezone instanceof \DateTimeZone) {
  591.                 $timezone = new \DateTimeZone($timezone);
  592.             }
  593.         }
  595.         // immutable dates
  596.         if ($date instanceof \DateTimeImmutable) {
  597.             return false !== $timezone ? $date->setTimezone($timezone) : $date;
  598.         }
  600.         if ($date instanceof \DateTime) {
  601.             $date = clone $date;
  602.             if (false !== $timezone) {
  603.                 $date->setTimezone($timezone);
  604.             }
  606.             return $date;
  607.         }
  609.         if (null === $date || 'now' === $date) {
  610.             if (null === $date) {
  611.                 $date = 'now';
  612.             }
  614.             return new \DateTime($date, false !== $timezone ? $timezone : $this->getTimezone());
  615.         }
  617.         $asString = (string) $date;
  618.         if (ctype_digit($asString) || ('' !== $asString && '-' === $asString[0] && ctype_digit(substr($asString, 1)))) {
  619.             $date = new \DateTime('@'.$date);
  620.         } else {
  621.             $date = new \DateTime($date);
  622.         }
  624.         if (false !== $timezone) {
  625.             $date->setTimezone($timezone);
  626.         }
  628.         return $date;
  629.     }
  631.     /**
  632.      * Replaces strings within a string.
  633.      *
  634.      * @param string|null        $str  String to replace in
  635.      * @param array|\Traversable $from Replace values
  636.      *
  637.      * @internal
  638.      */
  639.     public static function replace($str, $from): string
  640.     {
  641.         if (!is_iterable($from)) {
  642.             throw new RuntimeError(\sprintf('The "replace" filter expects a sequence or a mapping, got "%s".', get_debug_type($from)));
  643.         }
  645.         return strtr($str ?? '', self::toArray($from));
  646.     }
  648.     /**
  649.      * Rounds a number.
  650.      *
  651.      * @param int|float|string|null   $value     The value to round
  652.      * @param int|float               $precision The rounding precision
  653.      * @param 'common'|'ceil'|'floor' $method    The method to use for rounding
  654.      *
  655.      * @return float The rounded number
  656.      *
  657.      * @internal
  658.      */
  659.     public static function round($value, $precision = 0, $method = 'common')
  660.     {
  661.         $value = (float) $value;
  663.         if ('common' === $method) {
  664.             return round($value, $precision);
  665.         }
  667.         if ('ceil' !== $method && 'floor' !== $method) {
  668.             throw new RuntimeError('The "round" filter only supports the "common", "ceil", and "floor" methods.');
  669.         }
  671.         return $method($value * 10 ** $precision) / 10 ** $precision;
  672.     }
  674.     /**
  675.      * Formats a number.
  676.      *
  677.      * All of the formatting options can be left null, in that case the defaults will
  678.      * be used. Supplying any of the parameters will override the defaults set in the
  679.      * environment object.
  680.      *
  681.      * @param mixed       $number       A float/int/string of the number to format
  682.      * @param int|null    $decimal      the number of decimal points to display
  683.      * @param string|null $decimalPoint the character(s) to use for the decimal point
  684.      * @param string|null $thousandSep  the character(s) to use for the thousands separator
  685.      */
  686.     public function formatNumber($number, $decimal = null, $decimalPoint = null, $thousandSep = null): string
  687.     {
  688.         $defaults = $this->getNumberFormat();
  689.         if (null === $decimal) {
  690.             $decimal = $defaults[0];
  691.         }
  693.         if (null === $decimalPoint) {
  694.             $decimalPoint = $defaults[1];
  695.         }
  697.         if (null === $thousandSep) {
  698.             $thousandSep = $defaults[2];
  699.         }
  701.         return number_format((float) $number, $decimal, $decimalPoint, $thousandSep);
  702.     }
  704.     /**
  705.      * URL encodes (RFC 3986) a string as a path segment or an array as a query string.
  706.      *
  707.      * @param string|array|null $url A URL or an array of query parameters
  708.      *
  709.      * @internal
  710.      */
  711.     public static function urlencode($url): string
  712.     {
  713.         if (\is_array($url)) {
  714.             return http_build_query($url, '', '&', \PHP_QUERY_RFC3986);
  715.         }
  717.         return rawurlencode($url ?? '');
  718.     }
  720.     /**
  721.      * Merges any number of arrays or Traversable objects.
  722.      *
  723.      *  {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %}
  724.      *
  725.      *  {% set items = items|merge({ 'peugeot': 'car' }, { 'banana': 'fruit' }) %}
  726.      *
  727.      *  {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'banana': 'fruit' } #}
  728.      *
  729.      * @param array|\Traversable ...$arrays Any number of arrays or Traversable objects to merge
  730.      *
  731.      * @internal
  732.      */
  733.     public static function merge(...$arrays): array
  734.     {
  735.         $result = [];
  737.         foreach ($arrays as $argNumber => $array) {
  738.             if (!is_iterable($array)) {
  739.                 throw new RuntimeError(\sprintf('The "merge" filter expects a sequence or a mapping, got "%s" for argument %d.', get_debug_type($array), $argNumber + 1));
  740.             }
  742.             $result = array_merge($result, self::toArray($array));
  743.         }
  745.         return $result;
  746.     }
  748.     /**
  749.      * Slices a variable.
  750.      *
  751.      * @param mixed $item         A variable
  752.      * @param int   $start        Start of the slice
  753.      * @param int   $length       Size of the slice
  754.      * @param bool  $preserveKeys Whether to preserve key or not (when the input is an array)
  755.      *
  756.      * @return mixed The sliced variable
  757.      *
  758.      * @internal
  759.      */
  760.     public static function slice(string $charset, $item, $start, $length = null, $preserveKeys = false)
  761.     {
  762.         if ($item instanceof \Traversable) {
  763.             while ($item instanceof \IteratorAggregate) {
  764.                 $item = $item->getIterator();
  765.             }
  767.             if ($start >= 0 && $length >= 0 && $item instanceof \Iterator) {
  768.                 try {
  769.                     return iterator_to_array(new \LimitIterator($item, $start, $length ?? -1), $preserveKeys);
  770.                 } catch (\OutOfBoundsException $e) {
  771.                     return [];
  772.                 }
  773.             }
  775.             $item = iterator_to_array($item, $preserveKeys);
  776.         }
  778.         if (\is_array($item)) {
  779.             return \array_slice($item, $start, $length, $preserveKeys);
  780.         }
  782.         return mb_substr((string) $item, $start, $length, $charset);
  783.     }
  785.     /**
  786.      * Returns the first element of the item.
  787.      *
  788.      * @param mixed $item A variable
  789.      *
  790.      * @return mixed The first element of the item
  791.      *
  792.      * @internal
  793.      */
  794.     public static function first(string $charset, $item)
  795.     {
  796.         $elements = self::slice($charset, $item, 0, 1, false);
  798.         return \is_string($elements) ? $elements : current($elements);
  799.     }
  801.     /**
  802.      * Returns the last element of the item.
  803.      *
  804.      * @param mixed $item A variable
  805.      *
  806.      * @return mixed The last element of the item
  807.      *
  808.      * @internal
  809.      */
  810.     public static function last(string $charset, $item)
  811.     {
  812.         $elements = self::slice($charset, $item, -1, 1, false);
  814.         return \is_string($elements) ? $elements : current($elements);
  815.     }
  817.     /**
  818.      * Joins the values to a string.
  819.      *
  820.      * The separators between elements are empty strings per default, you can define them with the optional parameters.
  821.      *
  822.      *  {{ [1, 2, 3]|join(', ', ' and ') }}
  823.      *  {# returns 1, 2 and 3 #}
  824.      *
  825.      *  {{ [1, 2, 3]|join('|') }}
  826.      *  {# returns 1|2|3 #}
  827.      *
  828.      *  {{ [1, 2, 3]|join }}
  829.      *  {# returns 123 #}
  830.      *
  831.      * @param iterable|array|string|float|int|bool|null $value An array
  832.      * @param string                                    $glue  The separator
  833.      * @param string|null                               $and   The separator for the last pair
  834.      *
  835.      * @internal
  836.      */
  837.     public static function join($value, $glue = '', $and = null): string
  838.     {
  839.         if (!is_iterable($value)) {
  840.             $value = (array) $value;
  841.         }
  843.         $value = self::toArray($value, false);
  845.         if (0 === \count($value)) {
  846.             return '';
  847.         }
  849.         if (null === $and || $and === $glue) {
  850.             return implode($glue, $value);
  851.         }
  853.         if (1 === \count($value)) {
  854.             return $value[0];
  855.         }
  857.         return implode($glue, \array_slice($value, 0, -1)).$and.$value[\count($value) - 1];
  858.     }
  860.     /**
  861.      * Splits the string into an array.
  862.      *
  863.      *  {{ "one,two,three"|split(',') }}
  864.      *  {# returns [one, two, three] #}
  865.      *
  866.      *  {{ "one,two,three,four,five"|split(',', 3) }}
  867.      *  {# returns [one, two, "three,four,five"] #}
  868.      *
  869.      *  {{ "123"|split('') }}
  870.      *  {# returns [1, 2, 3] #}
  871.      *
  872.      *  {{ "aabbcc"|split('', 2) }}
  873.      *  {# returns [aa, bb, cc] #}
  874.      *
  875.      * @param string|null $value     A string
  876.      * @param string      $delimiter The delimiter
  877.      * @param int|null    $limit     The limit
  878.      *
  879.      * @internal
  880.      */
  881.     public static function split(string $charset, $value, $delimiter, $limit = null): array
  882.     {
  883.         $value = $value ?? '';
  885.         if ('' !== $delimiter) {
  886.             return null === $limit ? explode($delimiter, $value) : explode($delimiter, $value, $limit);
  887.         }
  889.         if ($limit <= 1) {
  890.             return self::splitIntoCharacters($value, 'split');
  891.         }
  893.         $length = mb_strlen($value, $charset);
  894.         if ($length < $limit) {
  895.             return [$value];
  896.         }
  898.         $r = [];
  899.         for ($i = 0; $i < $length; $i += $limit) {
  900.             $r[] = mb_substr($value, $i, $limit, $charset);
  901.         }
  903.         return $r;
  904.     }
  906.     /**
  907.      * @internal
  908.      */
  909.     public static function default($value, $default = '')
  910.     {
  911.         if (self::testEmpty($value)) {
  912.             return $default;
  913.         }
  915.         return $value;
  916.     }
  918.     /**
  919.      * Returns the keys for the given array.
  920.      *
  921.      * It is useful when you want to iterate over the keys of an array:
  922.      *
  923.      *  {% for key in array|keys %}
  924.      *      {# ... #}
  925.      *  {% endfor %}
  926.      *
  927.      * @internal
  928.      */
  929.     public static function keys($array): array
  930.     {
  931.         if ($array instanceof \Traversable) {
  932.             while ($array instanceof \IteratorAggregate) {
  933.                 $array = $array->getIterator();
  934.             }
  936.             $keys = [];
  937.             if ($array instanceof \Iterator) {
  938.                 $array->rewind();
  939.                 while ($array->valid()) {
  940.                     $keys[] = $array->key();
  941.                     $array->next();
  942.                 }
  944.                 return $keys;
  945.             }
  947.             foreach ($array as $key => $item) {
  948.                 $keys[] = $key;
  949.             }
  951.             return $keys;
  952.         }
  954.         if (!\is_array($array)) {
  955.             return [];
  956.         }
  958.         return array_keys($array);
  959.     }
  961.     /**
  962.      * Invokes a callable.
  963.      *
  964.      * @internal
  965.      */
  966.     public static function invoke(\Closure $arrow, ...$arguments): mixed
  967.     {
  968.         return $arrow(...$arguments);
  969.     }
  971.     /**
  972.      * Reverses a variable.
  973.      *
  974.      * @param array|\Traversable|string|null $item         An array, a \Traversable instance, or a string
  975.      * @param bool                           $preserveKeys Whether to preserve key or not
  976.      *
  977.      * @return mixed The reversed input
  978.      *
  979.      * @internal
  980.      */
  981.     public static function reverse(string $charset, $item, $preserveKeys = false)
  982.     {
  983.         if ($item instanceof \Traversable) {
  984.             return array_reverse(iterator_to_array($item), $preserveKeys);
  985.         }
  987.         if (\is_array($item)) {
  988.             return array_reverse($item, $preserveKeys);
  989.         }
  991.         $string = (string) $item;
  993.         if ('UTF-8' !== $charset) {
  994.             $string = self::convertEncoding($string, 'UTF-8', $charset);
  995.         }
  997.         $string = implode('', array_reverse(self::splitIntoCharacters($string, 'reverse')));
  999.         if ('UTF-8' !== $charset) {
  1000.             $string = self::convertEncoding($string, $charset, 'UTF-8');
  1001.         }
  1003.         return $string;
  1004.     }
  1006.     /**
  1007.      * Shuffles an array, a \Traversable instance, or a string.
  1008.      * The function does not preserve keys.
  1009.      *
  1010.      * @param array|\Traversable|string|null $item
  1011.      *
  1012.      * @internal
  1013.      */
  1014.     public static function shuffle(string $charset, $item)
  1015.     {
  1016.         if (\is_string($item)) {
  1017.             if ('UTF-8' !== $charset) {
  1018.                 $item = self::convertEncoding($item, 'UTF-8', $charset);
  1019.             }
  1021.             $item = self::splitIntoCharacters($item, 'shuffle');
  1022.             shuffle($item);
  1023.             $item = implode('', $item);
  1025.             if ('UTF-8' !== $charset) {
  1026.                 $item = self::convertEncoding($item, $charset, 'UTF-8');
  1027.             }
  1029.             return $item;
  1030.         }
  1032.         if (is_iterable($item)) {
  1033.             $item = self::toArray($item, false);
  1034.             shuffle($item);
  1035.         }
  1037.         return $item;
  1038.     }
  1040.     /**
  1041.      * Sorts an array.
  1042.      *
  1043.      * @param array|\Traversable $array
  1044.      * @param ?\Closure          $arrow
  1045.      *
  1046.      * @internal
  1047.      */
  1048.     public static function sort(Environment $env, bool $isSandboxed, $array, $arrow = null): array
  1049.     {
  1050.         if ($array instanceof \Traversable) {
  1051.             $array = iterator_to_array($array);
  1052.         } elseif (!\is_array($array)) {
  1053.             throw new RuntimeError(\sprintf('The "sort" filter expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  1054.         }
  1056.         if (null !== $arrow) {
  1057.             self::checkArrow($isSandboxed, $arrow, 'sort', 'filter');
  1059.             uasort($array, $arrow);
  1060.         } else {
  1061.             asort($array);
  1062.         }
  1064.         return $array;
  1065.     }
  1067.     /**
  1068.      * @internal
  1069.      */
  1070.     public static function inFilter($value, $compare)
  1071.     {
  1072.         if ($value instanceof Markup) {
  1073.             $value = (string) $value;
  1074.         }
  1075.         if ($compare instanceof Markup) {
  1076.             $compare = (string) $compare;
  1077.         }
  1079.         if (\is_string($compare)) {
  1080.             if (\is_string($value) || \is_int($value) || \is_float($value)) {
  1081.                 return '' === $value || str_contains($compare, (string) $value);
  1082.             }
  1084.             return false;
  1085.         }
  1087.         if (!is_iterable($compare)) {
  1088.             return false;
  1089.         }
  1091.         if (\is_object($value) || \is_resource($value)) {
  1092.             if (!\is_array($compare)) {
  1093.                 foreach ($compare as $item) {
  1094.                     if ($item === $value) {
  1095.                         return true;
  1096.                     }
  1097.                 }
  1099.                 return false;
  1100.             }
  1102.             return \in_array($value, $compare, true);
  1103.         }
  1105.         foreach ($compare as $item) {
  1106.             if (0 === self::compare($value, $item)) {
  1107.                 return true;
  1108.             }
  1109.         }
  1111.         return false;
  1112.     }
  1114.     /**
  1115.      * Compares two values using a more strict version of the PHP non-strict comparison operator.
  1116.      *
  1117.      * @see https://wiki.php.net/rfc/string_to_number_comparison
  1118.      * @see https://wiki.php.net/rfc/trailing_whitespace_numerics
  1119.      *
  1120.      * @internal
  1121.      */
  1122.     public static function compare($a, $b)
  1123.     {
  1124.         // int <=> string
  1125.         if (\is_int($a) && \is_string($b)) {
  1126.             $bTrim = trim($b, " \t\n\r\v\f");
  1127.             if (!is_numeric($bTrim)) {
  1128.                 return (string) $a <=> $b;
  1129.             }
  1130.             if ((int) $bTrim == $bTrim) {
  1131.                 return $a <=> (int) $bTrim;
  1132.             }
  1134.             return (float) $a <=> (float) $bTrim;
  1135.         }
  1136.         if (\is_string($a) && \is_int($b)) {
  1137.             $aTrim = trim($a, " \t\n\r\v\f");
  1138.             if (!is_numeric($aTrim)) {
  1139.                 return $a <=> (string) $b;
  1140.             }
  1141.             if ((int) $aTrim == $aTrim) {
  1142.                 return (int) $aTrim <=> $b;
  1143.             }
  1145.             return (float) $aTrim <=> (float) $b;
  1146.         }
  1148.         // float <=> string
  1149.         if (\is_float($a) && \is_string($b)) {
  1150.             if (is_nan($a)) {
  1151.                 return 1;
  1152.             }
  1153.             $bTrim = trim($b, " \t\n\r\v\f");
  1154.             if (!is_numeric($bTrim)) {
  1155.                 return (string) $a <=> $b;
  1156.             }
  1158.             return $a <=> (float) $bTrim;
  1159.         }
  1160.         if (\is_string($a) && \is_float($b)) {
  1161.             if (is_nan($b)) {
  1162.                 return 1;
  1163.             }
  1164.             $aTrim = trim($a, " \t\n\r\v\f");
  1165.             if (!is_numeric($aTrim)) {
  1166.                 return $a <=> (string) $b;
  1167.             }
  1169.             return (float) $aTrim <=> $b;
  1170.         }
  1172.         // fallback to <=>
  1173.         return $a <=> $b;
  1174.     }
  1176.     /**
  1177.      * @throws RuntimeError When the regular expression cannot be evaluated
  1178.      *
  1179.      * @internal
  1180.      */
  1181.     public static function matches(string $regexp, ?string $str): int
  1182.     {
  1183.         set_error_handler(static function ($t, $m) use ($regexp) {
  1184.             throw new RuntimeError(\sprintf('Regexp "%s" passed to "matches" is not valid', $regexp).substr($m, 12));
  1185.         });
  1186.         try {
  1187.             if (false === $result = preg_match($regexp, $str ?? '')) {
  1188.                 throw new RuntimeError(\sprintf('Regexp "%s" passed to "matches" failed: %s.', $regexp, preg_last_error_msg()));
  1189.             }
  1191.             return $result;
  1192.         } finally {
  1193.             restore_error_handler();
  1194.         }
  1195.     }
  1197.     /**
  1198.      * Returns a trimmed string.
  1199.      *
  1200.      * @param string|\Stringable|null $string
  1201.      * @param string|null             $characterMask
  1202.      * @param string                  $side          left, right, or both
  1203.      *
  1204.      * @throws RuntimeError When an invalid trimming side is used
  1205.      *
  1206.      * @internal
  1207.      */
  1208.     public static function trim($string, $characterMask = null, $side = 'both'): string|\Stringable
  1209.     {
  1210.         if (null === $characterMask) {
  1211.             $characterMask = self::DEFAULT_TRIM_CHARS;
  1212.         }
  1214.         $trimmed = match ($side) {
  1215.             'both' => trim($string ?? '', $characterMask),
  1216.             'left' => ltrim($string ?? '', $characterMask),
  1217.             'right' => rtrim($string ?? '', $characterMask),
  1218.             default => throw new RuntimeError('Trimming side must be "left", "right" or "both".'),
  1219.         };
  1221.         // trimming a safe string with the default character mask always returns a safe string (independently of the context)
  1222.         return $string instanceof Markup && self::DEFAULT_TRIM_CHARS === $characterMask ? new Markup($trimmed, $string->getCharset()) : $trimmed;
  1223.     }
  1225.     /**
  1226.      * Inserts HTML line breaks before all newlines in a string.
  1227.      *
  1228.      * @param string|null $string
  1229.      *
  1230.      * @internal
  1231.      */
  1232.     public static function nl2br($string): string
  1233.     {
  1234.         return nl2br($string ?? '');
  1235.     }
  1237.     /**
  1238.      * Removes whitespaces between HTML tags.
  1239.      *
  1240.      * @param string|null $content
  1241.      *
  1242.      * @internal
  1243.      */
  1244.     public static function spaceless($content): string
  1245.     {
  1246.         return trim(preg_replace('/>\s+</', '><', $content ?? ''));
  1247.     }
  1249.     /**
  1250.      * @param string|null $string
  1251.      * @param string      $to
  1252.      * @param string      $from
  1253.      *
  1254.      * @internal
  1255.      */
  1256.     public static function convertEncoding($string, $to, $from): string
  1257.     {
  1258.         if (!\function_exists('iconv')) {
  1259.             throw new RuntimeError('Unable to convert encoding: required function iconv() does not exist. You should install ext-iconv or symfony/polyfill-iconv.');
  1260.         }
  1262.         return iconv($from, $to, $string ?? '');
  1263.     }
  1265.     /**
  1266.      * Unicode version of str_split(), an empty string giving a single empty character.
  1267.      *
  1268.      * @return non-empty-list<string>
  1269.      *
  1270.      * @throws RuntimeError When the string cannot be split into characters
  1271.      */
  1272.     private static function splitIntoCharacters(string $string, string $name): array
  1273.     {
  1274.         if (false === preg_match_all('/./us', $string, $matches)) {
  1275.             throw new RuntimeError(\sprintf('Unable to split the string passed to "%s" into characters: %s.', $name, preg_last_error_msg()));
  1276.         }
  1278.         return $matches[0] ?: [''];
  1279.     }
  1281.     /**
  1282.      * Returns the length of a variable.
  1283.      *
  1284.      * @param mixed $thing A variable
  1285.      *
  1286.      * @internal
  1287.      */
  1288.     public static function length(string $charset, $thing): int
  1289.     {
  1290.         if (null === $thing) {
  1291.             return 0;
  1292.         }
  1294.         if (\is_scalar($thing)) {
  1295.             return mb_strlen($thing, $charset);
  1296.         }
  1298.         if ($thing instanceof \Countable || \is_array($thing) || $thing instanceof \SimpleXMLElement) {
  1299.             return \count($thing);
  1300.         }
  1302.         if ($thing instanceof \Traversable) {
  1303.             return iterator_count($thing);
  1304.         }
  1306.         if ($thing instanceof \Stringable) {
  1307.             return mb_strlen((string) $thing, $charset);
  1308.         }
  1310.         return 1;
  1311.     }
  1313.     /**
  1314.      * Converts a string to uppercase.
  1315.      *
  1316.      * @param string|null $string A string
  1317.      *
  1318.      * @internal
  1319.      */
  1320.     public static function upper(string $charset, $string): string
  1321.     {
  1322.         return mb_strtoupper($string ?? '', $charset);
  1323.     }
  1325.     /**
  1326.      * Converts a string to lowercase.
  1327.      *
  1328.      * @param string|null $string A string
  1329.      *
  1330.      * @internal
  1331.      */
  1332.     public static function lower(string $charset, $string): string
  1333.     {
  1334.         return mb_strtolower($string ?? '', $charset);
  1335.     }
  1337.     /**
  1338.      * Strips HTML and PHP tags from a string.
  1339.      *
  1340.      * @param string|null          $string
  1341.      * @param string[]|string|null $allowable_tags
  1342.      *
  1343.      * @internal
  1344.      */
  1345.     public static function striptags($string, $allowable_tags = null): string
  1346.     {
  1347.         return strip_tags($string ?? '', $allowable_tags);
  1348.     }
  1350.     /**
  1351.      * Returns a titlecased string.
  1352.      *
  1353.      * @param string|null $string A string
  1354.      *
  1355.      * @internal
  1356.      */
  1357.     public static function titleCase(string $charset, $string): string
  1358.     {
  1359.         return mb_convert_case($string ?? '', \MB_CASE_TITLE, $charset);
  1360.     }
  1362.     /**
  1363.      * Returns a capitalized string.
  1364.      *
  1365.      * @param string|null $string A string
  1366.      *
  1367.      * @internal
  1368.      */
  1369.     public static function capitalize(string $charset, $string): string
  1370.     {
  1371.         return mb_strtoupper(mb_substr($string ?? '', 0, 1, $charset), $charset).mb_strtolower(mb_substr($string ?? '', 1, null, $charset), $charset);
  1372.     }
  1374.     /**
  1375.      * @internal
  1376.      *
  1377.      * to be removed in 4.0
  1378.      */
  1379.     public static function callMacro(MacroNamespace $namespace, string $method, array $args, int $lineno, array $context, Source $source)
  1380.     {
  1381.         return $namespace->call(substr($method, \strlen('macro_')), $args, $context, $lineno, $source);
  1382.     }
  1384.     /**
  1385.      * @template TSequence
  1386.      *
  1387.      * @param TSequence $seq
  1388.      *
  1389.      * @return ($seq is iterable ? TSequence : array{})
  1390.      *
  1391.      * @internal
  1392.      */
  1393.     public static function ensureTraversable($seq)
  1394.     {
  1395.         if (is_iterable($seq)) {
  1396.             return $seq;
  1397.         }
  1399.         return [];
  1400.     }
  1402.     /**
  1403.      * @internal
  1404.      */
  1405.     public static function toArray($seq, $preserveKeys = true)
  1406.     {
  1407.         if ($seq instanceof \Traversable) {
  1408.             return iterator_to_array($seq, $preserveKeys);
  1409.         }
  1411.         if (!\is_array($seq)) {
  1412.             return $seq;
  1413.         }
  1415.         return $preserveKeys ? $seq : array_values($seq);
  1416.     }
  1418.     /**
  1419.      * @param list<string|null> $names
  1420.      *
  1421.      * @internal
  1422.      */
  1423.     public static function destructureSequence(array &$context, array $names, \Traversable $sequence): \Traversable
  1424.     {
  1425.         $count = \count($names);
  1426.         if (0 === $count) {
  1427.             return $sequence;
  1428.         }
  1430.         $i = 0;
  1431.         foreach ($sequence as $value) {
  1432.             $name = $names[$i];
  1433.             if (null !== $name) {
  1434.                 $context[$name] = $value;
  1435.             }
  1436.             if (++$i === $count) {
  1437.                 return $sequence;
  1438.             }
  1439.         }
  1441.         for (; $i < $count; ++$i) {
  1442.             $name = $names[$i];
  1443.             if (null !== $name) {
  1444.                 $context[$name] = null;
  1445.             }
  1446.         }
  1448.         return $sequence;
  1449.     }
  1451.     /**
  1452.      * Checks if a variable is empty.
  1453.      *
  1454.      *    {# evaluates to true if the foo variable is null, false, or the empty string #}
  1455.      *    {% if foo is empty %}
  1456.      *        {# ... #}
  1457.      *    {% endif %}
  1458.      *
  1459.      * @param mixed $value A variable
  1460.      *
  1461.      * @internal
  1462.      */
  1463.     public static function testEmpty($value): bool
  1464.     {
  1465.         if ($value instanceof \Countable) {
  1466.             return 0 === \count($value);
  1467.         }
  1469.         if ($value instanceof \Traversable) {
  1470.             return !iterator_count($value);
  1471.         }
  1473.         if ($value instanceof \Stringable) {
  1474.             return '' === (string) $value;
  1475.         }
  1477.         return '' === $value || false === $value || null === $value || [] === $value;
  1478.     }
  1480.     /**
  1481.      * Checks if a variable is a sequence.
  1482.      *
  1483.      *    {# evaluates to true if the foo variable is a sequence #}
  1484.      *    {% if foo is sequence %}
  1485.      *        {# ... #}
  1486.      *    {% endif %}
  1487.      *
  1488.      * @internal
  1489.      */
  1490.     public static function testSequence($value): bool
  1491.     {
  1492.         if ($value instanceof \ArrayObject) {
  1493.             $value = $value->getArrayCopy();
  1494.         }
  1496.         if ($value instanceof \Traversable) {
  1497.             $value = iterator_to_array($value);
  1498.         }
  1500.         return \is_array($value) && array_is_list($value);
  1501.     }
  1503.     /**
  1504.      * Checks if a variable is a mapping.
  1505.      *
  1506.      *    {# evaluates to true if the foo variable is a mapping #}
  1507.      *    {% if foo is mapping %}
  1508.      *        {# ... #}
  1509.      *    {% endif %}
  1510.      *
  1511.      * @internal
  1512.      */
  1513.     public static function testMapping($value): bool
  1514.     {
  1515.         if ($value instanceof \ArrayObject) {
  1516.             $value = $value->getArrayCopy();
  1517.         }
  1519.         if ($value instanceof \Traversable) {
  1520.             $value = iterator_to_array($value);
  1521.         }
  1523.         return (\is_array($value) && !array_is_list($value)) || \is_object($value);
  1524.     }
  1526.     /**
  1527.      * Renders a template.
  1528.      *
  1529.      * @param array                        $context
  1530.      * @param string|array|TemplateWrapper $template      The template to render or an array of templates to try consecutively
  1531.      * @param array                        $variables     The variables to pass to the template
  1532.      * @param bool                         $withContext
  1533.      * @param bool                         $ignoreMissing Whether to ignore missing templates or not
  1534.      * @param bool                         $sandboxed     Whether to sandbox the template or not
  1535.      *
  1536.      * @return string|Markup
  1537.      *
  1538.      * @internal
  1539.      */
  1540.     public static function include(Environment $env, $context, $template, $variables = [], $withContext = true, $ignoreMissing = false, $sandboxed = false)
  1541.     {
  1542.         if (\func_num_args() >= 7) {
  1543.             if ($sandboxed) {
  1544.                 trigger_deprecation('twig/twig', '3.29', 'The "sandboxed" argument of the "include" function is deprecated, use the "render_sandboxed" function to render untrusted templates instead.');
  1545.             } else {
  1546.                 trigger_deprecation('twig/twig', '3.29', 'The "sandboxed" argument of the "include" function is deprecated, remove the argument as "false" has no effect.');
  1547.             }
  1548.         }
  1550.         $alreadySandboxed = false;
  1551.         $sandbox = null;
  1552.         if ($withContext) {
  1553.             $variables = array_merge($context, $variables);
  1554.         }
  1556.         if ($isSandboxed = $sandboxed && $env->hasExtension(SandboxExtension::class)) {
  1557.             $sandbox = $env->getExtension(SandboxExtension::class)->getChecker();
  1558.             if (!$alreadySandboxed = $sandbox->isSandboxed()) {
  1559.                 $sandbox->setSandboxed(true);
  1560.             }
  1561.         }
  1563.         try {
  1564.             $loaded = null;
  1565.             try {
  1566.                 $loaded = $env->resolveTemplate($template);
  1567.             } catch (LoaderError $e) {
  1568.                 if (!$ignoreMissing) {
  1569.                     throw $e;
  1570.                 }
  1572.                 return '';
  1573.             }
  1575.             $rendered = $loaded->render($variables);
  1577.             return '' === $rendered ? '' : new Markup($rendered, $env->getCharset());
  1578.         } finally {
  1579.             if ($isSandboxed && !$alreadySandboxed) {
  1580.                 $sandbox->setSandboxed(false);
  1581.             }
  1582.         }
  1583.     }
  1585.     /**
  1586.      * Renders a template without giving it access to the current context.
  1587.      *
  1588.      * @param string|array<string|TemplateWrapper>|TemplateWrapper $template      The template to render or an array of templates to try consecutively
  1589.      * @param array<string, mixed>                                 $variables     The variables to pass to the template
  1590.      * @param bool                                                 $ignoreMissing Whether to ignore missing templates or not
  1591.      *
  1592.      * @return string|Markup
  1593.      *
  1594.      * @internal
  1595.      */
  1596.     public static function includeOnly(Environment $env, $template, array $variables = [], bool $ignoreMissing = false)
  1597.     {
  1598.         return self::include($env, [], $template, $variables, false, $ignoreMissing);
  1599.     }
  1601.     /**
  1602.      * Returns a template content without rendering it.
  1603.      *
  1604.      * @param string $name          The template name
  1605.      * @param bool   $ignoreMissing Whether to ignore missing templates or not
  1606.      *
  1607.      * @internal
  1608.      */
  1609.     public static function source(Environment $env, $name, $ignoreMissing = false): string
  1610.     {
  1611.         $loader = $env->getLoader();
  1612.         try {
  1613.             return $loader->getSourceContext($name)->getCode();
  1614.         } catch (LoaderError $e) {
  1615.             if (!$ignoreMissing) {
  1616.                 throw $e;
  1617.             }
  1619.             return '';
  1620.         }
  1621.     }
  1623.     /**
  1624.      * Returns the list of cases of the enum.
  1625.      *
  1626.      * @template T of \UnitEnum
  1627.      *
  1628.      * @param class-string<T> $enum
  1629.      *
  1630.      * @return list<T>
  1631.      *
  1632.      * @internal
  1633.      */
  1634.     public static function enumCases(string $enum): array
  1635.     {
  1636.         if (!enum_exists($enum)) {
  1637.             throw new RuntimeError(\sprintf('Enum "%s" does not exist.', $enum));
  1638.         }
  1640.         return $enum::cases();
  1641.     }
  1643.     /**
  1644.      * Provides the ability to access enums by their class names.
  1645.      *
  1646.      * @template T of \UnitEnum
  1647.      *
  1648.      * @param class-string<T> $enum
  1649.      *
  1650.      * @return T
  1651.      *
  1652.      * @internal
  1653.      */
  1654.     public static function enum(string $enum): \UnitEnum
  1655.     {
  1656.         if (!enum_exists($enum)) {
  1657.             throw new RuntimeError(\sprintf('"%s" is not an enum.', $enum));
  1658.         }
  1660.         if (!$cases = $enum::cases()) {
  1661.             throw new RuntimeError(\sprintf('"%s" is an empty enum.', $enum));
  1662.         }
  1664.         return $cases[0];
  1665.     }
  1667.     /**
  1668.      * Provides the ability to get constants from instances as well as class/global constants.
  1669.      *
  1670.      * @param string      $constant     The name of the constant
  1671.      * @param object|null $object       The object to get the constant from
  1672.      * @param bool        $checkDefined Whether to check if the constant is defined or not
  1673.      *
  1674.      * @return mixed Class constants can return many types like scalars, arrays, and
  1675.      *               objects depending on the PHP version (\BackedEnum, \UnitEnum, etc.)
  1676.      *               When $checkDefined is true, returns true when the constant is defined, false otherwise
  1677.      *
  1678.      * @internal
  1679.      */
  1680.     public static function constant($constant, $object = null, bool $checkDefined = false)
  1681.     {
  1682.         if (null !== $object) {
  1683.             if ('class' === $constant) {
  1684.                 return $checkDefined ? true : $object::class;
  1685.             }
  1687.             $constant = $object::class.'::'.$constant;
  1688.         }
  1690.         if (!\defined($constant)) {
  1691.             if ($checkDefined) {
  1692.                 return false;
  1693.             }
  1695.             if ('::class' === strtolower(substr($constant, -7))) {
  1696.                 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));
  1697.             }
  1699.             throw new RuntimeError(\sprintf('Constant "%s" is undefined.', $constant));
  1700.         }
  1702.         return $checkDefined ? true : \constant($constant);
  1703.     }
  1705.     /**
  1706.      * Batches item.
  1707.      *
  1708.      * @param array $items An array of items
  1709.      * @param int   $size  The size of the batch
  1710.      * @param mixed $fill  A value used to fill missing items
  1711.      *
  1712.      * @internal
  1713.      */
  1714.     public static function batch($items, $size, $fill = null, $preserveKeys = true): array
  1715.     {
  1716.         if (!is_iterable($items)) {
  1717.             throw new RuntimeError(\sprintf('The "batch" filter expects a sequence or a mapping, got "%s".', get_debug_type($items)));
  1718.         }
  1720.         $size = (int) ceil($size);
  1722.         $result = array_chunk(self::toArray($items, $preserveKeys), $size, $preserveKeys);
  1724.         if (null !== $fill && $result) {
  1725.             $last = \count($result) - 1;
  1726.             if ($fillCount = $size - \count($result[$last])) {
  1727.                 for ($i = 0; $i < $fillCount; ++$i) {
  1728.                     $result[$last][] = $fill;
  1729.                 }
  1730.             }
  1731.         }
  1733.         return $result;
  1734.     }
  1736.     /**
  1737.      * Returns the attribute value for a given array/object.
  1738.      *
  1739.      * @param mixed  $object            The object or array from where to get the item
  1740.      * @param mixed  $item              The item to get from the array or object
  1741.      * @param array  $arguments         An array of arguments to pass if the item is an object method
  1742.      * @param string $type              The type of attribute (@see \Twig\Template constants)
  1743.      * @param bool   $isDefinedTest     Whether this is only a defined check
  1744.      * @param bool   $ignoreStrictCheck Whether to ignore the strict attribute check or not
  1745.      * @param int    $lineno            The template line where the attribute was called
  1746.      *
  1747.      * @return mixed The attribute value, or a Boolean when $isDefinedTest is true, or null when the attribute is not set and $ignoreStrictCheck is true
  1748.      *
  1749.      * @throws RuntimeError if the attribute does not exist and Twig is running in strict mode and $isDefinedTest is false
  1750.      *
  1751.      * @internal
  1752.      */
  1753.     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)
  1754.     {
  1755.         $propertyNotAllowedError = null;
  1756.         if ($sandboxed && $item instanceof \Stringable) {
  1757.             $env->getExtension(SandboxExtension::class)->getChecker()->ensureToStringAllowed($item, $lineno, $source);
  1758.         }
  1760.         // array
  1761.         if (Template::METHOD_CALL !== $type) {
  1762.             $arrayItem = \is_bool($item) || \is_float($item) ? (int) $item : $item;
  1764.             if ($arrayItem instanceof \Stringable && ($object instanceof \ArrayObject || $object instanceof \ArrayIterator)) {
  1765.                 $arrayItem = (string) $arrayItem;
  1766.             }
  1768.             if ($sandboxed && $object instanceof \ArrayAccess && !\in_array($object::class, self::ARRAY_LIKE_CLASSES, true)) {
  1769.                 try {
  1770.                     $env->getExtension(SandboxExtension::class)->getChecker()->checkPropertyAllowed($object, $arrayItem, $lineno, $source);
  1771.                 } catch (SecurityNotAllowedPropertyError $propertyNotAllowedError) {
  1772.                     // The methodCheck path expects $item to be a string; stringify it here
  1773.                     // to avoid PHP 8.1+ implicit float-to-int deprecations on downstream
  1774.                     // array key lookups (e.g. isset($cache[$class][$item])).
  1775.                     $item = (string) $item;
  1776.                     goto methodCheck;
  1777.                 }
  1778.             }
  1780.             if (match (true) {
  1781.                 \is_array($object) => \array_key_exists($arrayItem = (string) $arrayItem, $object),
  1782.                 $object instanceof \ArrayAccess => $object->offsetExists($arrayItem),
  1783.                 default => false,
  1784.             }) {
  1785.                 if ($isDefinedTest) {
  1786.                     return true;
  1787.                 }
  1789.                 return $object[$arrayItem];
  1790.             }
  1792.             if (Template::ARRAY_CALL === $type || !\is_object($object)) {
  1793.                 if ($isDefinedTest) {
  1794.                     return false;
  1795.                 }
  1797.                 if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1798.                     return;
  1799.                 }
  1801.                 if ($object instanceof \ArrayAccess) {
  1802.                     if (\is_object($arrayItem) || \is_array($arrayItem)) {
  1803.                         $message = \sprintf('Key of type "%s" does not exist in ArrayAccess-able object of class "%s".', get_debug_type($arrayItem), get_debug_type($object));
  1804.                     } else {
  1805.                         $message = \sprintf('Key "%s" does not exist in ArrayAccess-able object of class "%s".', $arrayItem, get_debug_type($object));
  1806.                     }
  1807.                 } elseif (\is_object($object)) {
  1808.                     $message = \sprintf('Impossible to access a key "%s" on an object of class "%s" that does not implement ArrayAccess interface.', $item, get_debug_type($object));
  1809.                 } elseif (\is_array($object)) {
  1810.                     if (!$object) {
  1811.                         $message = \sprintf('Key "%s" does not exist as the sequence/mapping is empty.', $arrayItem);
  1812.                     } else {
  1813.                         $message = \sprintf('Key "%s" for sequence/mapping with keys "%s" does not exist.', $arrayItem, implode(', ', array_keys($object)));
  1814.                     }
  1815.                 } elseif (Template::ARRAY_CALL === $type) {
  1816.                     if (null === $object) {
  1817.                         $message = \sprintf('Impossible to access a key ("%s") on a null variable.', $item);
  1818.                     } else {
  1819.                         $message = \sprintf('Impossible to access a key ("%s") on a %s variable ("%s").', $item, get_debug_type($object), $object);
  1820.                     }
  1821.                 } elseif (null === $object) {
  1822.                     $message = \sprintf('Impossible to access an attribute ("%s") on a null variable.', $item);
  1823.                 } else {
  1824.                     $message = \sprintf('Impossible to access an attribute ("%s") on a %s variable ("%s").', $item, get_debug_type($object), $object);
  1825.                 }
  1827.                 throw new RuntimeError($message, $lineno, $source);
  1828.             }
  1829.         }
  1831.         $item = (string) $item;
  1833.         if (!\is_object($object)) {
  1834.             if ($isDefinedTest) {
  1835.                 return false;
  1836.             }
  1838.             if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1839.                 return;
  1840.             }
  1842.             if (null === $object) {
  1843.                 $message = \sprintf('Impossible to invoke a method ("%s") on a null variable.', $item);
  1844.             } elseif (\is_array($object)) {
  1845.                 $message = \sprintf('Impossible to invoke a method ("%s") on a sequence/mapping.', $item);
  1846.             } else {
  1847.                 $message = \sprintf('Impossible to invoke a method ("%s") on a %s variable ("%s").', $item, get_debug_type($object), $object);
  1848.             }
  1850.             throw new RuntimeError($message, $lineno, $source);
  1851.         }
  1853.         if ($object instanceof Template) {
  1854.             throw new RuntimeError('Accessing \Twig\Template attributes is forbidden.', $lineno, $source);
  1855.         }
  1857.         // object property
  1858.         if (Template::METHOD_CALL !== $type) {
  1859.             if ($sandboxed) {
  1860.                 try {
  1861.                     $env->getExtension(SandboxExtension::class)->getChecker()->checkPropertyAllowed($object, $item, $lineno, $source);
  1862.                 } catch (SecurityNotAllowedPropertyError $propertyNotAllowedError) {
  1863.                     goto methodCheck;
  1864.                 }
  1865.             }
  1867.             static $propertyCheckers = [];
  1869.             if (isset($object->$item)
  1870.                 || ($propertyCheckers[$object::class][$item] ??= self::getPropertyChecker($object::class, $item))($object, $item)
  1871.             ) {
  1872.                 if ($isDefinedTest) {
  1873.                     return true;
  1874.                 }
  1876.                 return $object->$item;
  1877.             }
  1879.             if ($object instanceof \DateTimeInterface && \in_array($item, ['date', 'timezone', 'timezone_type'], true)) {
  1880.                 if ($isDefinedTest) {
  1881.                     return true;
  1882.                 }
  1884.                 return ((array) $object)[$item];
  1885.             }
  1887.             if (\defined($object::class.'::'.$item)) {
  1888.                 if ($isDefinedTest) {
  1889.                     return true;
  1890.                 }
  1892.                 return \constant($object::class.'::'.$item);
  1893.             }
  1894.         }
  1896.         methodCheck:
  1898.         static $cache = [];
  1900.         $class = $object::class;
  1902.         // object method
  1903.         // precedence: getXxx() > isXxx() > hasXxx()
  1904.         if (!isset($cache[$class])) {
  1905.             $methods = get_class_methods($object);
  1906.             if ($object instanceof \Closure) {
  1907.                 $methods[] = '__invoke';
  1908.             }
  1909.             sort($methods);
  1910.             $lcMethods = array_map('strtolower', $methods);
  1911.             $classCache = [];
  1912.             foreach ($methods as $i => $method) {
  1913.                 $classCache[$method] = $method;
  1914.                 $classCache[$lcName = $lcMethods[$i]] = $method;
  1916.                 if ('g' === $lcName[0] && str_starts_with($lcName, 'get')) {
  1917.                     $prefixLength = 3;
  1918.                     $lcName = substr($lcName, $prefixLength);
  1919.                 } elseif ('i' === $lcName[0] && str_starts_with($lcName, 'is')) {
  1920.                     $prefixLength = 2;
  1921.                     $lcName = substr($lcName, $prefixLength);
  1922.                 } elseif ('h' === $lcName[0] && str_starts_with($lcName, 'has')) {
  1923.                     $prefixLength = 3;
  1924.                     $lcName = substr($lcName, $prefixLength);
  1925.                     if (\in_array('is'.$lcName, $lcMethods, true)) {
  1926.                         continue;
  1927.                     }
  1928.                 } else {
  1929.                     continue;
  1930.                 }
  1932.                 // skip get(), is() and has() methods (in which case, $lcName is empty)
  1933.                 if ($lcName) {
  1934.                     // camelCase name (e.g. getFooBar() -> fooBar)
  1935.                     $name = $lcName[0].substr($method, $prefixLength + 1);
  1937.                     if (!isset($classCache[$name])) {
  1938.                         $classCache[$name] = $method;
  1939.                     }
  1941.                     if (!isset($classCache[$lcName])) {
  1942.                         $classCache[$lcName] = $method;
  1943.                     }
  1944.                 }
  1945.             }
  1946.             $cache[$class] = $classCache;
  1947.         }
  1949.         $call = false;
  1950.         if (isset($cache[$class][$item])) {
  1951.             $method = $cache[$class][$item];
  1952.         } elseif (isset($cache[$class][$lcItem = strtolower($item)])) {
  1953.             $method = $cache[$class][$lcItem];
  1954.         } elseif (isset($cache[$class]['__call'])) {
  1955.             $method = $item;
  1956.             $call = true;
  1957.         } else {
  1958.             if ($isDefinedTest) {
  1959.                 return false;
  1960.             }
  1962.             if ($propertyNotAllowedError) {
  1963.                 throw $propertyNotAllowedError;
  1964.             }
  1966.             if ($ignoreStrictCheck || !$env->isStrictVariables()) {
  1967.                 return;
  1968.             }
  1970.             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);
  1971.         }
  1973.         if ($sandboxed) {
  1974.             try {
  1975.                 $env->getExtension(SandboxExtension::class)->getChecker()->checkMethodAllowed($object, $method, $lineno, $source);
  1976.             } catch (SecurityNotAllowedMethodError $e) {
  1977.                 if ($isDefinedTest) {
  1978.                     return false;
  1979.                 }
  1981.                 if ($propertyNotAllowedError) {
  1982.                     throw $propertyNotAllowedError;
  1983.                 }
  1985.                 throw $e;
  1986.             }
  1987.         }
  1989.         if ($isDefinedTest) {
  1990.             return true;
  1991.         }
  1993.         // Some objects throw exceptions when they have __call, and the method we try
  1994.         // to call is not supported. If ignoreStrictCheck is true, we should return null.
  1995.         try {
  1996.             $ret = $object->$method(...$arguments);
  1997.         } catch (\BadMethodCallException $e) {
  1998.             if ($call && ($ignoreStrictCheck || !$env->isStrictVariables())) {
  1999.                 return;
  2000.             }
  2001.             throw $e;
  2002.         }
  2004.         return $ret;
  2005.     }
  2007.     /**
  2008.      * Returns the values from a single column in the input array.
  2009.      *
  2010.      * <pre>
  2011.      *  {% set items = [{ 'fruit' : 'apple'}, {'fruit' : 'orange' }] %}
  2012.      *
  2013.      *  {% set fruits = items|column('fruit') %}
  2014.      *
  2015.      *  {# fruits now contains ['apple', 'orange'] #}
  2016.      * </pre>
  2017.      *
  2018.      * @param array|\Traversable $array An array
  2019.      * @param int|string         $name  The column name
  2020.      * @param int|string|null    $index The column to use as the index/keys for the returned array
  2021.      *
  2022.      * @return array The array of values
  2023.      *
  2024.      * @internal
  2025.      */
  2026.     public static function column(Environment $env, bool $isSandboxed, $array, $name, $index = null): array
  2027.     {
  2028.         if (!is_iterable($array)) {
  2029.             throw new RuntimeError(\sprintf('The "column" filter expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2030.         }
  2032.         if ($array instanceof \Traversable) {
  2033.             $array = iterator_to_array($array);
  2034.         }
  2036.         if ($isSandboxed) {
  2037.             // The sandbox might be enabled via a SourcePolicyInterface, in which case the SandboxExtension
  2038.             // would not consider the sandbox active without the current Source: $isSandboxed is already
  2039.             // computed against the call-site source, so check the policy directly to honor that decision.
  2040.             $policy = $env->getExtension(SandboxExtension::class)->getChecker()->getSecurityPolicy();
  2041.             foreach ($array as $item) {
  2042.                 if (\is_object($item)) {
  2043.                     $policy->checkPropertyAllowed($item, (string) $name);
  2044.                     if (null !== $index) {
  2045.                         $policy->checkPropertyAllowed($item, (string) $index);
  2046.                     }
  2047.                 }
  2048.             }
  2049.         }
  2051.         return array_column($array, $name, $index);
  2052.     }
  2054.     /**
  2055.      * @param \Closure $arrow
  2056.      *
  2057.      * @internal
  2058.      */
  2059.     public static function filter(Environment $env, bool $isSandboxed, $array, $arrow)
  2060.     {
  2061.         if (!is_iterable($array)) {
  2062.             throw new RuntimeError(\sprintf('The "filter" filter expects a sequence/mapping or "Traversable", got "%s".', get_debug_type($array)));
  2063.         }
  2065.         self::checkArrow($isSandboxed, $arrow, 'filter', 'filter');
  2067.         if (\is_array($array)) {
  2068.             return array_filter($array, $arrow, \ARRAY_FILTER_USE_BOTH);
  2069.         }
  2071.         // the IteratorIterator wrapping is needed as some internal PHP classes are \Traversable but do not implement \Iterator
  2072.         return new \CallbackFilterIterator(new \IteratorIterator($array), $arrow);
  2073.     }
  2075.     /**
  2076.      * @param \Closure $arrow
  2077.      *
  2078.      * @internal
  2079.      */
  2080.     public static function find(Environment $env, bool $isSandboxed, $array, $arrow)
  2081.     {
  2082.         if (!is_iterable($array)) {
  2083.             throw new RuntimeError(\sprintf('The "find" filter expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2084.         }
  2086.         self::checkArrow($isSandboxed, $arrow, 'find', 'filter');
  2088.         foreach ($array as $k => $v) {
  2089.             if ($arrow($v, $k)) {
  2090.                 return $v;
  2091.             }
  2092.         }
  2094.         return null;
  2095.     }
  2097.     /**
  2098.      * @param \Closure $arrow
  2099.      *
  2100.      * @internal
  2101.      */
  2102.     public static function map(Environment $env, bool $isSandboxed, $array, $arrow)
  2103.     {
  2104.         if (!is_iterable($array)) {
  2105.             throw new RuntimeError(\sprintf('The "map" filter expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2106.         }
  2108.         self::checkArrow($isSandboxed, $arrow, 'map', 'filter');
  2110.         $r = [];
  2111.         foreach ($array as $k => $v) {
  2112.             $r[$k] = $arrow($v, $k);
  2113.         }
  2115.         return $r;
  2116.     }
  2118.     /**
  2119.      * @param \Closure $arrow
  2120.      *
  2121.      * @internal
  2122.      */
  2123.     public static function reduce(Environment $env, bool $isSandboxed, $array, $arrow, $initial = null)
  2124.     {
  2125.         if (!is_iterable($array)) {
  2126.             throw new RuntimeError(\sprintf('The "reduce" filter expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2127.         }
  2129.         self::checkArrow($isSandboxed, $arrow, 'reduce', 'filter');
  2131.         $accumulator = $initial;
  2132.         foreach ($array as $key => $value) {
  2133.             $accumulator = $arrow($accumulator, $value, $key);
  2134.         }
  2136.         return $accumulator;
  2137.     }
  2139.     /**
  2140.      * @param \Closure $arrow
  2141.      *
  2142.      * @internal
  2143.      */
  2144.     public static function arraySome(Environment $env, $array, $arrow, bool $isSandboxed = false)
  2145.     {
  2146.         if (!is_iterable($array)) {
  2147.             throw new RuntimeError(\sprintf('The "has some" test expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2148.         }
  2150.         self::checkArrow($isSandboxed, $arrow, 'has some', 'operator');
  2152.         foreach ($array as $k => $v) {
  2153.             if ($arrow($v, $k)) {
  2154.                 return true;
  2155.             }
  2156.         }
  2158.         return false;
  2159.     }
  2161.     /**
  2162.      * @param \Closure $arrow
  2163.      *
  2164.      * @internal
  2165.      */
  2166.     public static function arrayEvery(Environment $env, $array, $arrow, bool $isSandboxed = false)
  2167.     {
  2168.         if (!is_iterable($array)) {
  2169.             throw new RuntimeError(\sprintf('The "has every" test expects a sequence or a mapping, got "%s".', get_debug_type($array)));
  2170.         }
  2172.         self::checkArrow($isSandboxed, $arrow, 'has every', 'operator');
  2174.         foreach ($array as $k => $v) {
  2175.             if (!$arrow($v, $k)) {
  2176.                 return false;
  2177.             }
  2178.         }
  2180.         return true;
  2181.     }
  2183.     /**
  2184.      * @internal
  2185.      */
  2186.     public static function checkArrow(bool $isSandboxed, $arrow, $thing, $type): void
  2187.     {
  2188.         if ($arrow instanceof \Closure) {
  2189.             return;
  2190.         }
  2192.         if ($isSandboxed) {
  2193.             throw new RuntimeError(\sprintf('The callable passed to the "%s" %s must be a Closure in sandbox mode.', $thing, $type));
  2194.         }
  2196.         trigger_deprecation('twig/twig', '3.15', 'Passing a callable that is not a PHP \Closure as an argument to the "%s" %s is deprecated.', $thing, $type);
  2197.     }
  2199.     /**
  2200.      * @internal to be removed in Twig 4
  2201.      */
  2202.     public static function captureOutput(iterable $body): string
  2203.     {
  2204.         $level = ob_get_level();
  2205.         ob_start();
  2207.         try {
  2208.             foreach ($body as $data) {
  2209.                 echo $data;
  2210.             }
  2211.         } catch (\Throwable $e) {
  2212.             while (ob_get_level() > $level) {
  2213.                 ob_end_clean();
  2214.             }
  2216.             throw $e;
  2217.         }
  2219.         return ob_get_clean();
  2220.     }
  2222.     /**
  2223.      * @internal
  2224.      */
  2225.     public static function parseParentFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  2226.     {
  2227.         if (!$blockName = $parser->peekBlockStack()) {
  2228.             throw new SyntaxError('Calling the "parent" function outside of a block is forbidden.', $line, $parser->getStream()->getSourceContext());
  2229.         }
  2231.         if (!$parser->hasInheritance()) {
  2232.             throw new SyntaxError('Calling the "parent" function on a template that does not call "extends" or "use" is forbidden.', $line, $parser->getStream()->getSourceContext());
  2233.         }
  2235.         return new ParentExpression($blockName, $line);
  2236.     }
  2238.     /**
  2239.      * @internal
  2240.      */
  2241.     public static function parseBlockFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  2242.     {
  2243.         $fakeFunction = new TwigFunction('block', static fn ($name, $template = null) => null);
  2244.         $args = (new CallableArgumentsExtractor($fakeNode, $fakeFunction))->extractArguments($args);
  2246.         return new BlockReferenceExpression($args[0], $args[1] ?? null, $line);
  2247.     }
  2249.     /**
  2250.      * @internal
  2251.      */
  2252.     public static function parseAttributeFunction(Parser $parser, Node $fakeNode, $args, int $line): AbstractExpression
  2253.     {
  2254.         $fakeFunction = new TwigFunction('attribute', static fn ($variable, $attribute, $arguments = null) => null);
  2255.         $args = (new CallableArgumentsExtractor($fakeNode, $fakeFunction))->extractArguments($args);
  2257.         /*
  2258.         Deprecation to uncomment sometimes during the lifetime of the 4.x branch
  2259.         $src = $parser->getStream()->getSourceContext();
  2260.         $dep = new DeprecatedCallableInfo('twig/twig', '3.15', 'The "attribute" function is deprecated, use the "." notation instead.');
  2261.         $dep->setName('attribute');
  2262.         $dep->setType('function');
  2263.         $dep->triggerDeprecation($src->getPath() ?: $src->getName(), $line);
  2264.         */
  2266.         return new GetAttrExpression($args[0], $args[1], $args[2] ?? null, Template::ANY_CALL, $line);
  2267.     }
  2269.     private static function getPropertyChecker(string $class, string $property): \Closure
  2270.     {
  2271.         static $classReflectors = [];
  2273.         $class = $classReflectors[$class] ??= new \ReflectionClass($class);
  2275.         if (!$class->hasProperty($property)) {
  2276.             static $propertyExists;
  2278.             return $propertyExists ??= \Closure::fromCallable('property_exists');
  2279.         }
  2281.         $property = $class->getProperty($property);
  2283.         if (!$property->isPublic() || $property->isStatic()) {
  2284.             static $false;
  2286.             return $false ??= static fn () => false;
  2287.         }
  2289.         return static fn ($object) => $property->isInitialized($object);
  2290.     }
  2291. }