wc-tier-and-package-prices/releases/RELEASE-INFO-1.1.0.md

# WooCommerce Tier and Package Prices - Release 1.1.0

**Release Date:** December 21, 2025
**Version:** 1.1.0
**Package Size:** 387 KB
**Git Tag:** v1.1.0

## Download

**File:** `wc-tier-and-package-prices-1.1.0.zip`

### Checksums

**SHA256:**
```
da6b462f3dc297b282ed0da258b78fd9f2f82f3e76289c4c8fadd1ac9e02c55b
```

**MD5:**
```
ef68125c54b0c10f04ba82d48a98b4aa
```

## What's New in 1.1.0

### Major Features
- ✨ **Package Quantity Restriction** - NEW
  - Limit product purchases to predefined package sizes only
  - Perfect for bulk-only sales, sample packs, or fixed bundle quantities
  - Global and per-product configuration options

### New Settings
- 🌍 **Global Restriction Setting**
  - Enable quantity restrictions site-wide
  - Located in: WooCommerce > Settings > Tier & Package Prices
  - Description: "Limit quantities to defined package sizes only"

- 📦 **Per-Product Restriction Setting**
  - Override global setting on individual products
  - Located in: Product Edit > Package Pricing section
  - Checkbox: "Restrict to Package Quantities"

### Frontend Enhancements
- 🎨 **Enhanced Package Selection UI**
  - Automatic quantity field hiding when restriction is enabled
  - Clear notice: "Choose a package size below"
  - Visual package selection with highlighted states
  - Responsive package selection buttons

- ✅ **Client-Side Validation**
  - JavaScript prevents form submission without package selection
  - Alert message guides users to select a package
  - Real-time visual feedback on selection

### Backend Validation
- 🛡️ **Server-Side Cart Validation**
  - Validates quantity matches defined packages
  - Prevents manual quantity manipulation
  - User-friendly error messages
  - Example: "The quantity 15 is not available for Product Name. Please choose from the available package sizes: 10, 20, 50"

### Technical Improvements
- New method: `WC_TPP_Cart::validate_package_quantity()`
- New method: `WC_TPP_Frontend::maybe_hide_quantity_input()`
- Enhanced `woocommerce_add_to_cart_validation` filter integration
- Added `wc-tpp-restricted-mode` CSS class
- Added `wc-tpp-package-selectable` CSS class for styling
- New product meta key: `_wc_tpp_restrict_to_packages`
- New global option: `wc_tpp_restrict_package_quantities`

### Translations
- Added 7 new translatable strings
- Updated all language files (en_US, de_DE, de_CH_informal)
- All .mo files recompiled with new strings

## Installation

1. Download the ZIP file: `wc-tier-and-package-prices-1.1.0.zip`
2. Log in to your WordPress admin panel
3. Navigate to **Plugins > Add New > Upload Plugin**
4. Choose the downloaded ZIP file
5. Click **Install Now**
6. After installation, click **Activate Plugin**
7. Go to **WooCommerce > Settings > Tier & Package Prices** to configure

### Upgrade from 1.0.x

This is a **minor version** update with new features. No data migration needed.

**Steps:**
1. Deactivate the current version
2. Upload and activate version 1.1.0
3. All existing settings and data will be automatically preserved
4. Review new restriction settings if desired

### Upgrade from 1.0.2

No breaking changes. Safe to upgrade directly. New restriction feature is disabled by default.

### Requirements

- **WordPress:** 6.0 or higher
- **PHP:** 7.4 or higher
- **WooCommerce:** 8.0 or higher

## New Strings Translation Reference

All new strings in this release:

### Settings Page
1. "Restrict to Package Quantities" - Checkbox label
2. "Limit quantities to defined package sizes only" - Checkbox description
3. "When enabled, customers can only purchase..." - Tooltip text

### Product Meta Box
4. "Restrict to Package Quantities" - Checkbox label (same as above)
5. "Only allow quantities defined in packages above" - Tooltip text

### Frontend Display
6. "Choose a package size below" - User notice in restricted mode

### Cart Validation
7. "this product" - Fallback product name
8. "The quantity %1$d is not available for %2$s..." - Error message template

## Use Cases

### Bulk-Only Sales
Enable restriction globally to sell products only in bulk quantities.

**Example:**
- Package 1: 100 units at $500
- Package 2: 250 units at $1,100
- Package 3: 500 units at $2,000

Customers can only purchase these exact quantities.

### Sample Packs
Create fixed sample packs with no custom quantities.

**Example:**
- Starter Pack: 10 items
- Trial Pack: 25 items
- Full Pack: 50 items

### Promotional Bundles
Offer promotional pricing only for specific bundle sizes.

**Example:**
- Holiday Bundle: 12 units (seasonal pricing)
- Party Pack: 24 units (bulk discount)
- Wholesale Bundle: 100 units (wholesale pricing)

## Configuration Examples

### Example 1: Site-Wide Restriction

**Scenario:** All products should only be sold in packages

**Configuration:**
1. Go to WooCommerce > Settings > Tier & Package Prices
2. Check "Restrict to Package Quantities"
3. Save changes
4. Configure package sizes for each product

**Result:** All products with packages defined will enforce quantity restrictions

### Example 2: Per-Product Restriction

**Scenario:** Only specific products need quantity restrictions

**Configuration:**
1. Leave global setting unchecked
2. Edit the specific product
3. Scroll to Package Pricing section
4. Check "Restrict to Package Quantities"
5. Update product

**Result:** Only that product enforces restrictions

