Hooks & Events

Minimum Version Requirement

This feature requires WhatsMarkSaaS v2.0.0 or higher. Ensure your installation meets this requirement before proceeding.

Overview

WhatsMarkSaaS implements a WordPress-style hook system that allows modules to integrate with core functionality without modifying core code. This guide covers actions, filters, lifecycle hooks, and custom hook creation.

---

Hook System Architecture

The hook system provides two types of hooks:

Hook Type	Purpose	Return Value
Actions	Execute code at specific points	None (void)
Filters	Modify and return data through pipeline	Modified value

---

Registering Hooks

registerHooks() Method

Hooks must be registered in the main module class registerHooks() method:

<?php

namespace Modules\OrderTracker;

use Corbital\ModuleManager\Support\Module;

class OrderTracker extends Module
{
    /**
     * Register WordPress-style action and filter hooks.
     *
     * @return void
     */
    public function registerHooks(): void
    {
        // Register actions
        add_action('after_activate', [$this, 'onActivate']);
        add_action('order_created', [$this, 'handleOrderCreated']);

        // Register filters
        add_filter('dashboard_widgets', [$this, 'addDashboardWidget']);
        add_filter('order_status_options', [$this, 'addCustomStatus']);
    }

    /**
     * Handle module activation.
     */
    public function onActivate($data): void
    {
        \Log::info('OrderTracker module activated', $data);
    }

    /**
     * Handle order creation event.
     */
    public function handleOrderCreated($orderData): void
    {
        // Send notification, log event, trigger webhook, etc.
    }

    /**
     * Add custom dashboard widget.
     */
    public function addDashboardWidget($widgets): array
    {
        $widgets[] = [
            'name' => 'Order Summary',
            'component' => 'order-tracker::widgets.summary',
        ];

        return $widgets;
    }

    /**
     * Add custom order status.
     */
    public function addCustomStatus($statuses): array
    {
        $statuses['on_hold'] = 'On Hold';
        return $statuses;
    }
}

---

Actions

Actions execute code at specific points without returning a value.

Registering Actions

Signature:

add_action(string $tag, callable $callback, int $priority = 10, int $acceptedArgs = 1): void

Parameters:

Parameter	Type	Description
$tag	string	Hook name
$callback	callable	Function to execute
$priority	int	Execution order (default: 10, lower = earlier)
$acceptedArgs	int	Number of arguments callback accepts

Example:

public function registerHooks(): void
{
    add_action('after_activate', function ($data) {
        \Log::info('Module activated', $data);
    });

    add_action('order_created', function ($order) {
        // Send notification
        $this->sendOrderNotification($order);
    }, 20);
}

Firing Actions

Signature:

do_action(string $tag, mixed ...$args): void

Example:

// In controller
public function store(Request $request)
{
    $order = Order::create($validated);

    // Fire action with order data
    do_action('order_created', $order);

    return redirect()->route('order-tracker.index');
}

Action with Multiple Parameters

// Register action
add_action('order_status_changed', function ($order, $oldStatus, $newStatus) {
    \Log::info("Order {$order->id} status changed from {$oldStatus} to {$newStatus}");
}, 10, 3);

// Fire action
do_action('order_status_changed', $order, $oldStatus, $newStatus);

---

Filters

Filters modify and return data through a pipeline.

Registering Filters

Signature:

add_filter(string $tag, callable $callback, int $priority = 10, int $acceptedArgs = 1): void

Example:

public function registerHooks(): void
{
    add_filter('dashboard_widgets', function ($widgets) {
        $widgets[] = [
            'name' => 'Order Statistics',
            'component' => 'order-tracker::widgets.stats',
        ];
        return $widgets;
    });

    add_filter('order_total', function ($total, $order) {
        // Apply discount
        if ($order->has_discount) {
            $total *= 0.9; // 10% discount
        }
        return $total;
    }, 10, 2);
}

Applying Filters

Signature:

apply_filters(string $tag, mixed $value, mixed ...$args): mixed

Example:

// Get widgets with filter applied
$widgets = apply_filters('dashboard_widgets', []);

// Calculate total with filters
$total = apply_filters('order_total', $order->total, $order);

Filter Pipeline

Multiple filters on the same hook execute in priority order:

// Priority 10 (executes first)
add_filter('order_total', function ($total) {
    return $total * 1.1; // Add 10% tax
}, 10);

// Priority 20 (executes second)
add_filter('order_total', function ($total) {
    return round($total, 2); // Round to 2 decimals
}, 20);

// Result: (100 * 1.1) rounded = 110.00
$total = apply_filters('order_total', 100);

---

Lifecycle Hooks

WhatsMarkSaaS provides built-in lifecycle hooks for module events:

Available Lifecycle Hooks

Hook	Trigger Point	Arguments
before_activate	Before module activation	$moduleName
after_activate	After module activation	$moduleName
before_deactivate	Before module deactivation	$moduleName
after_deactivate	After module deactivation	$moduleName
before_install	Before module installation	$moduleName
after_install	After module installation	$moduleName
before_uninstall	Before module uninstallation	$moduleName
after_uninstall	After module uninstallation	$moduleName

Using Lifecycle Hooks

