feature #2881 Environment class cleanup (fabpot)

This PR was squashed before being merged into the 2.x branch (closes #2881).

Discussion
----------

Environment class cleanup

Commits
-------

b5da9b5a deprecated passing a Twig\Template to load()/resolveTemplate()
a4476dfc updated docs
d9b91a25 added the possibility to pass a TemplateWrapper to Twig\Environment::load()
714360d6 marked Twig\Environment::getTemplateClass() as internal

CHANGELOG

@@ -1,5 +1,8 @@
 * 2.7.0 (2019-XX-XX)
 
+ * deprecated passing a Twig\Template to Twig\Environment::load()/Twig\Environment::resolveTemplate()
+ * added the possibility to pass a TemplateWrapper to Twig\Environment::load()
+ * marked Twig\Environment::getTemplateClass() as internal (implementation detail)
  * improved the performance of the sandbox
  * deprecated the spaceless tag
  * added a spaceless filter

doc/deprecated.rst

@@ -65,6 +65,13 @@ Environment
   ``Twig\Environment::setBaseTemplateClass()`` methods are deprecated and will
   be removed in Twig 3.0.
 
+* As of Twig 2.7, the ``Twig\Environment::getTemplateClass()`` is marked as
+  being internal and should not be used.
+
+* As of Twig 2.7, passing a ``Twig\Template`` instance to the
+  ``Twig\Environment::load()`` and ``Twig\Environment::resolveTemplate()`` is
+  deprecated.
+
 Interfaces
 ----------
 

src/Environment.php

@@ -29,7 +29,6 @@ use Twig\Node\ModuleNode;
 use Twig\Node\Node;
 use Twig\NodeVisitor\NodeVisitorInterface;
 use Twig\RuntimeLoader\RuntimeLoaderInterface;
-use Twig\Template;
 use Twig\TokenParser\TokenParserInterface;
 
 /**
@@ -293,6 +292,8 @@ class Environment
      * @param int|null $index The index if it is an embedded template
      *
      * @return string The template class name
+     *
+     * @internal
      */
     public function getTemplateClass($name, $index = null)
     {
@@ -336,7 +337,7 @@ class Environment
     /**
      * Loads a template.
      *
-     * @param string|TemplateWrapper|Template $name The template name
+     * @param string|TemplateWrapper $name The template name
      *
      * @throws LoaderError  When the template cannot be found
      * @throws RuntimeError When a previously generated cache is corrupted
@@ -351,6 +352,8 @@ class Environment
         }
 
         if ($name instanceof Template) {
+            @trigger_error('Passing a \Twig\Template instance to '.__METHOD__.' is deprecated since Twig 2.7.0, use \Twig\TemplateWrapper instead.', E_USER_DEPRECATED);
+
             return new TemplateWrapper($this, $name);
         }
 
@@ -483,7 +486,7 @@ class Environment
      * Similar to load() but it also accepts instances of \Twig\Template and
      * \Twig\TemplateWrapper, and an array of templates where each is tried to be loaded.
      *
-     * @param string|Template|TemplateWrapper|array $names A template or an array of templates to try consecutively
+     * @param string|TemplateWrapper|array $names A template or an array of templates to try consecutively
      *
      * @return TemplateWrapper
      *

test/Twig/Tests/TemplateWrapperTest.php

@@ -11,7 +11,6 @@
 
 use Twig\Environment;
 use Twig\Loader\ArrayLoader;
-use Twig\TemplateWrapper;
 
 class Twig_Tests_TemplateWrapperTest extends \PHPUnit\Framework\TestCase
 {