# Filter Hooks Guide - Events & Templates

## Single Source of Truth: ✅ Verified

**EventRegistry.php** is the single source of truth for all events.
**DefaultTemplates.php** provides templates for all events.

All components use EventRegistry:
- ✅ NotificationsController.php (Events API)
- ✅ TemplateProvider.php (Templates API)
- ✅ No hardcoded event lists anywhere

## Adding Custom Events & Templates

### 1. Add Custom Event

```php
add_filter('woonoow_notification_events_registry', function($events) {
    // Add custom event
    $events['vip_milestone'] = [
        'id' => 'vip_milestone',
        'label' => __('VIP Milestone Reached', 'my-plugin'),
        'description' => __('When customer reaches VIP milestone', 'my-plugin'),
        'category' => 'customers',
        'recipient_type' => 'customer',
        'wc_email' => '',
        'enabled' => true,
    ];
    
    return $events;
});
```

### 2. Add Default Template for Custom Event

```php
add_filter('woonoow_email_default_templates', function($templates) {
    // Add template for custom event
    $templates['customer']['vip_milestone'] = '[card type="success"]

## Congratulations, {customer_name}!

You\'ve reached VIP status! Enjoy exclusive benefits.

[/card]

[card]

**Your VIP Benefits:**

- Free shipping on all orders
- 20% discount on premium items
- Early access to new products
- Priority customer support

[button url="{vip_dashboard_url}"]View VIP Dashboard[/button]

[/card]';
    
    return $templates;
}, 10, 1);
```

### 3. Add Subject for Custom Event

```php
add_filter('woonoow_email_default_subject', function($subject, $recipient, $event) {
    if ($event === 'vip_milestone' && $recipient === 'customer') {
        return '🎉 Welcome to VIP Status, {customer_name}!';
    }
    return $subject;
}, 10, 3);
```

### 4. Replace Existing Template

```php
add_filter('woonoow_email_default_templates', function($templates) {
    // Replace order_placed template for staff
    $templates['staff']['order_placed'] = '[card type="hero"]

# 🎉 New Order Alert!

Order #{order_number} just came in from {customer_name}

[button url="{order_url}"]Process Order Now[/button]

[/card]';
    
    return $templates;
}, 20, 1); // Priority 20 to override default
```

## Complete Example: Subscription Plugin

```php
<?php
/**
 * Plugin Name: WooNooW Subscriptions Addon
 */

// Add subscription events
add_filter('woonoow_notification_events_registry', function($events) {
    $events['subscription_created'] = [
        'id' => 'subscription_created',
        'label' => __('Subscription Created', 'woonoow-subscriptions'),
        'description' => __('When new subscription is created', 'woonoow-subscriptions'),
        'category' => 'subscriptions',
        'recipient_type' => 'customer',
        'wc_email' => 'customer_new_subscription',
        'enabled' => true,
    ];
    
    $events['subscription_renewal'] = [
        'id' => 'subscription_renewal',
        'label' => __('Subscription Renewal', 'woonoow-subscriptions'),
        'description' => __('When subscription renews', 'woonoow-subscriptions'),
        'category' => 'subscriptions',
        'recipient_type' => 'customer',
        'wc_email' => 'customer_renewal_subscription',
        'enabled' => true,
    ];
    
    $events['subscription_cancelled'] = [
        'id' => 'subscription_cancelled',
        'label' => __('Subscription Cancelled', 'woonoow-subscriptions'),
        'description' => __('When subscription is cancelled', 'woonoow-subscriptions'),
        'category' => 'subscriptions',
        'recipient_type' => 'customer',
        'wc_email' => 'customer_cancelled_subscription',
        'enabled' => true,
    ];
    
    return $events;
});

// Add templates
add_filter('woonoow_email_default_templates', function($templates) {
    $templates['customer']['subscription_created'] = '[card type="success"]

## Welcome to Your Subscription!

Your subscription is now active. We\'ll charge you {subscription_amount} every {billing_period}.

[/card]

[card]

**Subscription Details:**

**Product:** {subscription_product}
**Amount:** {subscription_amount}
**Billing Period:** {billing_period}
**Next Payment:** {next_payment_date}

[button url="{subscription_url}"]Manage Subscription[/button]

[/card]';

    $templates['customer']['subscription_renewal'] = '[card]

## Subscription Renewed

Your subscription for {subscription_product} has been renewed.

**Amount Charged:** {subscription_amount}
**Next Renewal:** {next_payment_date}

[button url="{subscription_url}"]View Subscription[/button]

[/card]';

    $templates['customer']['subscription_cancelled'] = '[card type="warning"]

## Subscription Cancelled

Your subscription for {subscription_product} has been cancelled.

You\'ll continue to have access until {expiry_date}.

[/card]

[card]

Changed your mind? You can reactivate anytime.

[button url="{subscription_url}"]Reactivate Subscription[/button]

[/card]';
    
    return $templates;
});

// Add subjects
add_filter('woonoow_email_default_subject', function($subject, $recipient, $event) {
    $subjects = [
        'subscription_created' => 'Your subscription is active!',
        'subscription_renewal' => 'Subscription renewed - {subscription_product}',
        'subscription_cancelled' => 'Subscription cancelled - {subscription_product}',
    ];
    
    if (isset($subjects[$event]) && $recipient === 'customer') {
        return $subjects[$event];
    }
    
    return $subject;
}, 10, 3);
```

## Available Filter Hooks

### 1. `woonoow_notification_events_registry`
**Location:** `EventRegistry::get_all_events()`
**Purpose:** Add/modify notification events
**Parameters:** `$events` (array)
**Return:** Modified events array

### 2. `woonoow_email_default_templates`
**Location:** `DefaultTemplates::get_all_templates()`
**Purpose:** Add/modify email templates
**Parameters:** `$templates` (array)
**Return:** Modified templates array

### 3. `woonoow_email_default_subject`
**Location:** `DefaultTemplates::get_default_subject()`
**Purpose:** Add/modify email subjects
**Parameters:** `$subject` (string), `$recipient` (string), `$event` (string)
**Return:** Modified subject string

## Testing Your Custom Event

After adding filters:

1. **Refresh WordPress** - Clear any caches
2. **Check Events API:** `/wp-json/woonoow/v1/notifications/events`
3. **Check Templates API:** `/wp-json/woonoow/v1/notifications/templates`
4. **UI:** Your event should appear in Staff/Customer Notifications
5. **Template:** Should be editable in the template editor

## Best Practices

✅ **DO:**
- Use unique event IDs
- Provide clear labels and descriptions
- Include all required fields
- Test thoroughly
- Use appropriate priority for filters

❌ **DON'T:**
- Hardcode events anywhere
- Skip required fields
- Use conflicting event IDs
- Forget to add templates for events