T-Work Spin Wheel System

• Overview
• Features
• Requirements
• Installation
• Quick Start
• REST API Endpoints
• Shortcodes
• Admin Interface
• Security
• Performance
• Development
• Contributing
• License

T-Work Spin Wheel System is a professional WordPress plugin designed for creating engaging spin wheel campaigns with comprehensive management tools. Built with enterprise-grade security, performance optimization, and mobile-first architecture.

• 🎡 Complete Spin Wheel System - Full-featured wheel with customizable prizes and animations
• 🔌 REST API - Production-ready API endpoints for mobile app integration
• 📊 Advanced Analytics - Real-time statistics, charts, and comprehensive reporting
• 🎨 Professional Admin Interface - Intuitive 11-tab management panel
• 🔒 Enterprise Security - Rate limiting, SQL injection protection, XSS prevention
• ⚡ High Performance - Object caching, query optimization, scheduled tasks
• 📱 Mobile Ready - Optimized for mobile apps with JSON responses

• 📤 Export/Import - CSV history export, JSON prizes/settings import/export
• 📧 Email Notifications - Automated emails on spin results with customizable templates
• 🎯 Shortcodes - [spin_wheel], [spin_wheel_stats], [spin_wheel_history]
• ⚡ AJAX Handlers - Real-time updates, bulk actions, dynamic loading
• 📝 Logging System - Comprehensive logging with database storage and retention
• 💾 Cache Management - Object cache integration for optimal performance
• 🧹 Scheduled Tasks - Daily log cleanup, analytics updates, background processing
• 📈 Statistics - Prize distribution, top users, daily/weekly/monthly stats
• 🎨 Frontend Assets - Modern CSS and JavaScript for beautiful frontend display

• 🔗 Webhooks Integration - External service integration with event-based triggers
• 📋 Prize Templates - Pre-configured templates for quick prize creation
• 🔄 Bulk Operations - Bulk delete, activate/deactivate, and update operations
• 🏥 Health Check - System diagnostics, database health, cache status
• 💾 Backup/Restore - Full system backup and restore functionality
• 🏷️ Prize Categories - Organize prizes with categories, colors, and icons
• 📝 Custom Fields - Flexible custom fields per prize for extended data
• 🧪 A/B Testing - Variant assignment and conversion tracking
• 📊 Conversion Tracking - Event logging and conversion rate calculation
• 📚 API Documentation - Auto-generated API documentation endpoint

• WordPress: 5.0 or higher
• PHP: 7.4 or higher (PHP 8.0+ recommended)
• WooCommerce: 5.0+ (required for coupon prizes)
• MySQL: 5.6+ or MariaDB 10.0+

1. Download the plugin ZIP file
2. Navigate to Plugins → Add New in WordPress admin
3. Click Upload Plugin and select the ZIP file
4. Click Install Now and then Activate

1. Upload the twork-spin-wheel folder to /wp-content/plugins/
2. Activate the plugin through the Plugins menu in WordPress
3. Navigate to Spin Wheel in the admin menu to configure

cd wp-content/plugins/
git clone https://github.com/tworksystem/twork-spin-wheel.git

1. Activate the Plugin

   • Go to Plugins → Find T-Work Spin Wheel System → Click Activate

2. Configure Your First Wheel

   • Navigate to Spin Wheel in the admin menu
   • Go to the Settings tab
   • Configure wheel title, description, colors, and limits
   • Set points per spin and daily limits

3. Add Prizes

   • Go to the Prizes tab
   • Click Add New Prize
   • Configure prize type, name, probability weight, and color
   • Save your prize

4. Display on Frontend

   • Use shortcode: [spin_wheel wheel_id="1"]
   • Or integrate via REST API for mobile apps

5. View Analytics

   • Go to the Analytics tab
   • View real-time statistics and charts

/wp-json/twork/v1/spin-wheel

GET /wp-json/twork/v1/spin-wheel/config/{user_id}

Response:

{
  "wheel": {
    "id": 1,
    "title": "Lucky Spin",
    "points_per_spin": 100,
    "daily_limit": 3
  },
  "prizes": [...],
  "user_spins_today": 2
}

POST /wp-json/twork/v1/spin-wheel/spin
Content-Type: application/json

{
  "user_id": 123,
  "wheel_id": 1
}

Response:

{
  "success": true,
  "prize": {
    "id": 5,
    "name": "100 Points",
    "type": "points",
    "value": 100
  },
  "spins_remaining": 1
}

GET /wp-json/twork/v1/spin-wheel/prizes?user_id=123&page=1&per_page=20

GET /wp-json/twork/v1/spin-wheel/banner

GET /wp-json/twork/v1/spin-wheel/docs

