Spin Wheel

⌘K
  2. Home
  4. Docs
  6. Spin Wheel
  8. Hooks & Filters (Deve...
  10. Developer Hooks Reference

Developer Hooks Reference

Ultimate Spin Wheel provides 8 powerful PHP action hooks that allow developers to extend and customize the plugin’s functionality without modifying core files.

Overview

All hooks are prefixed with uspw_ and follow WordPress naming conventions. They are strategically placed at key points in the spin wheel flow to provide maximum flexibility.

Hook Execution Order

The hooks fire in the following sequence during a spin:

  1. uspw_before_spin_validation – Before any validation
  2. uspw_before_prize_selection – Before random selection algorithm
  3. uspw_after_prize_selected – After prize is selected
  4. uspw_after_coupon_won – After coupon is awarded (legacy flow)
  5. uspw_before_save_entry – Before saving to database
  6. uspw_after_entry_saved – After database insert
  7. uspw_before_send_winner_email – Before email is sent
  8. uspw_email_sent_result – After email send attempt

Available Hooks

1. uspw_before_spin_validation

Type: Filter
Location: class-spin-wheel.php (line ~337)
Purpose: Custom validation before spin processing

$can_spin = apply_filters( 'uspw_before_spin_validation', true, $campaign_id, $user_data );

Parameters:

  • bool $can_spin – Whether the user can spin (default: true)
  • int $campaign_id – Campaign ID
  • array $user_data – User submitted data

Common Use Cases:

  • Block spins from specific email domains
  • Implement custom rate limiting
  • Require user authentication
  • Validate custom fields
  • Time-based restrictions

View Full Documentation →

2. uspw_before_prize_selection

Type: Action
Location: class-spin-wheel.php (line ~409)
Purpose: Analytics and tracking before prize selection

do_action( 'uspw_before_prize_selection', $campaign_id, $weighted_prizes, $user_data );

Parameters:

  • int $campaign_id – Campaign ID
  • array $weighted_prizes – Available prizes with weights
  • array $user_data – User submitted data

Common Use Cases:

  • Track prize pool analytics
  • Implement A/B testing
  • Send real-time notifications
  • Log user behavior patterns
  • Integrate with external CRM

View Full Documentation →

3. uspw_after_prize_selected

Type: Action
Location: class-spin-wheel.php (line ~485)
Purpose: Post-selection actions and notifications

do_action( 'uspw_after_prize_selected', $selected_prize, $campaign_id, $user_data, $won_code );

Parameters:

  • array $selected_prize – The winning prize details
  • int $campaign_id – Campaign ID
  • array $user_data – User submitted data
  • string $won_code – The actual coupon code won

Common Use Cases:

  • Send real-time winner notifications
  • Track prize inventory
  • Trigger marketing automation
  • Create custom post for each winner
  • Sync with analytics platforms

View Full Documentation →

4. uspw_after_coupon_won

Type: Action
Location: class-spin-wheel.php (line ~270)
Purpose: Custom notifications after coupon is won (legacy spin flow)

do_action( 'uspw_after_coupon_won', $campaign_id, $data );

Parameters:

  • int $campaign_id – Campaign ID
  • array $data – Entry data including coupon_code, coupon_title, email, name

Common Use Cases:

  • Send SMS notifications to winners
  • Trigger custom webhook for each win
  • Log wins to external analytics
  • Update inventory systems
  • Sync with loyalty programs

View Full Documentation →

5. uspw_before_save_entry

Type: Filter
Location: class-spin-wheel.php (line ~590)
Purpose: Modify or enrich data before database save

$data = apply_filters( 'uspw_before_save_entry', $data, $campaign_id );

Parameters:

  • array $data – Entry data
  • int $campaign_id – Campaign ID

Common Use Cases:

  • Add UTM parameters for attribution
  • Enrich data with geolocation
  • Normalize phone numbers
  • Calculate lead quality scores
  • Integrate with email verification

View Full Documentation →

6. uspw_after_entry_saved

Type: Action
Location: class-spin-wheel.php (line ~628)
Purpose: External integrations after database save

do_action( 'uspw_after_entry_saved', $entry_id, $data, $campaign_id );

Parameters:

  • int $entry_id – Database entry ID
  • array $data – Complete entry data
  • int $campaign_id – Campaign ID

Common Use Cases:

  • Sync with CRM (Salesforce, HubSpot)
  • Trigger Zapier webhooks
  • Create WooCommerce customers
  • Send to Google Sheets
  • Queue background jobs

View Full Documentation →

7. uspw_before_send_winner_email

Type: Filter
Location: class-spin-wheel.php (line ~665)
Purpose: Customize email before sending

$email_args = apply_filters( 'uspw_before_send_winner_email', $email_args, $data, $campaign_id );

Parameters:

  • array $email_args – Email parameters (to, subject, message, headers)
  • array $data – Entry data
  • int $campaign_id – Campaign ID

Common Use Cases:

  • Translate emails by location
  • Route to transactional email service
  • Add product recommendations
  • Add expiration timers
  • A/B test email templates

View Full Documentation →

8. uspw_email_sent_result

Type: Action
Location: class-spin-wheel.php (line ~681)
Purpose: Handle email delivery results

do_action( 'uspw_email_sent_result', $email_sent, $data, $campaign_id );

Parameters:

  • bool $email_sent – Whether email was sent successfully
  • array $data – Entry data
  • int $campaign_id – Campaign ID

Common Use Cases:

  • Log email delivery status
  • Implement retry logic
  • Send SMS fallback
  • Track email performance
  • Sync status with CRM

View Full Documentation →

Best Practices

1. Use Appropriate Priority

// Default priority (10)
add_action( 'uspw_after_entry_saved', 'my_function', 10, 3 );

// Run early (5)
add_action( 'uspw_before_save_entry', 'my_validation', 5, 2 );

// Run late (20)
add_action( 'uspw_after_entry_saved', 'my_cleanup', 20, 3 );

2. Always Validate Data

add_action( 'uspw_after_prize_selected', 'my_handler', 10, 4 );
function my_handler( $selected_prize, $campaign_id, $user_data, $won_code ) {
    // Validate inputs
    if ( empty( $user_data['email'] ) ) {
        return;
    }
    
    // Sanitize data
    $email = sanitize_email( $user_data['email'] );
    
    // Your logic here
}

3. Use Asynchronous Processing for Heavy Operations

add_action( 'uspw_after_entry_saved', 'queue_heavy_task', 10, 3 );
function queue_heavy_task( $entry_id, $data, $campaign_id ) {
    // Schedule background job instead of running immediately
    wp_schedule_single_event( time() + 60, 'my_heavy_task', [
        'entry_id' => $entry_id,
        'data' => $data
    ] );
}

4. Handle Errors Gracefully

add_action( 'uspw_after_entry_saved', 'sync_to_api', 10, 3 );
function sync_to_api( $entry_id, $data, $campaign_id ) {
    $response = wp_remote_post( 'https://api.example.com/endpoint', [
        'body' => wp_json_encode( $data )
    ] );
    
    if ( is_wp_error( $response ) ) {
        error_log( 'API sync failed: ' . $response->get_error_message() );
        // Don't break the user experience
        return;
    }
}

5. Respect Pro Plugin Compatibility

add_action( 'uspw_before_prize_selection', 'my_custom_logic', 10, 3 );
function my_custom_logic( $campaign_id, $weighted_prizes, $user_data ) {
    // Check if Pro is active
    $is_pro = apply_filters( 'ultimate_spin_wheel_pro_init', false );
    
    if ( $is_pro ) {
        // Pro-specific logic
    } else {
        // Free version logic
    }
}

Code Examples Repository

Each hook has its own documentation page with 5 real-world code examples:

Support

For questions or issues with these hooks:

  1. Check the individual hook documentation pages
  2. Review the code examples for similar use cases
  3. Examine the source code in includes/core/class-spin-wheel.php
  4. Contact support with specific implementation questions

Version History

  • 1.5.0 (Pro) – Initial release with all 8 hooks

Last Updated: February 2026

How can we help?