58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# 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.
|