public function registerHooks(): void
{
    // Log activation
    add_action('after_activate', function ($moduleName) {
        \Log::info("Module {$moduleName} activated");
    });

    // Cleanup on deactivation
    add_action('before_deactivate', function ($moduleName) {
        \Cache::forget("module:{$moduleName}:cache");
    });

    // Setup on installation
    add_action('after_install', function ($moduleName) {
        // Create default settings
        $this->createDefaultSettings();
    });

    // Cleanup on uninstallation
    add_action('before_uninstall', function ($moduleName) {
        // Remove module data
        $this->cleanupModuleData();
    });
}

---

Creating Custom Hooks

Define Custom Actions

In your module controller:

public function processOrder($orderId)
{
    $order = Order::findOrFail($orderId);

    // Allow modules to modify before processing
    do_action('before_order_process', $order);

    // Process order
    $this->process($order);

    // Allow modules to execute after processing
    do_action('after_order_process', $order);
}

Other modules can hook into these actions:

// In another module
add_action('before_order_process', function ($order) {
    // Validate inventory
    $this->checkInventory($order);
});

add_action('after_order_process', function ($order) {
    // Send confirmation email
    $this->sendConfirmation($order);
});

Define Custom Filters

In your module:

public function calculateShipping($order)
{
    $baseShipping = 10.00;

    // Allow modules to modify shipping cost
    $shipping = apply_filters('order_shipping_cost', $baseShipping, $order);

    return $shipping;
}

Other modules can modify shipping:

// In shipping module
add_filter('order_shipping_cost', function ($cost, $order) {
    if ($order->total > 100) {
        return 0; // Free shipping over $100
    }
    return $cost;
}, 10, 2);

---

Hook Priority System

Priority Levels

Priority determines hook execution order:

Priority	When to Use
1-9	Critical, must execute first
10	Default priority (standard hooks)
11-19	After default hooks
20+	Low priority, cleanup tasks

Priority Example

// Execute first (priority 5)
add_filter('order_total', function ($total) {
    return $total + 5; // Add shipping
}, 5);

// Execute second (priority 10, default)
add_filter('order_total', function ($total) {
    return $total * 1.1; // Add tax
});

// Execute third (priority 15)
add_filter('order_total', function ($total) {
    return round($total, 2); // Round result
}, 15);

// Result: ((100 + 5) * 1.1) rounded = 115.50
$total = apply_filters('order_total', 100);

---

Conditional Hook Registration

Register Hooks Based on Conditions

public function registerHooks(): void
{
    // Only register if another module is active
    if (module_enabled('Notifications')) {
        add_action('order_created', [$this, 'sendNotification']);
    }

    // Only register for specific tenants
    if (tenant_setting('enable_custom_status')) {
        add_filter('order_status_options', [$this, 'addCustomStatus']);
    }

    // Only register in production
    if (app()->environment('production')) {
        add_action('order_created', [$this, 'sendToAnalytics']);
    }
}

---

Hook Documentation

Documenting Custom Hooks

Document all custom hooks your module provides:

/**
 * Fires after an order is successfully created.
 *
 * @since 1.0.0
 *
 * @param \Modules\OrderTracker\Models\Order $order The created order object.
 */
do_action('order_created', $order);

/**
 * Filters the order status options.
 *
 * @since 1.0.0
 *
 * @param array $statuses Array of status options (key => label).
 * @return array Modified status options.
 */
$statuses = apply_filters('order_status_options', $statuses);

---

Hook Reference

Common WhatsMarkSaaS Hooks

Module Lifecycle:

• before_activate
• after_activate
• before_deactivate
• after_deactivate

Application:

• app_module_headers - Add scripts/styles to header
• app_module_footers - Add scripts to footer
• dashboard_widgets - Filter dashboard widgets

Custom Module Hooks:

Create a HOOKS.md file in your module documenting all hooks:

# OrderTracker Hooks

## Actions {#actions-example}

### order_created
Fires after an order is created.

**Parameters:**
- `$order` (Order) - The created order object

**Example:**
```php
add_action('order_created', function($order) {
    \Log::info("Order {$order->id} created");
});

order_status_changed

Fires when an order status changes.

Parameters:

• $order (Order) - The order object
• $oldStatus (string) - Previous status
• $newStatus (string) - New status

Filters

order_total

Filters the order total amount.

Parameters:

• $total (float) - The order total
• $order (Order) - The order object

Returns: (float) Modified total

---

## Best Practices

### Hook Naming Conventions

1. **Use descriptive names** - `order_created` not `oc`
2. **Use underscores** - `order_status_changed` not `orderStatusChanged`
3. **Prefix module hooks** - `ordertracker_order_created`
4. **Be consistent** - Follow existing naming patterns

### Performance Considerations

1. **Avoid heavy operations** - Keep hook callbacks lightweight
2. **Use priority wisely** - Don't force early execution without reason
3. **Cache results** - Cache expensive filter results
4. **Limit hook count** - Don't create unnecessary hooks

### Error Handling

```php
add_action('order_created', function ($order) {
    try {
        $this->sendNotification($order);
    } catch (\Exception $e) {
        \Log::error('Failed to send order notification', [
            'order_id' => $order->id,
            'error' => $e->getMessage(),
        ]);
    }
});

---

Troubleshooting

Hooks not firing

Solutions:

1. Verify registerHooks() is called
2. Check hook tag spelling matches exactly
3. Verify module is activated
4. Check priority order

Filters not modifying data

Solutions:

1. Ensure filter callback returns modified value
2. Verify filter is registered before being applied
3. Check priority order (lower priority executes first)

---

Next Steps

• Helper Functions - Use module utility functions

---

This guide is for WhatsMarkSaaS v2.0.0+ custom module development.