# WooCommerce plugin for user composable products - AI Context Document
**Author:** Marco Graetsch
## Project Overview
This plugin implements a special product type, for which users can select a limited number of product from a configurable set of simple or variable products. The limit of selectable products should be a global and per-product setting, for which global is the fallback. The set of selectable products can be defined per category, tag or SKU. The price is either a fixed price or the sum of the prices of the selected products. Think of a package of stickers as composable product, where each package can contain $limit number of stickers.
### Key Fact: 100% AI-Generated
This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance.
#### Session 5: Fixing Persistent Settings.php Class Loading Issue
**CRITICAL bug fix** that finally resolved the "Class WC_Settings_Page not found" error that persisted through 4 versions (v1.0.0, v1.0.1, v1.1.0, v1.1.1).
**The Journey to the Fix:**
1. v1.0.0: Used `plugins_loaded` hook → Fatal error
2. v1.0.1: Changed to `woocommerce_loaded` → Still failed
3. v1.1.0: Kept `woocommerce_loaded` → Bug continued
4. v1.1.1: Changed to `woocommerce_init` → **STILL FAILING!**
5. v1.1.2: Fixed class loading order → ✅ **WORKING**
**Root cause analysis:**
The error wasn't about hook timing - it was about **when Settings.php was being parsed**:
-`Plugin::includes()` was doing `require_once Settings.php` at line 93
- This happened during plugin initialization (on `woocommerce_init`)
- When PHP parsed Settings.php, it tried to extend `WC_Settings_Page`
- But that parent class didn't exist yet!
- Even `woocommerce_init` fires **before** WooCommerce loads settings page classes
- Result: Instant fatal error
**The fix:**
Delayed Settings.php inclusion until it's actually needed:
The `add_settings_page()` method is called via the `woocommerce_get_settings_pages` filter, which fires when WooCommerce has already loaded all its settings classes, guaranteeing `WC_Settings_Page` exists.
**Files modified:**
- includes/Plugin.php:
- Line 93: Removed `require_once Settings.php`, added explanatory comment
- Line 196: Added `require_once Settings.php` in `add_settings_page()` method
- wc-composable-product.php (version bump to 1.1.2)
- CHANGELOG.md (documented the fix and v1.1.1's failure)
1.**Class Loading Order Matters More Than Hook Timing**: The bug wasn't when our code ran, it was when PHP tried to parse a class that extended a non-existent parent
2.**Always Verify Fixes**: v1.1.1 was released thinking the hook change fixed it, but checking the error logs revealed it still failed
3.**Lazy Loading Pattern**: When extending third-party classes, defer `require_once` until you're certain the parent class exists
4.**Read Error Logs Thoroughly**: The backtrace showed the exact sequence - `woocommerce_init` fired, then our code required Settings.php, then PHP crashed trying to parse the `extends` statement
5.**Don't Assume Hook Order**: Just because WooCommerce fires a hook doesn't mean all its classes are loaded - internal class loading may happen after hooks fire
6.**Test After Each Release**: If this had been tested immediately after v1.1.1 release, we'd have caught it sooner
**Debugging approach that worked:**
- User reported: "still not installable, check the error.log again"
- Checked error log and found v1.1.1 still failing at 15:56:50
- Analyzed backtrace to see Settings.php was being required too early
- Realized `require_once` happens at call time, not when callback runs
- Moved `require_once` to the actual callback when WC guarantees class exists
- Verified fix with PHP syntax check before release
1.**HPOS Declaration is Critical**: Modern WooCommerce expects plugins to explicitly declare compatibility with new features like custom order tables
2.**Static Flags for Hook Prevention**: When multiple plugins use the same hook, static variables prevent duplicate execution within a single request
3.**Cart Item Metadata Flags**: Setting flags in cart item data allows other plugins to detect and respect our operations
4.**Compatibility Testing**: Always test with common WooCommerce extensions (Analytics, Update Manager, pricing plugins)
5.**Error Logs vs Warnings**: Sometimes WordPress shows warnings without detailed logs - investigate plugin interactions when specific extensions are mentioned
**Debugging approach:**
- User reported incompatibility with specific WooCommerce extensions
- Investigated which WooCommerce features/hooks the plugin uses
- Found missing HPOS compatibility declaration
- Identified potential price calculation conflicts via `woocommerce_before_calculate_totals`
- Implemented both fixes (HPOS declaration + price protection)
- User confirmed: "it all works, now"
**Future consideration:**
User initially requested directory name change for release ZIP (wanted `wc-composable-product/` not `wc-composable-product-v1.1.3/`). Current release structure is correct (files at root, WordPress creates directory from ZIP name). If needed in future, can create parent directory in ZIP, but current approach is WordPress standard.
Translation files updated (392559d) to include all 8 stock-related strings across all 5 locales that were missing them (de_DE, de_DE_informal, de_CH, de_CH_informal, fr_CH). All translation files now 100% complete with 55/55 strings.
**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
- 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)
