wc-composable-product/INSTALL.md

# Installation Guide

## Requirements

Before installing the WooCommerce Composable Products plugin, ensure your system meets these requirements:

- **PHP**: 8.3 or higher
- **WordPress**: 6.0 or higher
- **WooCommerce**: 8.0 or higher
- **Composer**: For dependency management

## Installation Steps

### 1. Upload Plugin Files

Upload the plugin directory to your WordPress installation:

```bash
/wp-content/plugins/wc-composable-product/
```

### 2. Install Dependencies

Navigate to the plugin directory and install dependencies:

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

### 3. Activate Plugin

1. Log in to your WordPress admin panel
2. Navigate to **Plugins > Installed Plugins**
3. Find "WooCommerce Composable Products"
4. Click **Activate**

### 4. Configure Settings

After activation, configure the plugin:

1. Navigate to **WooCommerce > Settings**
2. Click on the **Composable Products** tab
3. Configure default settings:
   - **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 Your First Composable Product

### Step 1: Create a New Product

1. Go to **Products > Add New**
2. Enter a product name (e.g., "Custom Sticker Pack")

### Step 2: Set Product Type

1. In the **Product Data** panel, select **Composable product** from the dropdown

### Step 3: Configure General Settings

In the **General** tab:
- Set a **Regular price** (used if pricing mode is "Fixed")
- Configure **Selection Limit** (leave empty to use global default)
- Choose **Pricing Mode** (leave empty to use global default)

### Step 4: Configure Composable Options

Click on the **Composable Options** tab:

1. **Selection Criteria**: Choose how to select available products
   - **By Category**: Select product categories
   - **By Tag**: Select product tags
   - **By SKU**: Enter comma-separated SKUs

2. Based on your selection:
   - **Categories**: Select one or more categories from the dropdown
   - **Tags**: Select one or more tags from the dropdown
   - **SKUs**: Enter SKUs like: `STICKER-01, STICKER-02, STICKER-03`

### Step 5: Publish

Click **Publish** to make your composable product live.

## Frontend Usage

When customers visit your composable product:

1. They see a grid of available products based on your criteria
2. They can select up to the configured limit
3. The total price updates in real-time (if using sum pricing mode)
4. Click "Add to Cart" to add the composition to their cart
5. Selected products are displayed in the cart

## Troubleshooting

### Plugin Won't Activate

- Ensure WooCommerce is installed and activated first
- Check PHP version (must be 8.3+)
- Verify Composer dependencies are installed

### Products Not Showing in Selector

- Check that products are published and in stock
- Verify the selection criteria (category/tag/SKU) is correct
- Ensure products match the criteria you configured

### Twig Template Errors

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

### JavaScript Not Working

- Clear browser cache
- Check browser console for errors
- Ensure jQuery is loaded (WooCommerce includes it)

## Updating

When updating the plugin:

1. Deactivate the plugin
2. Replace plugin files
3. Run `composer install --no-dev --optimize-autoloader`
4. Reactivate the plugin
5. Clear all caches (WordPress, browser, CDN)

## Uninstallation

To completely remove the plugin:

1. Deactivate the plugin
2. Delete the plugin from the Plugins page
3. Optionally clean up database entries (WooCommerce will handle this automatically)

## Support

For issues and feature requests:
- GitHub: https://github.com/magdev/wc-composable-product/issues
- Documentation: See README.md

## Next Steps

- Customize the template by editing `templates/product-selector.twig`
- Modify styles in `assets/css/frontend.css`
- Translate the plugin using the provided `.pot` file
- Create categories/tags for easier product organization