Developer Hooks and API

This comprehensive reference covers all available hooks, filters, and API endpoints for extending and customizing the Live Carts for WooCommerce plugin.

Table of Contents

• Action Hooks
• Filter Hooks
• REST API Endpoints
• Database Schema

Action Hooks

The plugin provides several action hooks that fire during cart lifecycle events.

Cart Creation and Loading

phplugins_live_carts_cart_created

Fires when a new cart is initially created and saved to the database.

Parameters:

• $cart_id (string): Unique cart identifier
• $user_id (int): WordPress user ID (0 for guests)
• $cart_data (array): Complete cart data array

Example:

add_action('phplugins_live_carts_cart_created', function($cart_id, $user_id, $cart_data) {
    // Log new cart creation
    error_log("New cart created: {$cart_id} for user {$user_id}");
    
    // Send analytics event
    analytics_track('cart_created', [
        'cart_id' => $cart_id,
        'user_id' => $user_id,
        'value' => $cart_data['value']
    ]);
});

phplugins_live_carts_cart_loaded

Triggers when an existing cart is loaded from the session.

Parameters:

• $cart_id (string): Cart identifier
• $cart_data (array): Cart data from database

Example:

add_action('phplugins_live_carts_cart_loaded', function($cart_id, $cart_data) {
    // Track cart resume events
    update_user_meta($cart_data['user_id'], 'last_cart_resume', current_time('mysql'));
});

Cart Activity Tracking

phplugins_live_carts_cart_seen

Fires whenever cart activity is detected (page loads, updates, etc.).

Parameters:

• $cart_id (string): Cart identifier
• $activity_data (array): Activity information including URL, timestamp

Example:

add_action('phplugins_live_carts_cart_seen', function($cart_id, $activity_data) {
    // Track customer behavior patterns
    $patterns = get_option('cart_behavior_patterns', []);
    $patterns[$cart_id][] = [
        'timestamp' => $activity_data['timestamp'],
        'url' => $activity_data['url']
    ];
    update_option('cart_behavior_patterns', $patterns);
});

phplugins_live_carts_cart_contents_updated

Triggers when cart contents are modified (items added, removed, or quantities changed).

Parameters:

• $cart_id (string): Cart identifier
• $old_contents (array): Previous cart contents
• $new_contents (array): Updated cart contents

Example:

add_action('phplugins_live_carts_cart_contents_updated', function($cart_id, $old_contents, $new_contents) {
    // Track product addition/removal patterns
    $old_count = count($old_contents);
    $new_count = count($new_contents);
    
    if ($new_count > $old_count) {
        // Product added
        do_action('custom_product_added_to_cart', $cart_id, $new_contents);
    } elseif ($new_count < $old_count) {
        // Product removed
        do_action('custom_product_removed_from_cart', $cart_id, $old_contents, $new_contents);
    }
});

Cart Status Changes

phplugins_live_carts_cart_abandoned

Fires when a cart is marked as abandoned due to inactivity.

Parameters:

• $cart_id (string): Cart identifier
• $cart_data (array): Complete cart information

Example:

add_action('phplugins_live_carts_cart_abandoned', function($cart_id, $cart_data) {
    // Trigger abandoned cart email campaign
    if ($cart_data['value'] > 50 && $cart_data['user_id'] > 0) {
        wp_schedule_single_event(
            time() + (1 * HOUR_IN_SECONDS),
            'send_abandoned_cart_email',
            [$cart_id, $cart_data['user_id']]
        );
    }
    
    // Log abandonment for analytics
    do_action('ecommerce_event_track', 'cart_abandoned', [
        'cart_value' => $cart_data['value'],
        'items_count' => count($cart_data['contents'] ?? [])
    ]);
});

phplugins_live_carts_cart_converted

Triggers when a cart is successfully converted to an order.

Parameters:

• $cart_id (string): Cart identifier
• $order_id (int): WooCommerce order ID
• $cart_data (array): Cart data at time of conversion

Example:

add_action('phplugins_live_carts_cart_converted', function($cart_id, $order_id, $cart_data) {
    // Calculate cart lifetime
    $created_time = strtotime($cart_data['created']);
    $conversion_time = current_time('timestamp');
    $cart_lifetime = $conversion_time - $created_time;
    
    // Update conversion analytics
    update_post_meta($order_id, '_cart_id', $cart_id);
    update_post_meta($order_id, '_cart_lifetime_seconds', $cart_lifetime);
    
    // Send conversion event to analytics
    analytics_track('cart_converted', [
        'cart_id' => $cart_id,
        'order_id' => $order_id,
        'lifetime_minutes' => round($cart_lifetime / 60, 2),
        'final_value' => $cart_data['value']
    ]);
});

Filter Hooks

Filter hooks allow you to modify plugin behavior and data.

Pro Version Specific Filters

phplugins_live_carts_admin_cart_contents

Modify the cart contents display in admin interface (Pro version extends this for editing).

Parameters:

• $html (string): Generated HTML content
• $cart_data (object): Cart data object
• $contents (array): Cart contents array

Return: Modified HTML string

Example:

add_filter('phplugins_live_carts_admin_cart_contents', function($html, $cart_data, $contents) {
    // Add custom cart analysis before editing interface
    $analysis = '<div class="custom-cart-analysis">';
    $analysis .= '<h4>Cart Analysis</h4>';
    $analysis .= '<p>High-value cart: ' . ($cart_data->value > 100 ? 'Yes' : 'No') . '</p>';
    $analysis .= '</div>';

    return $analysis . $html;
}, 15, 3); // Priority 15 to run before Pro editing (priority 20)

Data Modification Filters

phplugins_live_carts_cart_insert

Modify cart data before insertion into database.

Parameters:

• $cart_data (array): Cart data to be inserted

Return: Modified cart data array

Example:

add_filter('phplugins_live_carts_cart_insert', function($cart_data) {
    // Add custom metadata
    $cart_data['custom_source'] = $_GET['utm_source'] ?? 'direct';
    $cart_data['device_type'] = wp_is_mobile() ? 'mobile' : 'desktop';
    
    return $cart_data;
});

phplugins_live_carts_cart_ip_address

Filter the IP address before storing.

Parameters:

• $ip_address (string): Detected IP address
• $cart_id (string): Cart identifier

Return: Filtered IP address string

Example:

add_filter('phplugins_live_carts_cart_ip_address', function($ip_address, $cart_id) {
    // Anonymize IP for privacy
    if (strpos($ip_address, '.') !== false) {
        // IPv4
        $parts = explode('.', $ip_address);
        $parts[3] = '0';
        return implode('.', $parts);
    }
    return $ip_address;
}, 10, 2);

Display and Frontend Filters

phplugins_live_carts_frontend_cart_id_html

Customize the HTML output of cart ID on frontend.

Parameters:

• $html (string): Default HTML output
• $cart_id (string): Cart identifier

Return: Modified HTML string

Example:

add_filter('phplugins_live_carts_frontend_cart_id_html', function($html, $cart_id) {
    return sprintf(
        '<div class="custom-cart-id">
            <span class="cart-label">Your Cart:</span>
            <strong class="cart-id">%s</strong>
            <button onclick="copyCartId(\'%s\')" class="copy-btn">Copy</button>
        </div>',
        $cart_id,
        $cart_id
    );
}, 10, 2);

Configuration Filters

phplugins_live_carts_track_revisions

Control whether cart content revisions are tracked.

Parameters:

• $track_revisions (bool): Whether to track revisions
• $cart_id (string): Cart identifier

Return: Boolean value

Example:

add_filter('phplugins_live_carts_track_revisions', function($track_revisions, $cart_id) {
    // Only track revisions for carts with high value
    global $woocommerce;
    $cart_total = $woocommerce->cart->get_total('raw');
    
    return $cart_total > 100; // Only track if cart > $100
}, 10, 2);

phplugins_live_carts_abandon_time

Customize the time before carts are considered abandoned.

Parameters:

• $abandon_time (int): Default abandon time in seconds (7200 = 2 hours)

Return: Modified abandon time in seconds

Example:

add_filter('phplugins_live_carts_abandon_time', function($abandon_time) {
    // Different abandon times based on user role
    if (current_user_can('subscriber')) {
        return 3600; // 1 hour for subscribers
    }
    if (current_user_can('customer')) {
        return 4 * 3600; // 4 hours for customers
    }
    return $abandon_time; // Default for others
});

phplugins_live_carts_archive_time

Modify how long before carts are archived.

Parameters:

• $archive_time (int): Default archive time in seconds (30 days)

Return: Modified archive time in seconds

Example:

add_filter('phplugins_live_carts_archive_time', function($archive_time) {
    // Archive faster for development, slower for production
    if (defined('WP_DEBUG') && WP_DEBUG) {
        return 7 * DAY_IN_SECONDS; // 7 days in debug mode
    }
    return 90 * DAY_IN_SECONDS; // 90 days in production
});

REST API Endpoints

The plugin provides REST API endpoints compatible with WooCommerce Analytics.

Stats Endpoint

Endpoint: /wp-json/wc-analytics/reports/phplugins-carts/stats
Method: GET
Authentication: WooCommerce Admin permissions required

Parameters

Parameter	Type	Description	Default
after	string	Start date (ISO 8601 format)	30 days ago
before	string	End date (ISO 8601 format)	Current date
interval	string	Data grouping (day, week, month)	day
status	string	Filter by cart status	all

Response Format

{
  "totals": {
    "carts_created": 150,
    "carts_converted": 45,
    "carts_abandoned": 90,
    "conversion_rate": 30.0,
    "abandonment_rate": 60.0,
    "average_cart_value": 85.50
  },
  "intervals": [
    {
      "interval": "2023-11-01",
      "date_start": "2023-11-01T00:00:00",
      "date_end": "2023-11-01T23:59:59",
      "subtotals": {
        "carts_created": 12,
        "carts_converted": 4,
        "carts_abandoned": 7,
        "conversion_rate": 33.33,
        "abandonment_rate": 58.33,
        "average_cart_value": 92.25
      }
    }
  ]
}

Custom API Usage Example

// Create custom endpoint extending the stats controller
add_action('rest_api_init', function() {
    register_rest_route('custom/v1', '/cart-insights', [
        'methods' => 'GET',
        'callback' => function($request) {
            global $wpdb;
            
            $table = $wpdb->prefix . 'phplugins_carts';
            
            // Get top abandoned products
            $abandoned_products = $wpdb->get_results("
                SELECT 
                    cc.contents,
                    COUNT(*) as abandon_count
                FROM {$table} c 
                JOIN {$wpdb->prefix}phplugins_cart_contents cc ON c.cart_id = cc.cart_id
                WHERE c.status = 'abandoned' 
                AND c.created > DATE_SUB(NOW(), INTERVAL 30 DAY)
                GROUP BY cc.contents
                ORDER BY abandon_count DESC
                LIMIT 10
            ");
            
            return rest_ensure_response([
                'abandoned_products' => $abandoned_products,
                'timestamp' => current_time('c')
            ]);
        },
        'permission_callback' => function() {
            return current_user_can('manage_woocommerce');
        }
    ]);
});

Database Schema

Direct database access for advanced customizations.

Primary Tables

wp_phplugins_carts

CREATE TABLE wp_phplugins_carts (
    cart_id VARCHAR(8) PRIMARY KEY,
    user_id BIGINT(20) DEFAULT 0,
    created DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
    status VARCHAR(20) DEFAULT 'active',
    ip_address VARCHAR(45) NULL,
    last_url TEXT NULL,
    value DOUBLE DEFAULT 0,
    coupon VARCHAR(200) NULL,
    order_id BIGINT(20) DEFAULT 0,
    archived TINYINT(1) DEFAULT 0,
    -- Pro Version Additional Columns
    session_key VARCHAR(191) DEFAULT NULL,
    recovery_key VARCHAR(32) DEFAULT NULL UNIQUE,
    INDEX idx_status (status),
    INDEX idx_created (created),
    INDEX idx_last_seen (last_seen),
    INDEX idx_user_id (user_id)
);

wp_phplugins_cart_contents

CREATE TABLE wp_phplugins_cart_contents (
    id BIGINT(20) AUTO_INCREMENT PRIMARY KEY,
    cart_id VARCHAR(8) NOT NULL,
    ts DATETIME DEFAULT CURRENT_TIMESTAMP,
    contents TEXT NOT NULL,
    FOREIGN KEY (cart_id) REFERENCES wp_phplugins_carts(cart_id) ON DELETE CASCADE,
    INDEX idx_cart_id (cart_id),
    INDEX idx_timestamp (ts)
);

Custom Query Examples

// Get cart conversion funnel data
function get_conversion_funnel_data($days = 30) {
    global $wpdb;
    
    $table = $wpdb->prefix . 'phplugins_carts';
    
    return $wpdb->get_results($wpdb->prepare("
        SELECT 
            DATE(created) as date,
            COUNT(*) as total_carts,
            SUM(CASE WHEN status = 'converted' THEN 1 ELSE 0 END) as converted,
            SUM(CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END) as abandoned,
            AVG(value) as avg_value
        FROM {$table} 
        WHERE created >= DATE_SUB(NOW(), INTERVAL %d DAY)
        GROUP BY DATE(created)
        ORDER BY date DESC
    ", $days));
}

// Get high-value abandoned carts for recovery
function get_high_value_abandoned_carts($min_value = 100) {
    global $wpdb;
    
    $table = $wpdb->prefix . 'phplugins_carts';
    
    return $wpdb->get_results($wpdb->prepare("
        SELECT 
            c.*,
            u.user_email,
            u.display_name
        FROM {$table} c
        LEFT JOIN {$wpdb->users} u ON c.user_id = u.ID
        WHERE c.status = 'abandoned'
        AND c.value >= %f
        AND c.last_seen >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
        ORDER BY c.value DESC
    ", $min_value));
}

Plugin Class Methods

Direct access to plugin functionality for advanced integrations.

Core Methods

// Get plugin instance
$live_carts = \BerryPress\LiveCarts\LiveCarts::get_instance();

// Force cart status update
$live_carts->update_cart_status($cart_id, 'abandoned');

// Get cart data
$cart_data = $live_carts->get_cart_data($cart_id);

// Create new cart manually
$cart_id = $live_carts->create_cart($user_id, $cart_contents);

// Archive old carts manually
$archived_count = $live_carts->archive_old_carts();

Best Practices for Developers

Performance Considerations

• Use appropriate WordPress caching for custom queries
• Implement pagination for large datasets
• Use transients for expensive calculations
• Consider database indexing for custom queries

Security Guidelines

• Always validate and sanitize inputs
• Use proper capability checks for admin functions
• Implement nonce verification for forms
• Follow WordPress coding standards

Integration Patterns

• Hook into existing actions rather than creating new ones when possible
• Use filters to modify behavior instead of overriding core functions
• Implement proper error handling and logging
• Follow WordPress plugin development best practices

Support and Resources

• Core Plugin Code: Available in /live-carts-for-woocommerce/ directory
• WordPress Hooks Reference: WordPress Plugin API
• WooCommerce Development: WooCommerce Developer Resources