wc-tier-and-package-prices/CLAUDE.md

# WooCommerce Tier and Package Prices - AI Context Document

**Last Updated:** 2025-12-23
**Current Version:** 1.1.20
**Author:** Marco Graetsch
**Project Status:** Production-ready WordPress plugin

## Project Overview

This is a WooCommerce plugin that adds flexible pricing capabilities to products through two distinct pricing models:

1. **Tier Pricing (Volume Discounts)**: Progressive discounts based on quantity ranges (e.g., 1-9 items @ $12, 10-24 @ $10, 25+ @ $8)
2. **Package Pricing (Fixed Bundles)**: Exact quantity packages at fixed prices (e.g., exactly 10 items for $95, exactly 25 for $200)

### Key Fact: 100% AI-Generated
This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance.

## Technical Stack

- **Language:** PHP 7.4+
- **Framework:** WordPress Plugin API
- **E-commerce:** WooCommerce 8.0+ (tested up to 10.x)
- **Template Engine:** Twig 3.0 (via Composer)
- **Frontend:** Vanilla JavaScript + jQuery
- **Styling:** Custom CSS
- **Dependency Management:** Composer
- **Internationalization:** WordPress i18n (.pot/.po/.mo files)

### Dependencies
```json
{
  "twig/twig": "^3.0",
  "symfony/polyfill-ctype": "^1.x",
  "symfony/polyfill-mbstring": "^1.x"
}
```

## Architecture

### Directory Structure
```
wc-tier-and-package-prices/
├── wc-tier-and-package-prices.php    # Main plugin file (entry point)
├── includes/                         # PHP classes
│   ├── class-wc-tpp-admin.php        # Admin settings integration
│   ├── class-wc-tpp-settings.php     # WooCommerce settings page
│   ├── class-wc-tpp-product-meta.php # Product edit page meta boxes
│   ├── class-wc-tpp-frontend.php     # Product page display logic
│   ├── class-wc-tpp-cart.php         # Cart price calculations
│   └── class-wc-tpp-template-loader.php # Twig template loader
├── templates/                        # Twig templates
│   ├── admin/                       # Admin interface templates
│   │   ├── tier-row.twig           # Single tier input row
│   │   └── package-row.twig        # Single package input row
│   └── frontend/                    # Customer-facing templates
│       ├── pricing-table.twig       # Main pricing display wrapper
│       ├── tier-pricing-table.twig  # Tier pricing display
│       └── package-pricing-display.twig # Package buttons/cards
├── assets/
│   ├── css/
│   │   ├── admin.css               # Backend styling
│   │   └── frontend.css            # Product page & cart styling
│   └── js/
│       ├── admin.js                # Meta box interaction (add/remove rows)
│       └── frontend.js             # Dynamic price updates, package selection
├── languages/                       # Translation files
│   ├── *.pot                       # Translation template
│   ├── *.po                        # Translation sources
│   └── *.mo                        # Compiled translations
├── vendor/                          # Composer dependencies (included in releases)
├── releases/                        # Release packages (not in git)
└── *.md                            # Documentation files

```

### Class Responsibilities

#### 1. `WC_Tier_Package_Prices` (Main Plugin Class)
- **Location:** `wc-tier-and-package-prices.php`
- **Pattern:** Singleton
- **Responsibilities:**
  - Plugin initialization and bootstrapping
  - Loading all component classes via `includes()`
  - HPOS (High-Performance Order Storage) compatibility declaration
  - Text domain loading for internationalization
  - Activation/deactivation hooks

#### 2. `WC_TPP_Admin`
- **Location:** `includes/class-wc-tpp-admin.php`
- **Pattern:** Singleton
- **Responsibilities:**
  - Enqueues admin CSS/JS
  - Registers WooCommerce settings page via filter
  - Manages settings page instance (cached to prevent duplicates)
  - Product meta box asset loading

#### 3. `WC_TPP_Settings`
- **Location:** `includes/class-wc-tpp-settings.php`
- **Extends:** `WC_Settings_Page` (WooCommerce core)
- **Responsibilities:**
  - Creates "Tier & Package Prices" tab in WooCommerce settings
  - Defines global plugin settings (enable/disable features, display position, etc.)
  - Setting persistence through WooCommerce options API

