Fixing Drupal 8.3 upgrade issues - TwigExtension, Layouts, and Tweaks

Lots of stuff has been changing in Drupal 8 recently. In 8.3.0, a new experimental "layout discovery" module was added to core, which conflicted with the contrib "layout plugin" module. Now in 8.3.3, the two-column and three-column layouts had their region names changed, which hid any content dropped into those regions when those layouts were used.

In the past week, we've seen a couple issues upgrading a site from 8.2.x to 8.3.2, and now another issue with 8.3.2 to 8.3.3 that seem worth a quick mention.

All of these are issues we've caught before releasing to production, thanks to our visual regression testing.

Layout Plugin -> Layout Discovery

By now, this is quite an old one, and modules like Panels and Display Suite now do this for you in an upgrade script -- they disable the contributed Layout Plugin and enable the Layout Discovery module in core.

There are several different contributed modules that need to get updated to work with 8.3, but all the ones we've seen now have a major version dedicated to 8.3+. So not much of an issue anymore.

Twocol and Twocol_bricks layouts broken

In today's 8.3.3 release, a fixed issue in the release log with the innocuous title "Review layout CSS and markup" made a bunch of our content disappear. Reviewing the patch, it becomes obvious why -- the names of several regions in the layouts provided by layout discovery have changed. In general, regions with "left" in their name got changed to "first" and "right" to "second".

A quick way to find all of these is to export your configuration, and inside the config directory, use grep "id: layout_two" * and grep "id: layout_three" to find all the places using these layouts. Then go edit the displays to put your content back, export your updated config and deploy.

\Drupal\core\Template\TwigExtension has new arguments

On a site we just took over maintenance, the previous developers had declared a new custom Twig extension for some custom functionality, and they had extended \Drupal\core\Template\TwigExtension to do so. This pattern was used in core until 8.3.0, but this base class now has some services injected into its constructor. Which threw fatal PHP errors, leaving a blank site.

The fix? Change the custom class to extend \Twig_Extension directly. There is no need to extend the Drupal wrapper. One thing that caught us is the underscore -- you need to add that as well as the backslash to get the right class...

drupal_block() missing second argument

In the Twig Tweak module there's a useful {{ drupal_block('block-id') }} function. However, with the release of 8.3.0, blocks have a "status" of either enabled or disabled, and disabled blocks are the equivalent of unpublished. And so this function fails to load a block unless it's enabled in a region.

When you update from 8.2 to 8.3, you may have noticed that there's no longer a "Disabled" region for blocks -- blocks all end up in an actual block region, but are set to disabled status.

Twig Tweak has added a second parameter, "use access checks", to allow bypassing the disabled status -- this needs to get set to False to get public blocks to show up. I'm not sure whether you can actually use the block visibility rules for the block aside from this disabled/enabled status, but this is what we needed to set in the templates to make the blocks re-appear.

Upgrade in safety

Upgrades are a tricky thing, and it's not unusual for small things like this to crop up with any update. This is why we highly recommend having a testing pipeline set up to test upgrades, and not just applying upgrades on a production site. Check out our Drupal Protection plan if you'd like assistance testing all updates before pushing them live!