### Example 3: Mixed Approach

**Scenario:** Most products are restricted, but some allow custom quantities

**Configuration:**
1. Enable global restriction
2. For products that should allow custom quantities, simply don't define any packages
3. Products without packages defined won't show restrictions

## Feature Compatibility

### Works With
- ✅ WooCommerce 8.0 - 10.0
- ✅ WordPress 6.0+
- ✅ HPOS (High-Performance Order Storage)
- ✅ All WooCommerce themes
- ✅ Tier pricing (can use both features together)
- ✅ Package pricing (required for restriction)
- ✅ All pricing table display positions

### Requirements for Restriction Feature
- Product must have at least one package defined
- Either global or per-product restriction must be enabled
- Package pricing must be enabled in settings

## Package Contents

The installation package includes all files from version 1.0.2 plus:

### Modified Files
- `wc-tier-and-package-prices.php` - Version updated to 1.1.0
- `composer.json` - Version updated to 1.1.0
- `CHANGELOG.md` - Added v1.1.0 section
- `includes/class-wc-tpp-settings.php` - Added restriction setting
- `includes/class-wc-tpp-product-meta.php` - Added per-product checkbox
- `includes/class-wc-tpp-frontend.php` - Added quantity hiding logic
- `includes/class-wc-tpp-cart.php` - Added validation method
- `assets/js/frontend.js` - Added restricted mode handling
- `templates/frontend/package-pricing-display.twig` - Added restriction notice
- `templates/frontend/pricing-table.twig` - Pass restriction flag
- All translation files (.po/.mo) - Updated with new strings

### Complete Directory Structure
```
wc-tier-and-package-prices/
├── assets/
│   ├── css/
│   │   ├── admin.css
│   │   └── frontend.css
│   └── js/
│       ├── admin.js
│       └── frontend.js (UPDATED)
├── includes/
│   ├── class-wc-tpp-admin.php
│   ├── class-wc-tpp-cart.php (UPDATED)
│   ├── class-wc-tpp-frontend.php (UPDATED)
│   ├── class-wc-tpp-product-meta.php (UPDATED)
│   ├── class-wc-tpp-settings.php (UPDATED)
│   └── class-wc-tpp-template-loader.php
├── languages/ (ALL UPDATED)
│   ├── wc-tier-package-prices-de_CH_informal.po/mo
│   ├── wc-tier-package-prices-de_DE.po/mo
│   ├── wc-tier-package-prices-en_US.po/mo
│   └── wc-tier-package-prices.pot
├── templates/
│   ├── admin/
│   │   ├── package-row.twig
│   │   └── tier-row.twig
│   └── frontend/
│       ├── package-pricing-display.twig (UPDATED)
│       ├── pricing-table.twig (UPDATED)
│       └── tier-pricing-table.twig
├── vendor/ (Twig v3.22.2)
├── CHANGELOG.md (UPDATED)
├── composer.json (UPDATED)
└── wc-tier-and-package-prices.php (UPDATED)
```

## Features (Complete List)

### Tier Pricing
- ✅ Quantity-based discount tiers
- ✅ Automatic price calculation
- ✅ Volume discount display

### Package Pricing
- ✅ Fixed-price bundles
- ✅ Custom package labels
- ✅ Multiple package options per product
- ✅ **NEW:** Quantity restriction to packages only

### Admin Features
- ✅ WooCommerce Settings integration
- ✅ Easy-to-use product meta boxes
- ✅ Configurable display positions
- ✅ Native WooCommerce UI
- ✅ **NEW:** Global restriction setting
- ✅ **NEW:** Per-product restriction override

### Frontend Features
- ✅ Beautiful pricing tables (Twig templates)
- ✅ Real-time cart updates
- ✅ Responsive design
- ✅ 3 languages supported
- ✅ **NEW:** Package-only selection mode
- ✅ **NEW:** Automatic quantity field hiding
- ✅ **NEW:** Visual package selection

### Validation & Security
- ✅ **NEW:** Client-side JavaScript validation
- ✅ **NEW:** Server-side cart validation
- ✅ **NEW:** User-friendly error messages
- ✅ WooCommerce HPOS compatible

## Breaking Changes

**None.** This release is fully backward compatible.

The new restriction feature is disabled by default and must be explicitly enabled.

## Migration Notes

### From 1.0.2
- No migration needed
- New settings appear automatically in admin
- Feature is disabled by default

### Settings Location
All settings remain in: **WooCommerce > Settings > Tier & Package Prices**

### Data Preservation
- All existing tier pricing data preserved
- All existing package pricing data preserved
- All product meta data preserved
- No database changes required

## Known Limitations

### Current Version
1. Restriction only works when packages are defined
2. Cannot restrict to tier quantities (only packages)
3. Restriction applies to entire product (no variation-level control)

### Future Enhancements
These features may be added in future versions:
- Variation-level restriction control
- Restrict to tier quantities option
- Minimum/maximum package selection limits

## Support

- **Documentation:** See README.md and CHANGELOG.md
- **Previous Release:** See RELEASE-INFO-1.0.2.md
- **Issues:** https://src.bundespruefstelle.ch/wc-tier-package-prices/issues
- **Author:** Marco Graetsch

## License

GPL v2 or later - https://www.gnu.org/licenses/gpl-2.0.html

---

**Production Ready:** This package includes optimized autoloader and no development dependencies.

**What's Next:** Version 1.1.0 completes the package restriction feature set. Future versions may add variation-level controls and tier quantity restrictions.