**Global Settings:**
- `wc_tpp_enable_tier_pricing` (yes/no)
- `wc_tpp_enable_package_pricing` (yes/no)
- `wc_tpp_display_table` (yes/no) - Show pricing tables on product pages
- `wc_tpp_display_position` (before_add_to_cart / after_add_to_cart / after_price)
- `wc_tpp_restrict_package_quantities` (yes/no) - Global quantity restrictions

#### 4. `WC_TPP_Product_Meta`
- **Location:** `includes/class-wc-tpp-product-meta.php`
- **Responsibilities:**
  - Adds tier/package pricing fields to product edit page
  - Renders Twig templates for meta box rows
  - Saves tier/package data to post meta
  - Nonce verification and capability checks for security
  - Prevents autosave from corrupting data

**Product Meta Keys:**
- `_wc_tpp_tiers` - Array of tier objects `[{min_qty, price, label}]`
- `_wc_tpp_packages` - Array of package objects `[{qty, price, label}]`
- `_wc_tpp_restrict_to_packages` - Per-product quantity restriction (yes/no)

#### 5. `WC_TPP_Frontend`
- **Location:** `includes/class-wc-tpp-frontend.php`
- **Responsibilities:**
  - Enqueues frontend CSS/JS on product pages
  - Displays pricing tables via Twig templates
  - Localizes currency settings to JavaScript
  - Hides quantity inputs for restricted products
  - Modifies catalog "Add to Cart" buttons to "View Options" for restricted products
  - Static methods for price lookups (`get_tier_price()`, `get_package_price()`)

#### 6. `WC_TPP_Cart`
- **Location:** `includes/class-wc-tpp-cart.php`
- **Responsibilities:**
  - **MOST CRITICAL CLASS** - Handles all cart price calculations
  - Applies tier/package pricing during cart totals calculation
  - Stores pricing metadata in cart items for display
  - Customizes cart item display (price labels, quantity indicators)
  - Validates package quantities on add-to-cart
  - Hides/disables quantity inputs for restricted products (classic cart + blocks)
  - **WooCommerce Blocks support** via `woocommerce_store_api_product_quantity_editable` filter

**Price Calculation Priority (in `apply_tier_package_pricing()`):**
1. Check for exact package match → Use package price if found
2. Check for tier match → Use tier price if found
3. Fall back to regular product price

#### 7. `WC_TPP_Template_Loader`
- **Location:** `includes/class-wc-tpp-template-loader.php`
- **Pattern:** Singleton
- **Responsibilities:**
  - Initializes Twig environment with proper paths
  - Renders Twig templates from both admin and frontend directories
  - Handles template caching and error handling

## Important Implementation Details

### Price Calculation Logic

**Package Pricing** (exact match):
```php
// In cart: if quantity == 10 and package exists for 10, use package price
if ($quantity == $package['qty']) {
    $unit_price = $package['price'] / $quantity;  // Total price divided by quantity
    $product->set_price($unit_price);  // WooCommerce expects unit price
}
```

**Tier Pricing** (range-based):
```php
// In cart: if quantity >= 10, use tier price for quantities 10+
foreach ($tiers as $tier) {
    if ($quantity >= $tier['min_qty']) {
        $applicable_price = $tier['price'];  // This is already unit price
    }
}
$product->set_price($applicable_price);
```

### Quantity Restriction Feature

Products can be configured to ONLY allow purchase in package quantities:

- **Global setting:** `wc_tpp_restrict_package_quantities`
- **Per-product setting:** `_wc_tpp_restrict_to_packages`
- **When enabled:**
  - Quantity inputs are hidden on product page, cart, and mini-cart
  - Customers must use package selection buttons
  - Validation prevents arbitrary quantities from being added
  - Catalog buttons change to "View Options" instead of "Add to Cart"

### WooCommerce Blocks Compatibility

**CRITICAL BUG FIXED in v1.1.20:**
- Filter `woocommerce_store_api_product_quantity_editable` passes `WC_Product` object, NOT cart item array
- Previous code tried to use product object as array → fatal error
- Fixed by accepting product object and using `$product->get_id()`

### Cart Item Metadata

The plugin stores additional data in cart items for display purposes:

