The three migration trolls: PHP, CSS, Tokens in content.

Planning an upgrade to Drupal 8? Chances are, you'll run into the usual upgrade trolls - snippets of code in your content, that looked fine before the upgrade, but break after the upgrade. What are those trolls, why are they so pesky, and how can they be handled?

1. PHP in Database.

A techy troll. You may not know that, but some developers like to add PHP snippets in blocks and nodes. PHP snippets start with <?php and end with ?>. Sometimes, developers insert them to add logic and functionality to web pages and blocks.

Placing PHP in database is considered a bad practice in Drupal development. It breaks the development principle of separating content, design, and functionality. Having PHP in content and blocks can break the site. When undetected and unhandled, calls to deprecated and missing functions remain after the upgrade, breaking the site when the containing page is visited. Usually, bad practices are carried out by developers, who don’t specialize in Drupal, and have not spent significant time getting to review the standards.

The correct way of handling PHP in content is to find all such cases, and move the logic and functionality out into modules and theme template.php files.

Indication: <?php and ?> tags in content and blocks.
Results: Broken pages and error messages.
Solution: Move PHP out into modules and themes.

2. CSS in Database.

A stylish troll. This troll usually bugs websites, that like to have each page look special, like printed media. This starts with your designer design each internal page individually. Then, a developer has to style each internal page individually. Because the easiest way to selectively load styling is to insert it in content, some developers, who don’t adhere to best practices, just do it. After your site is upgraded, and the theme is changed, all those pages suddenly become visually incompatible with the new site.

The correct way to add styles to specific pages is to put them in CSS files in theme, and conditionally load them. Also, specific pages content should never be designed in such a way, as to make it unusable with another theme. If the choice is made to include CSS in database, at least make it a separate field, that can easily be found and disabled.

Another way how CSS gets in content is through the intrusive text editors. All advanced text editors, such as the acclaimed CKEditor, sometimes perform formatting of inserted text, inserting large amounts of CSS styling, invisible to a viewer, but bloating the code immensely.

When inserted to specific tags, styling becomes very hard and tedious to change and remove.

Indication: <style> and <tag style=”...”> tags in content and blocks.
Results: Inconsistent theming, that can’t easily be overridden by the theme layer.
Solution: Remove the styles or moved them into theme layer.

3. Tokens in Database.

A ninja troll. Tokens are placeholders, provided by the Token module and many other modules that interact with Token. They look like this: [node:title]. When Token module finds a token, it replaces it with it’s placeholder value. However, during an upgrade, when modules are upgraded, and some modules are replaced with alternatives, these tokens can be left unhandled.

Placing tokens in content is not really a “don’t”, but is very undesirable, and can cause certain problems during an upgrade. The least of the problems that a broken token can cause, is that it won’t be handled, and you will have the actual token, like [node:title], in your text, and not even be aware about it. The worst problem it can cause is a php error.

If tokens have been used in content and blocks, they need to be identified and corrected, or removed.

Indication: [ : ] in content and blocks.
Results: Unreplaced, unhandled tokens, or even php errors.
Solution: Remove tokens, or replace with newer versions of tokens.

A Helpful Tool.

I have a small module that searches for the cases of PHP, CSS, and tokens in Drupal 7 database, and presents a report. This module can be found in my sandbox at http://drupal.org/sandbox/alexrayu/2179797 - feel free to pull and use, and send me suggestions and changes if you have any.