minor twigphp#4534 Add return type annotations on Twig 3 to prepare Twig 4 (smnandre)

This PR was squashed before being merged into the 3.x branch.

Discussion
----------

Add return type annotations on Twig 3 to prepare Twig 4

Started to add missing type annotation following `@stof` comment [here](twigphp#4523 (comment)).

Update:  I checked here every class (but one) in the `src` directory.

But you should ~~probably~~ **certainely** have another look.

Remains:
- src/ExpressionParser.php, where i'm not confident enough about the best return types (AbstractExpression|null works almost everytime, but lack some precision)
- extra directory
- tests directory

I'm happy to let them to someone else.... this was less fun than I expected 😅

Commits
-------

82be134 Add return type annotations on Twig 3 to prepare Twig 4

Author: fabpot

src/AbstractTwigCallable.php

@@ -79,6 +79,9 @@ public function getDynamicName(): string
         return $this->dynamicName;
     }
 
+    /**
+     * @return callable|array{class-string, string}|null
+     */
     public function getCallable()
     {
         return $this->callable;

src/Environment.php

@@ -155,6 +155,8 @@ public function useYield(): bool
 
     /**
      * Enables debugging mode.
+     *
+     * @return void
      */
     public function enableDebug()
     {
@@ -164,6 +166,8 @@ public function enableDebug()
 
     /**
      * Disables debugging mode.
+     *
+     * @return void
      */
     public function disableDebug()
     {
@@ -183,6 +187,8 @@ public function isDebug()
 
     /**
      * Enables the auto_reload option.
+     *
+     * @return void
      */
     public function enableAutoReload()
     {
@@ -191,6 +197,8 @@ public function enableAutoReload()
 
     /**
      * Disables the auto_reload option.
+     *
+     * @return void
      */
     public function disableAutoReload()
     {
@@ -209,6 +217,8 @@ public function isAutoReload()
 
     /**
      * Enables the strict_variables option.
+     *
+     * @return void
      */
     public function enableStrictVariables()
     {
@@ -218,6 +228,8 @@ public function enableStrictVariables()
 
     /**
      * Disables the strict_variables option.
+     *
+     * @return void
      */
     public function disableStrictVariables()
     {
@@ -267,6 +279,8 @@ public function getCache($original = true)
      * @param CacheInterface|string|false $cache A Twig\Cache\CacheInterface implementation,
      *                                           an absolute path to the compiled templates,
      *                                           or false to disable cache
+     *
+     * @return void
      */
     public function setCache($cache)
     {
@@ -503,6 +517,9 @@ public function resolveTemplate($names): TemplateWrapper
         throw new LoaderError(\sprintf('Unable to find one of the following templates: "%s".', implode('", "', $names)));
     }
 
+    /**
+     * @return void
+     */
     public function setLexer(Lexer $lexer)
     {
         $this->lexer = $lexer;
@@ -520,6 +537,9 @@ public function tokenize(Source $source): TokenStream
         return $this->lexer->tokenize($source);
     }
 
+    /**
+     * @return void
+     */
     public function setParser(Parser $parser)
     {
         $this->parser = $parser;
@@ -539,6 +559,9 @@ public function parse(TokenStream $stream): ModuleNode
         return $this->parser->parse($stream);
     }
 
+    /**
+     * @return void
+     */
     public function setCompiler(Compiler $compiler)
     {
         $this->compiler = $compiler;
@@ -573,6 +596,9 @@ public function compileSource(Source $source): string
         }
     }
 
+    /**
+     * @return void
+     */
     public function setLoader(LoaderInterface $loader)
     {
         $this->loader = $loader;
@@ -583,6 +609,9 @@ public function getLoader(): LoaderInterface
         return $this->loader;
     }
 
+    /**
+     * @return void
+     */
     public function setCharset(string $charset)
     {
         if ('UTF8' === $charset = strtoupper($charset ?: '')) {
@@ -603,6 +632,9 @@ public function hasExtension(string $class): bool
         return $this->extensionSet->hasExtension($class);
     }
 
+    /**
+     * @return void
+     */
     public function addRuntimeLoader(RuntimeLoaderInterface $loader)
     {
         $this->runtimeLoaders[] = $loader;
@@ -650,6 +682,9 @@ public function getRuntime(string $class)
         throw new RuntimeError(\sprintf('Unable to load the "%s" runtime.', $class));
     }
 
+    /**
+     * @return void
+     */
     public function addExtension(ExtensionInterface $extension)
     {
         $this->extensionSet->addExtension($extension);
@@ -658,6 +693,8 @@ public function addExtension(ExtensionInterface $extension)
 
     /**
      * @param ExtensionInterface[] $extensions An array of extensions
+     *                                         
+     * @return void
      */
     public function setExtensions(array $extensions)
     {
@@ -673,6 +710,9 @@ public function getExtensions(): array
         return $this->extensionSet->getExtensions();
     }
 
+    /**
+     * @return void
+     */
     public function addTokenParser(TokenParserInterface $parser)
     {
         $this->extensionSet->addTokenParser($parser);
@@ -701,6 +741,9 @@ public function registerUndefinedTokenParserCallback(callable $callable): void
         $this->extensionSet->registerUndefinedTokenParserCallback($callable);
     }
 
+    /**
+     * @return void
+     */
     public function addNodeVisitor(NodeVisitorInterface $visitor)
     {
         $this->extensionSet->addNodeVisitor($visitor);
@@ -716,6 +759,9 @@ public function getNodeVisitors(): array
         return $this->extensionSet->getNodeVisitors();
     }
 
+    /**
+     * @return void
+     */
     public function addFilter(TwigFilter $filter)
     {
         $this->extensionSet->addFilter($filter);
@@ -750,6 +796,9 @@ public function getFilters(): array
         return $this->extensionSet->getFilters();
     }
 
+    /**
+     * @return void
+     */
     public function addTest(TwigTest $test)
     {
         $this->extensionSet->addTest($test);
@@ -773,6 +822,9 @@ public function getTest(string $name): ?TwigTest
         return $this->extensionSet->getTest($name);
     }
 
+    /**
+     * @return void
+     */
     public function addFunction(TwigFunction $function)
     {
         $this->extensionSet->addFunction($function);
@@ -814,6 +866,8 @@ public function getFunctions(): array
      * but after, you can only update existing globals.
      *
      * @param mixed $value The global value
+     *
+     * @return void
      */
     public function addGlobal(string $name, $value)
     {

src/Extension/EscaperExtension.php

@@ -80,6 +80,8 @@ public function setEnvironment(Environment $environment): void
     }
 
     /**
+     * @return void
+     *
      * @deprecated since Twig 3.10
      */
     public function setEscaperRuntime(EscaperRuntime $escaper)
@@ -130,6 +132,8 @@ public function getDefaultStrategy(string $name)
      * @param string                                        $strategy The strategy name that should be used as a strategy in the escape call
      * @param callable(Environment, string, string): string $callable A valid PHP callable
      *
+     * @return void
+     *
      * @deprecated since Twig 3.10
      */
     public function setEscaper($strategy, callable $callable)
@@ -163,6 +167,8 @@ public function getEscapers()
     }
 
     /**
+     * @return void
+     *
      * @deprecated since Twig 3.10
      */
     public function setSafeClasses(array $safeClasses = [])
@@ -177,6 +183,8 @@ public function setSafeClasses(array $safeClasses = [])
     }
 
     /**
+     * @return void
+     *
      * @deprecated since Twig 3.10
      */
     public function addSafeClass(string $class, array $strategies)
@@ -192,6 +200,8 @@ public function addSafeClass(string $class, array $strategies)
 
     /**
      * @internal
+     *
+     * @return array<string>
      */
     public static function escapeFilterIsSafe(Node $filterArgs)
     {

src/Extension/SandboxExtension.php

@@ -72,7 +72,7 @@ private function isSourceSandboxed(?Source $source): bool
         return $this->sourcePolicy->enableSandbox($source);
     }
 
-    public function setSecurityPolicy(SecurityPolicyInterface $policy)
+    public function setSecurityPolicy(SecurityPolicyInterface $policy): void
     {
         $this->policy = $policy;
     }
@@ -117,6 +117,13 @@ public function checkPropertyAllowed($obj, $property, int $lineno = -1, ?Source
         }
     }
 
+    /**
+     * @param mixed $obj
+     *
+     * @return mixed
+     *
+     * @throws SecurityNotAllowedMethodError
+     */
     public function ensureToStringAllowed($obj, int $lineno = -1, ?Source $source = null)
     {
         if (\is_array($obj)) {

src/ExtensionSet.php

@@ -62,6 +62,9 @@ public function __construct()
         $this->staging = new StagingExtension();
     }
 
+    /**
+     * @return void
+     */
     public function initRuntime()
     {
         $this->runtimeInitialized = true;

src/Lexer.php

@@ -82,7 +82,7 @@ public function __construct(Environment $env, array $options = [])
         ], $options);
     }
 
-    private function initialize()
+    private function initialize(): void
     {
         if ($this->isInitialized) {
             return;

src/Markup.php

@@ -27,7 +27,7 @@ public function __construct($content, $charset)
         $this->charset = $charset;
     }
 
-    public function __toString()
+    public function __toString(): string
     {
         return $this->content;
     }

src/Node/CheckSecurityCallNode.php

@@ -20,6 +20,9 @@
 #[YieldReady]
 class CheckSecurityCallNode extends Node
 {
+    /**
+     * @return void
+     */
     public function compile(Compiler $compiler)
     {
         $compiler

src/Node/Expression/CallExpression.php

@@ -26,6 +26,9 @@ abstract class CallExpression extends AbstractExpression
 {
     private $reflector = null;
 
+    /**
+     * @return void
+     */
     protected function compileCallable(Compiler $compiler)
     {
         $twigCallable = $this->getTwigCallable();

src/Node/Expression/FunctionExpression.php

@@ -44,6 +44,9 @@ public function __construct(TwigFunction|string $function, Node $arguments, int
         $this->deprecateAttribute('dynamic_name', new NameDeprecation('twig/twig', '3.12'));
     }
 
+    /**
+     * @return void
+     */
     public function compile(Compiler $compiler)
     {
         $name = $this->getAttribute('name');