WooCommerce Composable Products

Create composable products where customers can select a limited number of items from a configurable set of products. Think of it as a "build your own gift box" or "create your sticker pack" feature.

Key Features

• Custom Product Type: New "Composable Product" type in WooCommerce
• Flexible Selection: Define available products by category, tag, or SKU
• Variable Product Support: Automatically expands variable products into selectable variations
• Stock Management: Real-time stock validation, visual indicators, and automatic inventory tracking
• Configurable Limits: Set global or per-product selection limits
• Pricing Options: Fixed price or sum of selected products with full locale-aware formatting
• Multi-language Support: Fully translated in 6 locales (de_DE, de_CH, fr_CH, it_CH + informal variants)
• Modern UI: Clean interface built with Twig templates and vanilla JavaScript
• Tested: 57 unit tests with PHPUnit, Brain Monkey, and Mockery
• CI/CD: Automated release workflow with test gate for Gitea

Requirements

• PHP 8.3 or higher
• WordPress 6.0 or higher
• WooCommerce 8.0 or higher
• Composer (for dependency management)

Installation

From Release Package

1. Download the latest release ZIP from the releases page
2. In WordPress admin, go to Plugins > Add New > Upload Plugin
3. Upload the ZIP file and click Install Now
4. Activate the plugin through the Plugins menu
5. Configure global settings under WooCommerce > Settings > Composable Products

From Source

1. Upload the plugin directory to /wp-content/plugins/wc-composable-product/

2. Install dependencies:

   cd /wp-content/plugins/wc-composable-product/
   composer install --no-dev --optimize-autoloader
   

3. Activate the plugin through the Plugins menu in WordPress

4. Configure global settings under WooCommerce > Settings > Composable Products

Usage

Global Settings

Navigate to WooCommerce > Settings > Composable Products to configure:

• Default Selection Limit: Number of items customers can select (default: 5)
• Default Pricing Mode: Choose between "Sum of selected products" or "Fixed price"
• Display Options: Toggle product images, prices, and totals

Creating a Composable Product

1. Go to Products > Add New
2. Select Composable product from the Product Data dropdown
3. In the General tab:
   • Set a Regular price (used when pricing mode is "Fixed")
   • Configure Selection Limit (leave empty to use global default)
   • Choose Pricing Mode (leave empty to use global default)
4. Click the Composable Options tab:
   • Selection Criteria: Choose how to define available products
     • By Category: Select one or more product categories
     • By Tag: Select one or more product tags
     • By SKU: Enter comma-separated SKUs (e.g., STICKER-01, STICKER-02)
5. Click Publish

Frontend Behavior

When customers visit a composable product page:

1. A grid of available products is displayed based on configured criteria
2. Customers select up to the configured limit via checkboxes
3. Total price updates in real-time (in sum pricing mode)
4. Stock indicators show availability (green/orange/red badges)
5. Click "Add to Cart" to add the composition to cart
6. Selected products are listed in the cart and checkout

Troubleshooting

Plugin Won't Activate

• Ensure WooCommerce is installed and activated first
• Check PHP version (must be 8.3+)
• Verify Composer dependencies are installed (vendor/ directory exists)

Products Not Showing in Selector

• Check that products are published
• Verify the selection criteria (category/tag/SKU) matches existing products
• Ensure the criteria type and values are saved in the Composable Options tab

Twig Template Errors

• Ensure the vendor/ directory exists and contains Twig
• Run composer install again
• Check that the cache/ directory is writable

Updating

1. Deactivate the plugin
2. Replace plugin files (or upload new release ZIP)
3. If installed from source: run composer install --no-dev --optimize-autoloader
4. Reactivate the plugin
5. Clear all caches (WordPress, browser, CDN)

Development

This project was created with AI assistance (Claude.AI) and follows WordPress and WooCommerce best practices.

Building from Source

composer install

Running Tests

The plugin includes a PHPUnit test suite with Brain Monkey for WordPress function mocking:

vendor/bin/phpunit --testdox

Tests run without a WordPress installation. WooCommerce classes are provided as minimal stubs in tests/stubs/.

Translation

Generate POT file:

wp i18n make-pot . languages/wc-composable-product.pot

Compile translations:

for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done

Creating Releases

Releases are automated via Gitea CI/CD. Push an annotated tag to trigger:

git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

The workflow builds the release ZIP, compiles translations, generates checksums, and creates a Gitea release with attachments.

License

GPL v3 or later - see LICENSE file for details

Author

Marco Graetsch

Support

For issues and feature requests, please use the issue tracker.