Skip to main content

Getting Started with Hooks

Hooks are a powerful extensibility mechanism in Mumara Campaigns that allow you to execute custom code when specific events occur within the application. They provide a way to extend and customize the platform's behavior without modifying core files.

What are Hooks?​

Hooks are callback functions that get executed when associated events occur in Mumara Campaigns. They enable you to:

  • Extend functionality - Add custom logic to existing features
  • Integrate with external systems - Send data to third-party services when events occur
  • Customize the interface - Inject custom HTML, CSS, or JavaScript into pages
  • Automate workflows - Trigger actions based on system events
  • Build add-ons - Create modular extensions that plug into the core application

How Hooks Work​

The hooks system follows a simple publish-subscribe pattern:

  1. Registration - You register a callback function to a specific hook name
  2. Execution - When the corresponding event occurs, all registered callbacks are executed
  3. Priority - Multiple callbacks on the same hook execute in priority order (lower numbers first)
// Register a hook
add_hook('AddContact', 1, function($vars) {
    // Your custom code here
    // $vars contains data about the event
});

Hook Types​

Mumara Campaigns provides two main categories of hooks:

Module Hooks​

Module hooks fire when specific actions occur within the application, such as:

  • Contact operations (add, edit, delete)
  • List management
  • Campaign events (start, pause, complete)
  • Domain and SMTP configuration changes
  • User management actions

These hooks are ideal for:

  • Syncing data with external CRMs
  • Triggering notifications
  • Logging custom audit trails
  • Implementing business logic

Output Hooks​

Output hooks allow you to inject content into specific locations on pages:

  • HeadTop / HeadEnd - Add stylesheets or meta tags
  • BodyTop / BodyEnd - Inject scripts or HTML
  • Footer - Add footer content
  • PrimaryMenu - Extend navigation
  • AlertBar - Display custom alerts

These hooks are perfect for:

  • Adding custom stylesheets or scripts
  • Displaying notifications or banners
  • Extending the user interface
  • Injecting analytics or tracking code

File Location​

Hook files are stored in the /includes/hooks/ directory. You can create new PHP files in this directory to register your custom hooks.

# Create a new hook file
touch /path/to/mumara/includes/hooks/myhooks.php

An example.php file is provided in the hooks directory as a reference template.

Quick Example​

Here's a simple example that logs contact additions to a file:

<?php
// File: includes/hooks/contact-logger.php

add_hook('AddContact', 1, function($vars) {
    $logData = [
        'timestamp' => date('Y-m-d H:i:s'),
        'contact_id' => $vars['subscriber_id'] ?? 'unknown',
        'list_id' => $vars['list_id'] ?? 'unknown',
        'action' => 'contact_added'
    ];

    $logLine = json_encode($logData) . PHP_EOL;
    file_put_contents(storage_path('logs/contacts.log'), $logLine, FILE_APPEND | LOCK_EX);
});

Execution Modes​

Hooks can be executed in two modes:

Synchronous Execution​

The hook executes immediately and blocks until completion:

listen_hook('AddContact', $data);

Asynchronous Execution​

The hook is queued and executes in the background:

run_hook_in_background('AddContact', $data);

Background execution is useful for time-consuming operations that shouldn't delay the user's request.

Best Practices​

  1. Use unique function names - Prefix your functions to avoid naming conflicts
  2. Handle errors gracefully - Wrap your code in try-catch blocks
  3. Keep hooks lightweight - Offload heavy processing to background jobs
  4. Test thoroughly - Hooks can affect core functionality
  5. Document your hooks - Comment your code for future maintenance

Next Steps​

Last updated on