# QDR - Studiou WC Custom Reports

A WordPress plugin that extends WooCommerce with custom reporting functionality for product categories, variants analysis, and customer order summaries.

## Description

This plugin adds advanced reporting capabilities to WooCommerce, allowing you to analyze sales data by product categories, product properties/variants, and customer order history. It provides detailed insights into order counts, revenue, property-based breakdowns, and customer purchasing patterns.

## Features

- **Custom Reports Page**: Advanced filtering and data visualization
- **Product Categories Summary**: Analyze sales by product categories
- **Order Customers List**: View distinct customers with order counts and total spending
- **Dynamic Property Columns**: Show counts by product properties (size, color, etc.)
- **Flexible Date Filtering**: Custom date ranges with preset options
- **Order Status Filtering**: Include/exclude specific order statuses
- **Sortable Columns**: Sort by category, orders count, or total price
- **Pagination**: Handle large datasets efficiently
- **CSV Export**: Export filtered data to CSV files
- **Settings Management**: Configure default values and preferences

## Installation

1. Upload the plugin files to `/wp-content/plugins/studiou-wc-custom-reports/`
2. Activate the plugin through the 'Plugins' screen in WordPress
3. Navigate to WooCommerce > Custom Reports to start using the plugin

## Requirements

- WordPress 6.8.1 or higher
- PHP 8.2 or higher
- WooCommerce 9.0 or higher

## File Structure

```
studiou-wc-custom-reports/
├── studiou-wc-custom-reports.php     # Main plugin file
├── includes/
│   ├── class-main.php                # Main plugin class
│   ├── class-db-manager.php          # Database operations
│   ├── class-settings-manager.php    # Settings management
│   ├── class-admin-view.php          # Admin interface
│   ├── class-export-handler.php      # CSV export functionality
│   ├── class-report-data.php         # Data model and validation
│   ├── class-report-factory.php      # Report factory pattern
│   ├── class-product-categories-report.php  # Product categories report implementation
│   ├── class-order-customers-report.php     # Order customers report implementation
│   └── class-utils.php               # Utility functions
├── languages/                        # Translation files
└── README.md                         # This file
```

## Class Structure

### Main Classes

- **StudiouWC_Main**: Main plugin orchestrator
- **StudiouWC_DB_Manager**: Handles all database queries and operations
- **StudiouWC_Settings_Manager**: Manages plugin settings and configuration
- **StudiouWC_Admin_View**: Renders admin interface and handles user interactions
- **StudiouWC_Export_Handler**: Manages CSV export functionality

### Supporting Classes

- **StudiouWC_Report_Data**: Data model with validation
- **StudiouWC_Report_Factory**: Factory for creating different report types
- **StudiouWC_Product_Categories_Report**: Product categories report implementation
- **StudiouWC_Order_Customers_Report**: Order customers list report implementation
- **StudiouWC_Utils**: Common utility functions

## Usage

### Accessing Reports

1. Go to **WooCommerce > Custom Reports**
2. Configure your filters:
   - **View**: Select report type
   - **Date Range**: Set from/to dates
   - **Order Statuses**: Choose which statuses to include
   - **Items per page**: Control pagination
3. Click **Filter** to update results
4. Use **Export** to download CSV

### Configuring Settings

1. Go to **WooCommerce > Custom Report Settings**
2. Set your preferences:
   - **Default Interval**: Choose default date range
   - **Default Property**: Select product property for variant analysis
   - **Default Statuses**: Choose default order statuses
3. Click **Save Settings**

## Extending the Plugin

### Adding New Report Types

1. Create a new report class in `includes/`
2. Update `StudiouWC_Report_Factory` to handle the new type
3. Add corresponding database methods in `StudiouWC_DB_Manager`
4. Update the view dropdown in `StudiouWC_Admin_View`

### Adding Custom Properties

The plugin automatically detects product meta fields as properties. To add custom properties:

1. Add meta fields to your products
2. The plugin will automatically include them in the property dropdown
3. Configure the default property in settings

## Hooks and Filters

The plugin is designed to be extensible through WordPress hooks and filters (to be implemented in future versions).

## Support

For support and feature requests, please contact the plugin author or visit the plugin homepage.

## License

This plugin is licensed under GPL v2 or later.

## Changelog

### 1.1.0
- Added "Order Customers List" report view
- Shows distinct customers with name, email, phone, orders count, and total orders price
- CSV export support for customer list report
- HPOS and legacy order storage support for customer queries

### 1.0.0
- Initial release
- Product Categories and Variants Summary report
- CSV export functionality
- Settings management
- Admin interface with filtering and pagination
- Object-oriented architecture with separated concerns
- Full WordPress and WooCommerce integration

## Developer Notes

### Architecture

The plugin follows object-oriented principles with clear separation of concerns:

- **Single Responsibility**: Each class has one primary purpose
- **Dependency Injection**: Classes receive dependencies through constructors
- **Factory Pattern**: Used for creating different report types
- **Data Validation**: Input sanitization and validation throughout
- **Security**: Proper capability checks and nonce verification

### Database Queries

All database operations are handled through the `StudiouWC_DB_Manager` class using WordPress's `$wpdb` with prepared statements for security.

### Coding Standards

- Follows WordPress coding standards
- PSR-4 autoloading compatibility
- Proper sanitization and escaping
- Internationalization ready

### Performance Considerations

- Efficient database queries with proper indexing
- Pagination for large datasets
- Limited property value queries
- Caching opportunities for future enhancement

## Contributing

When contributing to this plugin:

1. Follow WordPress coding standards
2. Add proper docblocks to all methods
3. Include unit tests for new functionality
4. Ensure backward compatibility
5. Test with different WooCommerce versions

## Security

The plugin implements several security measures:

- Capability checks for all admin functions
- Input sanitization and validation
- Prepared SQL statements
- Proper data escaping in output
- CSRF protection through WordPress nonces