From 054617f320c068b958699ee9be2f3a0693d0ee1b Mon Sep 17 00:00:00 2001 From: magdev Date: Wed, 31 Dec 2025 21:07:20 +0100 Subject: [PATCH] Document v1.1.5 Twig filter bug fix in CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive session history for v1.1.5 including: - Root cause analysis of Twig filter vs function mismatch - Error log evidence and backtrace analysis - Technical solution with code examples - Lessons learned about multi-plugin Twig compatibility - Updated "Bugs found" section marking Twig bug as fixed Also fixed markdown linting warnings: - Added blank line before fenced code block - Added language specification (text) to code fence - Added blank line around list 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8fa26c8..ae8c54f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -250,7 +250,7 @@ unzip -l wc-composable-product-vX.X.X.zip ## Bugs found -- There is a bug related to twig in the frontend area. Documented in `logs/fatal-errors*.log` +- ✅ ~~There is a bug related to twig in the frontend area. Documented in `logs/fatal-errors*.log`~~ **FIXED in v1.1.5** - Translate the admin area, too ## Session History @@ -741,6 +741,92 @@ Added a dedicated fixed price field to the Composable Options tab that appears/h --- +### v1.1.5 - Critical Twig Filter Bug Fix (2025-12-31) + +#### Session 8: Twig Template Compatibility Fix + +**Critical bug fix** resolving template rendering errors when other plugins use Twig. + +**The bug:** + +Plugin crashed with `Twig\Error\SyntaxError: Unknown "esc_attr" filter` when rendering the product selector template on the frontend. + +**Root cause analysis:** + +1. **Filter vs Function mismatch**: The template used filter syntax (`{{ product.name|esc_attr }}`), but WordPress escaping functions were only registered as Twig **functions**, not **filters** +2. **Plugin conflict**: When another plugin (e.g., WooCommerce Tier and Package Prices) bundles its own Twig installation, it may parse our templates with its Twig instance +3. **Missing registrations**: That external Twig instance didn't have our custom filters registered, causing the "Unknown filter" error + +**Error log evidence:** + +From [logs/fatal-errors-2025-12-31.log:5](logs/fatal-errors-2025-12-31.log#L5): + +```text +Uncaught Twig\Error\SyntaxError: Unknown "esc_attr" filter in "product-selector.twig" at line 26 +``` + +The backtrace showed the error originated from `/wp-content/plugins/wc-tier-and-package-prices/vendor/twig/twig/`, proving another plugin's Twig instance was parsing our template. + +**The fix:** + +Added Twig filter registrations alongside existing function registrations in [includes/Plugin.php:88-91](includes/Plugin.php#L88-L91): + +```php +// Add WordPress escaping functions as Twig filters +$this->twig->addFilter(new \Twig\TwigFilter('esc_html', 'esc_html')); +$this->twig->addFilter(new \Twig\TwigFilter('esc_attr', 'esc_attr')); +$this->twig->addFilter(new \Twig\TwigFilter('esc_url', 'esc_url')); +``` + +This allows both syntaxes to work: + +- Filter syntax: `{{ product.name|esc_attr }}` ✅ +- Function syntax: `{{ esc_attr(product.name) }}` ✅ + +**Files modified:** + +- includes/Plugin.php: + - Lines 88-91: Added TwigFilter registrations for WordPress escaping functions +- wc-composable-product.php: + - Lines 6, 22: Version bump to 1.1.5 +- CHANGELOG.md: Added v1.1.5 release notes with technical details + +**What works (v1.1.5):** + +Everything from v1.1.4 plus: + +- Product selector template renders without errors ✅ +- Compatible with plugins that bundle Twig (e.g., pricing plugins) ✅ +- WordPress escaping works with both filter and function syntax ✅ +- No more "Unknown filter" errors ✅ + +**Key lessons learned:** + +1. **Filter vs Function Registration**: In Twig, `{{ value|filter }}` requires `TwigFilter`, while `{{ function(value) }}` requires `TwigFunction` - they're not interchangeable +2. **Multiple Twig Instances**: WordPress plugins may bundle their own Twig installations that can parse other plugins' templates +3. **Template Syntax Matters**: Using filter syntax in templates requires filter registration, even if function registration exists +4. **Defensive Compatibility**: Register WordPress functions as BOTH filters and functions for maximum compatibility +5. **Error Log Investigation**: Backtrace reveals which Twig instance is parsing the template, crucial for diagnosing multi-plugin conflicts +6. **Template Location Doesn't Matter**: Even though our template is in our plugin directory, other Twig instances can still parse it during rendering + +**Debugging approach:** + +1. User mentioned Twig bug in CLAUDE.md "Bugs found" section +2. Checked `logs/fatal-errors-2025-12-31.log` and found the exact error +3. Analyzed backtrace showing external Twig instance from another plugin +4. Examined template and found filter syntax (`|esc_attr`) +5. Checked Plugin.php and discovered only function registrations existed +6. Added filter registrations alongside function registrations +7. Committed fix with detailed explanation + +**Impact:** + +This was a **critical bug** preventing the plugin from working on sites with certain other WooCommerce extensions installed. Users would see a blank page or error when viewing composable products. + +**Status:** Fixed and committed to dev branch (8fc0614) + +--- + **For AI Assistants:** When starting a new session on this project: