# Shopify Custom Review System

A comprehensive custom review system for Shopify stores that allows customers to submit reviews from the storefront, with admin approval workflow and multi-store support.

## Features

- **Customer Review Submission**: Customers can submit reviews directly from Shopify product pages
- **Admin Approval Workflow**: Reviews require admin approval before being published
- **Multi-Store Support**: Manage reviews for multiple Shopify stores from one admin panel
- **Review Management**: Approve, reject, edit, and moderate reviews
- **Embeddable Widget**: JavaScript widget to display approved reviews on product pages
- **Responsive Design**: Works on desktop and mobile devices
- **Secure API**: Rate limiting, CSRF protection, and input validation
- **Review Statistics**: Average ratings, rating breakdowns, and review counts

## System Requirements

- PHP 7.4 or higher
- MySQL 5.7 or higher
- Web server (Apache/Nginx) with mod_rewrite enabled
- SSL certificate (recommended for production)

## Installation

### 1. Upload Files

Upload all files to your web hosting directory:

```
your-domain.com/
├── api/
├── admin/
├── config/
├── database/
├── includes/
├── widget/
└── README.md
```

### 2. Database Setup

1. Create a new MySQL database
2. Import the database schema:

```sql
-- Run the contents of database/schema.sql
```

3. Update database credentials in `config/config.php`:

```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_username');
define('DB_PASS', 'your_password');
```

### 3. Configuration

Update the configuration in `config/config.php`:

```php
// Update these URLs to match your domain
define('BASE_URL', 'https://your-domain.com');
define('ADMIN_URL', 'https://your-domain.com/admin');
define('API_URL', 'https://your-domain.com/api');

// Generate a secure JWT secret
define('JWT_SECRET', 'your-secure-random-string-here');
```

### 4. Admin Access

The default admin credentials are:
- **Username**: `admin`
- **Password**: `admin123`

**⚠️ Important**: Change the default password immediately after installation!

## Usage

### Admin Panel

Access the admin panel at: `https://your-domain.com/admin/`

#### Adding Stores

1. Log in to the admin panel
2. Go to "Stores" section
3. Click "Add New Store"
4. Fill in:
   - Store Name
   - Shopify Domain (e.g., `mystore.myshopify.com`)
   - Contact Email
5. Save the store and copy the generated API key

#### Managing Reviews

1. Go to "Reviews" section
2. Filter by store and status
3. Use bulk actions to approve/reject multiple reviews
4. Click "Edit" to modify review content
5. View review history and moderation logs

### Shopify Integration

#### 1. Add Review Widget to Product Pages

Add this code to your Shopify product template (usually `product.liquid`):

```html
<!-- Review Widget Container -->
<div id="shopify-reviews" 
     data-api-url="https://your-domain.com/api" 
     data-api-key="YOUR_STORE_API_KEY" 
     data-product-id="{{ product.id }}">
</div>

<!-- Load Widget CSS -->
<link rel="stylesheet" href="https://your-domain.com/widget/review-widget.css">

<!-- Load Widget JavaScript -->
<script src="https://your-domain.com/widget/review-widget.js"></script>
```

#### 2. Manual Widget Initialization

Alternatively, you can initialize the widget manually:

```html
<div id="my-reviews"></div>

<script>
const widget = new ShopifyReviewWidget({
    container: '#my-reviews',
    apiUrl: 'https://your-domain.com/api',
    apiKey: 'YOUR_STORE_API_KEY',
    productId: '{{ product.id }}',
    showForm: true,
    showStats: true,
    reviewsPerPage: 10
});
</script>
```

### API Endpoints

The system provides RESTful API endpoints:

#### Submit Review
```
POST /api/reviews
Content-Type: application/json

{
    "api_key": "your_api_key",
    "product_id": "123456",
    "reviewer_name": "John Doe",
    "reviewer_email": "john@example.com",
    "rating": 5,
    "title": "Great product!",
    "content": "I love this product..."
}
```

#### Get Product Reviews
```
GET /api/reviews?api_key=YOUR_KEY&product_id=123456&page=1&limit=10
```

#### Get Review Statistics
```
GET /api/reviews/stats?api_key=YOUR_KEY&product_id=123456
```

## Customization

### Widget Styling

Customize the widget appearance by modifying `widget/review-widget.css` or adding custom CSS:

```css
/* Custom widget styles */
.shopify-reviews-widget {
    font-family: 'Your Custom Font';
}

.review-item {
    border: 2px solid #your-color;
}
```

### Widget Configuration

The widget accepts various configuration options:

```javascript
const widget = new ShopifyReviewWidget({
    container: '#reviews',
    apiUrl: 'https://your-domain.com/api',
    apiKey: 'your_api_key',
    productId: 'product_id',
    
    // Display options
    showForm: true,           // Show review submission form
    showStats: true,          // Show review statistics
    showPagination: true,     // Show pagination
    
    // Pagination
    reviewsPerPage: 10,       // Reviews per page
    
    // Styling
    theme: 'light',           // 'light' or 'dark'
    
    // Form options
    requireEmail: true,       // Require email for submissions
    allowAnonymous: false,    // Allow anonymous reviews
    
    // Custom labels
    labels: {
        submitButton: 'Submit Review',
        nameLabel: 'Your Name',
        emailLabel: 'Email Address',
        ratingLabel: 'Rating',
        titleLabel: 'Review Title',
        contentLabel: 'Your Review'
    }
});
```

## Security Features

- **CSRF Protection**: All forms include CSRF tokens
- **Rate Limiting**: API endpoints have rate limiting
- **Input Validation**: All inputs are validated and sanitized
- **SQL Injection Prevention**: Uses prepared statements
- **XSS Protection**: All output is properly escaped
- **API Key Authentication**: Secure API access

## File Structure

```
├── api/
│   └── index.php              # Main API endpoint
├── admin/
│   ├── index.php              # Admin dashboard
│   ├── login.php              # Admin login
│   ├── reviews.php            # Review management
│   └── stores.php             # Store management
├── config/
│   └── config.php             # Configuration and database
├── database/
│   └── schema.sql             # Database schema
├── includes/
│   ├── ApiAuth.php            # Authentication class
│   ├── ReviewManager.php      # Review management class
│   └── StoreManager.php       # Store management class
├── widget/
│   ├── review-widget.js       # Widget JavaScript
│   └── review-widget.css      # Widget styles
└── README.md                  # This file
```

## Troubleshooting

### Common Issues

1. **Reviews not appearing**: Check API key and ensure store is active
2. **Database connection errors**: Verify database credentials in config.php
3. **Permission denied**: Ensure proper file permissions (644 for files, 755 for directories)
4. **CORS errors**: Add your Shopify domain to allowed origins in config.php

### Debug Mode

Enable debug mode in `config/config.php`:

```php
define('DEBUG_MODE', true);
define('LOG_ERRORS', true);
```

### Log Files

Check error logs in your hosting control panel or server logs for detailed error information.

## Support

For support and questions:

1. Check the troubleshooting section above
2. Review the configuration settings
3. Check server error logs
4. Ensure all requirements are met

## License

This project is open source and available under the MIT License.

## Changelog

### Version 1.0.0
- Initial release
- Multi-store support
- Admin approval workflow
- Embeddable widget
- Review statistics
- Responsive design

---

**Note**: This system is designed for shared hosting environments with PHP and MySQL support. For high-traffic stores, consider upgrading to VPS or dedicated hosting for better performance.