diff --git a/CLAUDE.md b/CLAUDE.md index c131efe..34d40f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -301,7 +301,7 @@ sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X. ### What's Excluded - Git metadata (`.git/`) -- Development files (`.vscode/`, `.idea/`, `.claude/`, `CLAUDE.md`) +- Development files (`.vscode/`, `.claude/`, `CLAUDE.md`) - Logs and cache files - Previous releases - `composer.lock` (but `vendor/` is included) diff --git a/INSTALLATION.md b/INSTALLATION.md index af191ba..5083989 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -90,8 +90,8 @@ After activation, you should see: Before installation, verify: -- ✓ WordPress 5.8 or higher -- ✓ WooCommerce 5.0 or higher installed and activated +- ✓ WordPress 6.0 or higher (tested up to 6.9.x) +- ✓ WooCommerce 8.0 or higher (tested up to 10.x) installed and activated - ✓ PHP 7.4 or higher - ✓ Write permissions in `/wp-content/plugins/` directory @@ -153,16 +153,34 @@ wp-content/ ├── USAGE_EXAMPLES.md ├── includes/ │ ├── class-wc-tpp-admin.php + │ ├── class-wc-tpp-settings.php │ ├── class-wc-tpp-cart.php │ ├── class-wc-tpp-frontend.php - │ └── class-wc-tpp-product-meta.php - └── assets/ - ├── css/ - │ ├── admin.css - │ └── frontend.css - └── js/ - ├── admin.js - └── frontend.js + │ ├── class-wc-tpp-product-meta.php + │ └── class-wc-tpp-template-loader.php + ├── templates/ + │ ├── admin/ + │ │ ├── tier-row.twig + │ │ └── package-row.twig + │ └── frontend/ + │ ├── pricing-table.twig + │ ├── tier-pricing-table.twig + │ └── package-pricing-display.twig + ├── assets/ + │ ├── css/ + │ │ ├── admin.css + │ │ └── frontend.css + │ └── js/ + │ ├── admin.js + │ └── frontend.js + ├── languages/ + │ ├── wc-tier-package-prices.pot + │ ├── wc-tier-package-prices-de_DE.po + │ ├── wc-tier-package-prices-de_DE.mo + │ ├── wc-tier-package-prices-de_CH_informal.po + │ └── wc-tier-package-prices-de_CH_informal.mo + └── vendor/ + └── (Twig and dependencies) ``` ## Getting Help diff --git a/QUICKSTART.md b/QUICKSTART.md index 5cf3f70..1cb7f80 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,6 +1,6 @@ # Quick Start Guide -Get started with WooCommerce Tier and Package Prices in 5 minutes! +Get started with WooCommerce Tier and Package Prices (v1.1.20) in 5 minutes! ## Step 1: Install (2 minutes) @@ -79,8 +79,11 @@ Use packages for common bundles (6-pack, dozen, case) 1. **Round Numbers**: Use 10, 25, 50, 100 for tiers 2. **Meaningful Savings**: Offer at least 10% off per tier 3. **Label Packages**: "Family Pack" sells better than "4-pack" -4. **Test Checkout**: Always complete a test order -5. **Mobile Check**: View on phone to verify responsiveness +4. **Label Tiers**: Use descriptive labels like "Wholesale Price" or "Bulk Discount" +5. **Test Checkout**: Always complete a test order +6. **Mobile Check**: View on phone to verify responsiveness +7. **Quantity Restrictions**: Enable package restrictions to prevent arbitrary quantities +8. **Blocks Compatible**: Works with both classic and block-based carts/checkout ## Need More Help? diff --git a/README.md b/README.md index 4a05790..25ec75e 100644 --- a/README.md +++ b/README.md @@ -110,12 +110,22 @@ When editing a product, scroll to the **Product data** panel: ``` wc-tier-and-package-prices/ -├── wc-tier-and-package-prices.php # Main plugin file +├── wc-tier-and-package-prices.php # Main plugin file (v1.1.20) ├── includes/ -│ ├── class-wc-tpp-admin.php # Admin settings +│ ├── class-wc-tpp-admin.php # Admin settings integration +│ ├── class-wc-tpp-settings.php # WooCommerce settings page │ ├── class-wc-tpp-product-meta.php # Product meta boxes -│ ├── class-wc-tpp-frontend.php # Frontend display -│ └── class-wc-tpp-cart.php # Cart price calculations +│ ├── class-wc-tpp-frontend.php # Frontend display logic +│ ├── class-wc-tpp-cart.php # Cart price calculations +│ └── class-wc-tpp-template-loader.php # Twig template engine +├── templates/ +│ ├── admin/ +│ │ ├── tier-row.twig # Tier pricing input row +│ │ └── package-row.twig # Package pricing input row +│ └── frontend/ +│ ├── pricing-table.twig # Main pricing display wrapper +│ ├── tier-pricing-table.twig # Tier pricing table +│ └── package-pricing-display.twig # Package selection UI ├── assets/ │ ├── css/ │ │ ├── admin.css # Admin styles @@ -123,7 +133,16 @@ wc-tier-and-package-prices/ │ └── js/ │ ├── admin.js # Admin JavaScript │ └── frontend.js # Frontend JavaScript -└── README.md +├── languages/ +│ ├── wc-tier-package-prices.pot # Translation template +│ ├── wc-tier-package-prices-*.po # Translation sources +│ └── wc-tier-package-prices-*.mo # Compiled translations +├── vendor/ # Composer dependencies (Twig) +├── CHANGELOG.md # Complete version history +├── INSTALLATION.md # Installation guide +├── QUICKSTART.md # Quick start guide +├── USAGE_EXAMPLES.md # Usage examples +└── README.md # This file ``` ## Requirements @@ -164,39 +183,51 @@ This plugin is licensed under the GPL v2 or later. ## Changelog -### Version 1.0.0 - 2025-12-21 +### Version 1.1.20 - 2025-12-23 -#### Compatibility Updates +**Current Release** - Latest stable version with full WooCommerce Blocks support -- ✅ Updated for WooCommerce 10.x compatibility -- ✅ Updated for WordPress 6.9.x compatibility -- ✅ Added HPOS (High-Performance Order Storage) support -- ✅ Declared compatibility with WooCommerce Custom Order Tables +#### Fixed +- **CRITICAL:** WooCommerce Blocks fatal error in mini-cart and cart blocks +- Fixed `woocommerce_store_api_product_quantity_editable` filter signature mismatch +- Filter now correctly accepts `WC_Product` object instead of cart item array +- Resolves "Cannot use object of type WC_Product_Simple as array" fatal error -#### Security Enhancements +#### Technical Details +- Updated `block_quantity_editable()` method signature to accept product object +- Changed parameter from `$cart_item` array to `WC_Product $product` +- Uses `$product->get_id()` instead of array access for product ID +- Full compatibility with WooCommerce Store API and block-based cart/checkout -- ✅ Added nonce verification for product meta save operations -- ✅ Added capability checks for user permissions -- ✅ Enhanced data escaping and sanitization -- ✅ Implemented autosave prevention +### Recent Major Updates -#### Code Improvements +#### Version 1.1.7 - Enhanced Tier Pricing +- Added optional text labels for tier pricing +- Clickable tier rows that auto-populate quantity field +- Add to Cart button auto-disable when quantity is invalid -- ✅ Enhanced cart object validation -- ✅ Improved product object type checking -- ✅ Better error handling for edge cases -- ✅ Updated data storage methods for cart items -- ✅ Modernized JavaScript localization with proper escaping +#### Version 1.1.4 - WooCommerce Blocks Support +- Full support for WooCommerce block-based cart and checkout +- Quantity restrictions work with both classic and block carts +- Enhanced "View Options" button styling -#### Initial Features +#### Version 1.1.0 - Package Quantity Restrictions +- Global and per-product package quantity restrictions +- Prevents customers from ordering non-package quantities +- Automatic quantity field hiding when restrictions enabled -- Initial release with tier pricing functionality -- Package pricing with fixed quantities -- Customizable pricing tables -- Global settings page -- Product-level configuration -- Cart integration with dynamic pricing -- Responsive frontend design +#### Version 1.0.1 - Twig Template Engine +- Migrated to Twig templating system +- Enhanced security with automatic HTML escaping +- Added German (Switzerland, Informal) translation + +#### Version 1.0.0 - Initial Release +- Tier pricing functionality (quantity-based discounts) +- Package pricing functionality (fixed-price bundles) +- WooCommerce HPOS compatibility +- Multilingual support (English, German) + +For complete version history, see [CHANGELOG.md](CHANGELOG.md) ## Credits diff --git a/USAGE_EXAMPLES.md b/USAGE_EXAMPLES.md index 91196bf..d4030c0 100644 --- a/USAGE_EXAMPLES.md +++ b/USAGE_EXAMPLES.md @@ -1,5 +1,8 @@ # Usage Examples +**Plugin Version:** 1.1.20 +**Last Updated:** 2025-12-23 + ## Example 1: T-Shirt Store with Volume Discounts ### Tier Pricing Setup @@ -16,9 +19,9 @@ For a t-shirt that normally costs $20: **How to configure:** 1. Edit your t-shirt product 2. Set regular price to $20.00 -3. Add tier: Min Qty = 10, Price = $18.00 -4. Add tier: Min Qty = 25, Price = $16.00 -5. Add tier: Min Qty = 50, Price = $14.00 +3. Add tier: Min Qty = 10, Price = $18.00, Label = "Bulk Discount" +4. Add tier: Min Qty = 25, Price = $16.00, Label = "Volume Pricing" +5. Add tier: Min Qty = 50, Price = $14.00, Label = "Wholesale Rate" 6. Save product **Customer experience:** @@ -97,6 +100,62 @@ Regular mug price: $10.00 - Package 2: Qty = 4, Price = $32.00, Label = "Family Set" - Package 3: Qty = 10, Price = $70.00, Label = "Office Bundle" +## Example 5: Quantity Restrictions (New in v1.1.0) + +### Party Supplies with Fixed Packages + +For products that should ONLY be sold in specific package quantities: + +**Product:** Balloons - Regular price $1.00 each + +**Package Configuration:** +- Package 1: Qty = 12, Price = $10.00, Label = "Dozen Pack" +- Package 2: Qty = 24, Price = $18.00, Label = "Party Pack" +- Package 3: Qty = 50, Price = $40.00, Label = "Event Pack" + +**How to configure:** +1. Edit balloon product +2. Set regular price to $1.00 +3. Add packages as shown above +4. **Check "Restrict to package quantities only"** (per-product setting) +5. Save product + +**Customer experience:** +- Quantity input field is hidden on product page +- Customer MUST select a package using the package selection buttons +- Attempting to add custom quantities via URL or API will fail with validation error +- Cart displays selected package quantity (cannot be edited) +- "View Options" button appears on shop/category pages instead of "Add to Cart" + +**When to use quantity restrictions:** +- Pre-packaged items (dozen eggs, 6-pack drinks, etc.) +- Products with fixed manufacturing quantities +- Promotional bundles where you don't want individual sales +- Subscription boxes with specific item counts + +## Example 6: Tier Labels for Enhanced UX (New in v1.1.7) + +### Office Supplies with Clickable Tiers + +**Product:** Premium Notebooks - Regular price $8.00 each + +**Tier Configuration with Labels:** +- Tier 1: Min Qty = 5, Price = $7.50, Label = "Small Business Discount" +- Tier 2: Min Qty = 10, Price = $7.00, Label = "Wholesale Pricing" +- Tier 3: Min Qty = 25, Price = $6.50, Label = "Corporate Rate" + +**Customer experience:** +- Tier labels appear below quantity in pricing table (italicized) +- Clicking a tier row auto-fills the quantity field with that tier's minimum quantity +- Smooth scroll animation highlights the quantity field +- Add to Cart button automatically disables when quantity is 0 or invalid + +**Benefits of tier labels:** +- Helps customers understand pricing context +- Makes tiers more appealing with descriptive names +- Improves conversion by highlighting value propositions +- Clickable rows improve user experience + ## Tips for Best Results ### Tier Pricing Best Practices @@ -113,6 +172,11 @@ Regular mug price: $10.00 - Minimum 5-10% per tier level - Higher tiers should have progressively better deals +4. **Use Labels** (v1.1.7+): Add descriptive labels to tiers + - "Wholesale Price" instead of just showing the number + - "Bulk Discount", "Volume Pricing", "Corporate Rate" + - Makes pricing more professional and appealing + ### Package Pricing Best Practices 1. **Strategic Quantities**: Match common use cases @@ -169,3 +233,32 @@ Regular mug price: $10.00 - Package 2: Medium party (25 pieces) = $110 - Package 3: Large party (50 pieces) = $200 - Package 4: Event package (100 pieces) = $350 + +## WooCommerce Blocks Compatibility (v1.1.4+, Fixed in v1.1.20) + +This plugin is **fully compatible** with WooCommerce block-based cart and checkout: + +### Supported Block Types +- Cart Block (`woocommerce/cart`) +- Mini Cart Block (`woocommerce/mini-cart`) +- Checkout Block (`woocommerce/checkout`) +- All Store API endpoints + +### Block-Specific Features +- Quantity restrictions work in block-based carts +- Package-restricted products hide quantity selectors in blocks +- Tier and package pricing applies correctly in block checkout +- Mini cart displays correct prices and restrictions + +### Technical Notes +- v1.1.20 fixed critical fatal error in WooCommerce Blocks +- Uses `woocommerce_store_api_product_quantity_editable` filter +- Works with both classic and block-based themes +- No configuration needed - blocks work automatically + +### Testing Your Block Setup +1. Add block-based cart to a page (`/cart`) +2. Add mini-cart block to your header +3. Add block-based checkout to a page (`/checkout`) +4. Test tier pricing, package pricing, and quantity restrictions +5. Verify prices calculate correctly at checkout