```php
WC()->cart->cart_contents[$cart_item_key]['wc_tpp_pricing_type'] = 'package' | 'tier';
WC()->cart->cart_contents[$cart_item_key]['wc_tpp_total_price'] = 99.99;  // For packages
WC()->cart->cart_contents[$cart_item_key]['wc_tpp_unit_price'] = 9.99;   // For tiers
```

This metadata is used by display filters to show "(Package price)" or "(Volume discount)" labels.

## Common Patterns & Conventions

### Class Instantiation Pattern
All classes auto-instantiate at the end of their file:
```php
if (!class_exists('WC_TPP_Frontend')) {
    class WC_TPP_Frontend {
        // class code
    }
}
new WC_TPP_Frontend();  // Auto-instantiate
```

**Exception:** Admin and Settings classes use singleton pattern to prevent duplicates.

### Security Best Practices
- All user inputs are sanitized (integers for quantities/prices)
- Nonce verification on form submissions
- Capability checks (`edit_products`) before saving
- Output escaping in templates (`esc_attr`, `esc_html`, `esc_js`)
- Direct file access prevention via `ABSPATH` check

### Translation Ready
All user-facing strings use:
```php
__('Text to translate', 'wc-tier-package-prices')
_e('Text to translate', 'wc-tier-package-prices')
```

Text domain: `wc-tier-package-prices`

## Known Issues & Historical Context

### Settings Page Duplication Saga (v1.1.15-1.1.19)
Multiple versions attempted to fix settings page appearing twice:
- **Root cause:** Settings file auto-instantiation + Composer autoloader
- **Solution:** Removed auto-instantiation from settings file, explicit instantiation in admin class
- **Prevention:** Singleton pattern + duplicate detection in array

### Class Redeclaration Issues (v1.1.8-1.1.14)
Plugin was completely non-functional:
- **Cause:** Incorrect initialization pattern without `class_exists()` guards
- **Solution:** Added guards and restored direct instantiation pattern
- **Lesson:** Always wrap class declarations in `class_exists()` checks

### WooCommerce Blocks Fatal Error (v1.1.19 → v1.1.20)
```
Fatal error: Cannot use object of type WC_Product_Simple as array
Location: includes/class-wc-tpp-cart.php:233
```
- **Cause:** Filter signature mismatch - expected array, received product object
- **Fix:** Changed method signature to accept `WC_Product $product` instead of `$cart_item` array
- **Status:** FIXED in v1.1.20

## Release Process

### Version Bumping
Update version in 3 places:
1. `wc-tier-and-package-prices.php` - Plugin header comment (line 7)
2. `wc-tier-and-package-prices.php` - `WC_TPP_VERSION` constant (line 26)
3. `composer.json` - version field (optional, not critical)

### Creating Release Package
```bash
# From project root
cd releases

# Create zip excluding dev files
zip -r wc-tier-and-package-prices-X.X.X.zip .. \
  -x '*.git*' '*.log' '.claude/*' 'releases/*' 'node_modules/*' \
  '.DS_Store' 'Thumbs.db' '.vscode/*' '.idea/*' '*.sublime-*' \
  'notes.*' 'logs/*' 'templates/cache/*' 'composer.lock'

# Generate checksums
md5sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.md5
sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.X.zip.sha256
```

**IMPORTANT:** The `vendor/` directory MUST be included in releases (Twig dependency required for runtime).

### What Gets Released
- All plugin source files
- Compiled vendor dependencies
- Translation files (.mo compiled from .po)
- Assets (CSS, JS)
- Documentation (README, CHANGELOG, etc.)

### What's Excluded
- Git metadata (`.git/`)
- Development files (`.vscode/`, `.claude/`, `CLAUDE.md`)
- Logs and cache files
- Previous releases
- `composer.lock` (but `vendor/` is included)

## Testing Checklist

When making changes, test these critical paths:

### Admin
- [ ] Settings page appears once under WooCommerce > Tier & Package Prices
- [ ] Settings save correctly
- [ ] Product edit page shows tier/package meta boxes
- [ ] Adding/removing tiers works
- [ ] Adding/removing packages works
- [ ] Data saves when clicking "Update" on product

### Frontend (Product Page)
- [ ] Pricing tables display when configured
- [ ] Package buttons update quantity selector
- [ ] Price updates dynamically when quantity changes
- [ ] Restricted products hide quantity input
- [ ] "View Options" appears on catalog for restricted products

