# 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.