feca-mailshots-plugin/results/nunjucks_replacement_findings_2026-04-20.md

Nunjucks Replacement Findings (2026-04-20)

Scope

Investigate a PHP templating replacement for Nunjucks with emphasis on required behavior from samples/invoicing.html:

• conditional line break behavior (br(text) suppresses <br> when absent)
• helper-style asset insertion (pdf_asset(...))

Candidate Tested

• twig/twig v3.24.0

Spike Implementation

Spike script:

• working/codex-spikes/twig_spike.php

Rendered output:

• working/twig/invoicing.twig.rendered.html

What was implemented in the spike:

1. pdf_asset(name) as a Twig helper function (HTML-safe return).
2. br(text) as a Twig helper function with Nunjucks-equivalent effect:
   • returns "" when value is empty/missing
   • returns "<value><br>" when present

Findings

1. Template rendered successfully with Twig.
2. pdf_asset('FenEdgeLogoOrange') helper call rendered correctly as helper output placeholder.
3. br(address_2) with empty value produced no <br>, meeting the required behavior.
4. This satisfies the functional requirement that details of implementation do not matter as long as behavior matches.

Compatibility Notes

• Twig syntax is very close to Nunjucks for variable interpolation, conditionals, filters, and control flow.
• Direct Nunjucks-style macro invocation may differ in strict syntax expectations.
• Where needed, helper functions can be provided to preserve required template behaviors without template redesign.

Recommendation

Adopt Twig as the PHP-side Nunjucks replacement, with a minimal-helper policy:

1. Prefer inline template logic over custom helpers (for example {% if x is not empty %}...{% endif %} instead of br(...)).
2. Minimize or avoid custom helper APIs to reduce discoverability/documentation burden.
3. Where possible, supply required dynamic values directly in render context variables rather than introducing template functions.

Status: Accepted for migration direction based on current requirements and sample behavior.

Decision Update (User Guidance)

User guidance clarified that helper proliferation creates discoverability problems.
Therefore, this investigation records a preference for simple, explicit template code and minimal custom helper surface.