Resolving Twig syntax errors in Drupal

The release of Drupal 10.4.0 sees stricter validation rules being applied to Twig templates, which can result in unexpected errors after an upgrade. One such issue involves the use of regular expressions within Twig's matches operator, leading to syntax errors that can break template rendering.

This is a situation I had recently after upgrading to Drupal 10.4.0 and provides a clear resolution for the problem.

The error

After upgrading to Drupal 10.4.0, users may encounter an error similar to the following when rendering templates:

Twig\Error\SyntaxError: Regexp "/s3:///" passed to "matches" is not valid: Unknown modifier '/'. in Twig\Node\Expression\Binary\MatchesBinary::Twig\Node\Expression\Binary\{closure}() (line 165 of themes/custom/{theme}/templates/views/views-view-unformatted--current-alerts.html.twig).

This error occurs when using the matches operator with a regular expression in Twig. The operator internally uses PHP's preg_match function, which requires valid delimiters around the pattern.

The problematic line in the template was this

{% elseif media_path matches '/s3:\/\//' %}

The issue here is that / is used as a delimiter, but the pattern also contains / characters, causing a conflict and resulting in an "Unknown modifier '/'" error.

The solution

To resolve this issue, replace the / delimiter with a different character that does not conflict with the pattern. For example, use # as the delimiter

{% elseif media_path matches '#s3:\/\//#' %}

Alternatively, explicitly escape all forward slashes (/) to avoid conflicts

{% elseif media_path matches '/s3:\\/\\//' %}

The first approach using # as the delimiter is often preferred for its readability and simplicity.

Other impacts of stricter rules in Drupal 10.4.0

Beyond regular expressions, the stricter Twig validation rules in Drupal 10.4.0 can impact templates in the following ways:

1. Strict variable handling:
   1. Variables must be explicitly defined before being used, preventing accidental references to undefined variables
   2. Developers may encounter errors if they attempt to use variables that were implicitly available in earlier versions
2. Syntax validation:
   1. Invalid or deprecated syntax, such as unescaped braces ({{ ... }}) used improperly, now triggers errors
   2. Developers need to ensure all Twig expressions are properly formatted and escape sequences are applied where required
3. Filter enforcement:
   1. Filters applied to variables must be valid and properly registered in the Twig environment
   2. Custom filters must be tested and explicitly defined in the theme or module code
4. Macro and function calls:
   1. Macros and functions need to follow stricter syntax and parameter rules
   2. Any dynamic references or variable manipulations that deviate from the expected syntax may fail

Why the change is necessary

Drupal 10.4.0 enforces stricter syntax validation rules to improve performance and security. Earlier versions of Drupal were more lenient, allowing templates with syntax inconsistencies to render without throwing errors. The updated rules ensure that all templates comply with PHP's syntax standards, reducing the risk of runtime errors.

The wrap

Upgrading to Drupal 10.4.0 can introduce stricter validation rules, highlighting syntax errors that were previously overlooked. By updating regular expressions in Twig templates to use alternative delimiters, developers can ensure compatibility with the latest version.