For authenticated requests, include WordPress nonce or use application passwords:

X-WP-Nonce: {nonce}

• Default: 10 requests per minute per IP/user
• Configurable in Advanced tab
• Returns 429 Too Many Requests when exceeded

[spin_wheel wheel_id="1" width="320" height="320"]

Attributes:

• wheel_id - Wheel ID to display (required)
• width - Wheel width in pixels (default: 320)
• height - Wheel height in pixels (default: 320)

[spin_wheel_stats user_id="123" show_total_spins="yes" show_points_spent="yes"]

Attributes:

• user_id - User ID (required)
• show_total_spins - Show total spins (yes/no)
• show_points_spent - Show points spent (yes/no)

[spin_wheel_history user_id="123" limit="10"]

Attributes:

• user_id - User ID (required)
• limit - Number of entries to display (default: 10)

The plugin provides a comprehensive admin interface with 11 organized tabs:

Configure wheel appearance, limits, colors, animations, and visual effects.

Manage prizes with probability weights, colors, icons, and bulk operations.

View all spin history with filtering, pagination, and export functionality.

Real-time statistics dashboard with charts, prize distribution, and top users.

Export data to CSV/JSON, import prizes, and manage data migration.

Cache management, logging settings, rate limiting, and email notifications.

Pre-configured prize templates for quick prize creation.

External service integration with event-based triggers and authentication.

System diagnostics, database health, cache status, and API testing.

Full system backup and restore functionality with JSON export/import.

Auto-generated API documentation with endpoint details and examples.

The plugin implements enterprise-grade security measures:

• ✅ Rate Limiting - Prevents API abuse with configurable limits
• ✅ SQL Injection Prevention - All queries use prepared statements
• ✅ XSS Protection - Output escaping and input sanitization
• ✅ Input Validation - Comprehensive validation for all inputs
• ✅ Nonce Verification - CSRF protection on all forms
• ✅ Capability Checks - Permission validation for admin functions
• ✅ IP Address Logging - Security audit trail
• ✅ Security Event Logging - Threat detection and monitoring

• All user inputs are sanitized and validated
• Database queries use $wpdb->prepare()
• Output is escaped using WordPress functions
• Nonces are verified on all form submissions
• User capabilities are checked before admin operations

Optimized for high performance with enterprise-grade features:

• ✅ Object Cache Integration - Reduces database queries
• ✅ Database Query Optimization - Efficient queries with proper indexes
• ✅ Scheduled Background Tasks - Daily cleanup and analytics updates
• ✅ Lazy Loading - Assets loaded only when needed
• ✅ Cache Invalidation - Smart cache updates on data changes
• ✅ Efficient Database Indexes - Optimized table structures

• Wheel configurations cached for 1 hour
• User spin counts cached for 5 minutes
• Analytics data cached for 15 minutes
• Cache automatically invalidated on updates

The plugin creates the following database tables:

All tables include proper indexes for optimal query performance.

twork-spin-wheel/
├── twork-spin-wheel.php    # Main plugin file
├── uninstall.php           # Uninstall script
├── includes/               # Core classes
│   ├── class-database.php
│   ├── class-rest-api.php
│   ├── class-admin.php
│   └── ...
├── assets/                 # Frontend assets
│   ├── css/
│   └── js/
└── languages/              # Translation files

• ✅ WordPress Coding Standards (WPCS) compliant
• ✅ PHPDoc documentation for all functions
• ✅ Proper error handling and exception management
• ✅ Modular architecture with separation of concerns
• ✅ Singleton pattern for main plugin class

The plugin provides various hooks for customization:

// Filter wheel configuration
apply_filters('twork_spin_wheel_config', $config, $wheel_id, $user_id);

// Filter prize result
apply_filters('twork_spin_wheel_prize', $prize, $wheel_id, $user_id);

// Action after spin
do_action('twork_spin_wheel_after_spin', $prize, $wheel_id, $user_id);

See CHANGELOG.md for a detailed list of changes.

• Initial release
• Complete spin wheel system
• REST API endpoints
• Admin interface with 11 tabs
• Analytics dashboard
• Export/Import functionality
• Security features
• Performance optimizations

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

feat: 16012026 - Add new feature description
fix: 16012026 - Fix bug description
docs: 16012026 - Update documentation

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2026 T-WORK SYSTEM Co.,Ltd.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Maw Kunn Myat

• Email: support@tworksystem.com
• GitHub: @mawkunnmyat

For support, feature requests, or bug reports:

• 📧 Email: support@tworksystem.com
• 🐛 Issues: GitHub Issues
• 📚 Documentation: Full Documentation

• Built with WordPress best practices
• Follows WordPress Coding Standards
• Optimized for performance and security
• Designed for enterprise use