# CLAUDE.md - WooCommerce Plugin

This file provides guidance to Claude Code when working with the Real ID WooCommerce plugin.

## WordPress Plugin Structure

This is a WordPress plugin located at `apps/wc-plugin/` that provides ID verification functionality for WooCommerce stores.

### Key Files
- `realid.php` - Main plugin file with WordPress headers and version constants
- `readme.txt` - WordPress.org plugin listing with changelog and metadata
- `src/` - React application source code for admin interface
- `includes/` - PHP backend logic, API routes, and WordPress hooks

## Versioning and Changelog

### Version Files
The plugin version must be updated in **two locations**:

1. **`readme.txt`** (line 5):
   ```
   Stable tag: 1.25.2
   ```

2. **`realid.php`** (two places):
   - **Line 8** - WordPress plugin header:
     ```php
     Version: 1.25.2
     ```
   - **Line 45** - PHP constant for internal use:
     ```php
     define("REAL_ID_VERSION", "1.25.2");
     ```

### Changelog Style Guidelines

**Location**: `readme.txt` in the `== Changelog ==` section

**Format Requirements**:
- **One line per change** - Keep entries concise and focused
- **Use bullet points** with asterisk (`*`)
- **Past tense verbs** - "Fixed", "Added", "Updated", "Corrected"
- **Specific and actionable** - Describe what was fixed/changed, not technical implementation details

**Examples of Good Changelog Entries**:
```
* Fixed React app crash when navigating away from Billing settings tab
* Corrected API route path to verify email sender signature and DKIM DNS records
* Added transient error recovery for corrupted cache data
```

**Examples of Poor Changelog Entries**:
```
* Fixed bug in useEffect async function that was causing Promise cleanup issues
* Updated json_decode error handling with try/catch blocks and logging
* Refactored license activation to use getCurrentShop() instead of data.shop
```

### Automated Version Management

**Command**: `/wc:increment-ver`

**Usage**: 
- `/wc:increment-ver` - Increments patch version (default)
- `/wc:increment-ver patch` - Increments patch version (1.0.0 → 1.0.1)
- `/wc:increment-ver minor` - Increments minor version (1.0.0 → 1.1.0) 
- `/wc:increment-ver major` - Increments major version (1.0.0 → 2.0.0)

**What it does**:
1. Determines the next version based on semantic versioning
2. Updates version in `readme.txt` and `realid.php` (both locations)
3. Automatically generates changelog entry based on recent changes and context
4. Uses git differences and current context to summarize changes

**File**: `.claude/commands/wc/increment-ver.md` contains the full automation logic

## Development Guidelines

### PHP Compatibility
- **Minimum PHP Version: 5.6** - All PHP code must be compatible with PHP 5.6 as stated in readme.txt
- **Do NOT use PHP 7+ features** such as:
  - Null coalescing operator (`??`) - Use `isset() ? : ` instead
  - Spaceship operator (`<=>`)
  - Scalar type declarations
  - Return type declarations
  - Anonymous classes
- **Example of PHP 5.6 compatible code**:
  ```php
  // ❌ WRONG - PHP 7+ only
  $value = $params['id'] ?? 'not_provided';
  
  // ✅ CORRECT - PHP 5.6 compatible
  $value = isset($params['id']) ? $params['id'] : 'not_provided';
  ```

### React Components
- All React components are in `src/components/`
- Use proper `useEffect` patterns - never pass async functions directly to `useEffect`
- Handle component cleanup properly to prevent "destroy is not a function" errors

### PHP Backend
- WordPress API routes are defined in `includes/Api.php`
- Use `wc_get_logger()` for consistent logging throughout the plugin
- All transients should store JSON strings, not arrays
- Use the `real_id_reset_transients()` helper to clear corrupted cache data
- Ensure all PHP code is compatible with PHP 5.6

### Error Handling
- Add defensive error handling for `json_decode()` operations on cached data
- Always validate transient data before using it
- Use try/catch blocks around potentially failing operations
- Log errors with structured data for debugging

## Common Issues and Fixes

### "destroy is not a function" Error
- **Cause**: Async function passed directly to `useEffect`
- **Fix**: Create inner async function and call it within the effect

### "json_decode(): Argument #1 must be of type string, array given"
- **Cause**: Transient cache contains array instead of JSON string
- **Fix**: Add error handling with `real_id_reset_transients()` fallback

### React App Crashes After License Activation
- **Cause**: Incomplete shop data missing WordPress-specific fields
- **Fix**: Use `getCurrentShop()` to fetch complete data instead of activation response

## Testing

- Test all Settings tab navigation after making changes
- Verify license activation flow works without crashes
- Check that transient error recovery works properly
- Ensure WordPress plugin headers and versions are consistent