# WP Rocket Compatibility for Prodigy Commerce Plugin

## Overview

This document explains the WP Rocket compatibility implementation for the Prodigy Commerce WordPress plugin. The compatibility layer ensures that Prodigy works seamlessly with WP Rocket's caching and optimization features.

## Features Implemented

### 1. Automatic Detection
- Automatically detects if WP Rocket is active
- Only loads compatibility features when needed
- No performance impact when WP Rocket is not installed

### 2. Cache Exclusions
- **Dynamic Pages**: Cart, checkout, user account pages are excluded from caching
- **Product Pages**: Individual product pages with dynamic content are excluded
- **AJAX Requests**: All Prodigy AJAX endpoints are excluded
- **User Sessions**: Pages with logged-in users are excluded

### 3. Script and CSS Optimization
- **JavaScript Files**: All Prodigy scripts are excluded from minification and concatenation
- **CSS Files**: All Prodigy stylesheets are excluded from optimization
- **Inline Scripts**: Prodigy-specific inline JavaScript is preserved
- **External Scripts**: Google Analytics and reCAPTCHA scripts are excluded

### 4. Cookie Management
- **Dynamic Cookies**: Prodigy user session cookies are marked as dynamic
- **Cache Rejection**: User authentication cookies prevent caching
- **Session Handling**: Proper session management with WP Rocket

### 5. Cache Busting
- **Version Parameters**: Cache-busting parameters added to all assets
- **Timestamp Parameters**: Additional timestamp parameters for better cache control
- **Automatic Updates**: Cache is automatically purged when content is updated

### 6. Lazy Loading
- **Image Exclusions**: Prodigy product images are excluded from lazy loading
- **Gallery Images**: Product gallery images are preserved
- **Custom Attributes**: Prodigy-specific image attributes are respected

## Implementation Details

### Main Compatibility Class
```php
includes/class-prodigy-wp-rocket-compatibility.php
```

This class handles all WP Rocket compatibility features:

- **Cache Exclusions**: Excludes Prodigy pages and content from caching
- **Script Optimization**: Prevents optimization of Prodigy scripts
- **Cookie Management**: Handles user session cookies properly
- **Cache Busting**: Adds cache-busting parameters to assets

### Integration Points

#### 1. Main Plugin Class
```php
includes/class-prodigy.php
```
- Initializes WP Rocket compatibility
- Loads compatibility class when needed

#### 2. Public Scripts
```php
includes/frontend/class-prodigy-public.php
```
- Adds cache-busting to all enqueued scripts
- Optimizes script loading order
- Adds WP Rocket detection to script data

#### 3. Template Functions
```php
includes/frontend/prodigy-template-functions.php
```
- Adds cache-busting to shortcode scripts
- Ensures proper script loading

## Configuration

### Automatic Configuration
The compatibility layer works automatically without any configuration needed. However, you can customize the behavior:

### Manual Cache Purging
```php
// Purge cache when Prodigy content is updated
do_action( 'prodigy_content_updated' );
```

### Custom Exclusions
You can add custom exclusions by filtering the arrays:

```php
// Add custom JavaScript exclusions
add_filter( 'rocket_exclude_js', function( $excluded_files ) {
    $excluded_files[] = 'your-custom-script';
    return $excluded_files;
});

// Add custom CSS exclusions
add_filter( 'rocket_exclude_css', function( $excluded_files ) {
    $excluded_files[] = 'your-custom-style';
    return $excluded_files;
});
```

## WP Rocket Settings Recommendations

### 1. File Optimization
- **Minify HTML**: Enabled
- **Minify CSS**: Enabled (Prodigy CSS will be automatically excluded)
- **Minify JavaScript**: Enabled (Prodigy JS will be automatically excluded)
- **Combine CSS**: Enabled
- **Combine JavaScript**: Enabled

### 2. Media
- **LazyLoad**: Enabled (Prodigy images will be automatically excluded)
- **WebP**: Enabled
- **Responsive Images**: Enabled

### 3. Preload
- **DNS Prefetch**: Enabled
- **Preload Fonts**: Enabled
- **Preload Links**: Enabled

### 4. Advanced Rules
- **Never Cache URLs**: Prodigy URLs will be automatically added
- **Never Cache Cookies**: Prodigy cookies will be automatically added
- **Never Cache User Agents**: No specific exclusions needed

## Testing

### 1. Cache Functionality
- Test cart functionality with caching enabled
- Verify user sessions work properly
- Check product pages load correctly

### 2. Performance
- Run performance tests with WP Rocket enabled
- Compare page load times with and without caching
- Verify script loading order is correct

### 3. Compatibility
- Test with different themes
- Verify shortcodes work properly
- Check AJAX functionality

## Troubleshooting

### Common Issues

#### 1. Cart Not Working
**Problem**: Cart functionality breaks with WP Rocket enabled
**Solution**: Check that cart page is excluded from cache

#### 2. User Sessions Lost
**Problem**: Users are logged out unexpectedly
**Solution**: Verify user cookies are in the dynamic cookies list

#### 3. Scripts Not Loading
**Problem**: Prodigy scripts are not loading properly
**Solution**: Check script exclusions in WP Rocket settings

#### 4. Images Not Loading
**Problem**: Product images don't load with lazy loading
**Solution**: Verify Prodigy images are excluded from lazy loading

### Debug Mode
Enable debug mode to see compatibility information:

```php
// Add to wp-config.php for debugging
define( 'PRODIGY_DEBUG_MODE', true );
```

### Manual Cache Clearing
If issues persist, manually clear WP Rocket cache:

```php
// Clear all WP Rocket cache
if ( function_exists( 'rocket_clean_domain' ) ) {
    rocket_clean_domain();
}
```

## Performance Impact

### Minimal Overhead
- Compatibility checks only run when WP Rocket is active
- No additional database queries
- Minimal memory usage

### Benefits
- Improved page load times through caching
- Better user experience
- Reduced server load
- Optimized asset delivery

## Future Enhancements

### Planned Features
- CDN integration for Prodigy assets
- Advanced cache warming for product pages
- Mobile-specific optimizations
- A/B testing support

### Customization Options
- User-configurable cache exclusions
- Performance monitoring integration
- Advanced cache purging strategies

## Support

For issues related to WP Rocket compatibility:

1. Check this documentation
2. Verify WP Rocket settings
3. Test with default theme
4. Contact Prodigy support

## Version History

- **v1.0.0**: Initial implementation
  - Basic cache exclusions
  - Script optimization compatibility
  - Cookie management
  - Cache busting

## License

This compatibility layer is part of the Prodigy Commerce plugin and follows the same license terms.