How to Upgrade Twig from Underscored to Namespaces

This post was updated at November 2020 with fresh know-how.
What is new?

Switch from deprecated --set option to rector.php config.


Symfony recently announced a new version of Twig with namespaces as we know it. Before PHP 5.2 there was Underscored_Namespace - I remember because that was the first version I used.

Today I'll show you how to upgrade from _ to \\ in few minutes seconds.

This set would not be possible and as good as it is without you, open-source PHP community. I'd like to thank 👏:

<ul>
    <li><strong><a href="https://github.com/greg0ire">greg0ire</a></strong> <a href="https://github.com/rectorphp/rector/commit/493e418f4691f3a4beadf901bd54ea7406380891">for contributing</a> to this set</li>
    <li>and <strong><a href="https://github.com/enumag">enumag</a></strong> for <a href="https://github.com/rectorphp/rector/search?q=twig+is%3Aissue+author%3Aenumag&amp;unscoped_q=twig+is%3Aissue+author%3Aenumag&amp;type=Issues">battle testing and reported issues</a></li>
</ul>

Find and Replace?

So all we need to do is replace Twig_ with Twig\?

-Twig_Function
+Twig\Function

This would fail since Twig\Function class doesn't exist. Twig\TwigFunction does. There 150 more cases where find and replace fails.

2 Places

We need to replace both docblocks:

 /**
- * @throws \Twig_Error_Loader
+ * @throws \Twig\Error\LoaderError
  */
 public function render(): void
 {
-    /** @var \Twig_Environment $env */
+    /** @var \Twig\Environment $env */
     $env = $this->getTwigEnv();

     // ...
 }

And the code:

-$safeTwigEnvironment = new \Twig_Environment(
+$safeTwigEnvironment = new \Twig\Environment(
-   new \Twig_Loader_Array([])
+   new \Twig\Loader\ArrayLoader([])
);

In a reaction to the Symfony blog post, I see many developers do upgrades manually. In case of 50 changes, it's ok, but private code bases will go 1000+ use cases.

Code Pattern Refactoring

For Rector it just 1 pattern to refactor. Just tell him to process your files src:

  1. Install Rector
composer require rector/rector --dev
  1. Update rector.php
use Rector\Symfony\Set\TwigSetList;
use Rector\Config\RectorConfig;

return function (RectorConfig $rectorConfig): void {
    $rectorConfig->import(TwigSetList::TWIG_UNDERSCORE_TO_NAMESPACE);
};
  1. Run Rector
vendor/bin/rector process src

Happy coding!