wc-composable-product/README.md

# 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:

   ```bash
   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

```bash
composer install
```

### Running Tests

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

```bash
vendor/bin/phpunit --testdox
```

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

### Translation

Generate POT file:

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

Compile translations:

```bash
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:

```bash
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.