### Cart & Checkout
- [ ] Correct prices applied for tier pricing
- [ ] Correct prices applied for package pricing
- [ ] Cart displays pricing type labels
- [ ] Package quantities can't be edited if restricted
- [ ] Prices recalculate if quantity changed (non-restricted products)
- [ ] Checkout totals are correct

### WooCommerce Blocks (Critical!)
- [ ] Mini cart block doesn't throw fatal errors
- [ ] Cart block works correctly
- [ ] Checkout block processes orders
- [ ] Quantity editable flag works for blocks

## Development Tips for Future AI Assistants

### When Debugging Cart Issues
1. Check `includes/class-wc-tpp-cart.php` first
2. The `apply_tier_package_pricing()` method runs on `woocommerce_before_calculate_totals`
3. Always validate product objects with `is_a($product, 'WC_Product')`
4. Remember: WooCommerce expects UNIT prices, not total prices (except for internal calculations)

### When Working with WooCommerce Hooks
- WooCommerce has both classic and block-based systems
- Classic cart uses different hooks than Store API (blocks)
- Always check filter/action documentation for parameter types
- Don't assume cart item arrays everywhere - sometimes it's product objects!

### When Adding Features
- Follow the existing pattern: add setting → add UI → add logic → add template
- Use Twig for all new templates (consistency)
- Add translations for all user-facing strings
- Test with both simple products and variable products (if applicable)
- Consider both classic and block-based cart/checkout

### When Fixing Bugs
1. Check `CHANGELOG.md` for historical context
2. Look for similar issues in past versions
3. Always add detailed changelog entry explaining root cause
4. Consider edge cases (guest checkout, logged-in users, AJAX add-to-cart, etc.)

## File Locations Quick Reference

| Task | File(s) |
|------|---------|
| Change version | `wc-tier-and-package-prices.php` (2 places) |
| Add global setting | `includes/class-wc-tpp-settings.php` |
| Modify product meta box | `includes/class-wc-tpp-product-meta.php` + `templates/admin/*.twig` |
| Change product page display | `includes/class-wc-tpp-frontend.php` + `templates/frontend/*.twig` |
| Fix cart pricing | `includes/class-wc-tpp-cart.php` |
| Update styles | `assets/css/frontend.css` or `assets/css/admin.css` |
| Fix JavaScript bugs | `assets/js/frontend.js` or `assets/js/admin.js` |
| Add translations | `languages/*.po` then compile to `.mo` |
| Document changes | `CHANGELOG.md` |

## Compatibility Notes

### WordPress
- Minimum: 6.0
- Tested up to: 6.9.x
- Uses standard plugin API, no deprecated functions

### WooCommerce
- Minimum: 8.0
- Tested up to: 10.x
- HPOS compatible (declared via `FeaturesUtil::declare_compatibility`)
- Blocks compatible (with proper filter handling)

### PHP
- Minimum: 7.4
- Uses modern PHP features (type hints acceptable in new code)
- Composer autoloader handles namespacing

### Browsers
- Modern browsers (ES6+ JavaScript)
- Responsive CSS (mobile-friendly)
- jQuery dependency (WooCommerce provides)

## Support & Resources

- **Repository:** https://src.bundespruefstelle.ch/magdev/wc-tier-package-prices
- **Documentation:** See `README.md`, `QUICKSTART.md`, `USAGE_EXAMPLES.md`, `INSTALLATION.md`
- **Changelog:** `CHANGELOG.md` (detailed version history)
- **Issue Tracking:** Check fatal-errors-*.log files for production errors

## Final Notes

This is a production-quality plugin with real-world usage. Any changes should:
1. Maintain backward compatibility with existing tier/package configurations
2. Not break WooCommerce core functionality
3. Work with both classic and block-based themes
4. Be thoroughly tested before release
5. Include proper error handling and validation
6. Update CHANGELOG.md with detailed explanations

The plugin architecture is solid and well-tested. Most bugs arise from:
- WooCommerce API changes (especially blocks)
- Filter/action signature changes
- Edge cases in cart calculations
- Settings persistence issues

Always refer to this document when starting work on this project. Good luck!