Adding custom events

To create a new event:

1. Create a class that extends \WPDesk\ShopMagic\Workflow\Event\Event or one of its intermediate abstract classes.
2. Register the event using the shopmagic/core/events filter.

Creating a new event class#

ShopMagic provides intermediate abstract classes for common event types:

• \WPDesk\ShopMagic\Workflow\Event\Builtin\OrderCommonEvent — events linked to an order.
• \WPDesk\ShopMagic\Workflow\Event\Builtin\UserCommonEvent — events linked to a customer.

For events linked to a different type of data, extend \WPDesk\ShopMagic\Workflow\Event\Event. Implement get_name(): string, get_group_slug(): string, initialize(): void, jsonSerialize(): array, and set_from_json( array $serialized_json ): void.

Use get_provided_data_domains(): array to declare additional data types available to filters, actions, and placeholders. Add the corresponding objects to $this->resources before triggering the automation.

Creating a new event that is linked to the order#

Extend \WPDesk\ShopMagic\Workflow\Event\Builtin\OrderCommonEvent and implement:

• get_name(): string — the event name displayed in the automation editor.
• initialize(): void — registers the WordPress action callback.

In the callback, add the order and customer to $this->resources, then call $this->trigger_automation(). Assigning the order to $this->order alone does not provide it to the automation.

OrderCommonEvent already declares the order and customer data domains and implements serialization and restoration of order event data.

Example#

The following initialize() method triggers the automation when order items are added through the WooCommerce admin AJAX action:

public function initialize(): void {
    add_action(
        'woocommerce_ajax_order_items_added',
        function ( $items, $order ) {
            if ( ! $order instanceof \WC_Order ) {
                return;
            }

            $this->resources->set( \WC_Order::class, $order );
            $this->resources->set(
                \WPDesk\ShopMagic\Customer\Customer::class,
                $this->get_customer( $order )
            );

            $this->trigger_automation();
        },
        10,
        2
    );
}

Informing the ShopMagic plugin about a new event#

Use the shopmagic/core/events filter to add an event instance to the event map.

The array key is the event identifier. Use a unique key and keep it unchanged after the event has been used in saved automations.

Load the event class through your autoloader or require its file inside the filter callback. Register the filter before ShopMagic builds its event list.

Example#

The following event listens to woocommerce_after_resend_order_email. This is a WooCommerce order email hook; it does not confirm that a separate invoicing plugin has generated or sent an invoice.

Save the event class in class-order-email-resent-event.php:

<?php

namespace YourNamespace;

use WPDesk\ShopMagic\Customer\Customer;
use WPDesk\ShopMagic\Workflow\Event\Builtin\OrderCommonEvent;

class OrderEmailResentEvent extends OrderCommonEvent {

    public function get_name(): string {
        return __( 'Order email resent', 'my-text-domain' );
    }

    public function initialize(): void {
        add_action(
            'woocommerce_after_resend_order_email',
            function ( $order ) {
                if ( ! $order instanceof \WC_Order ) {
                    return;
                }

                $this->resources->set( \WC_Order::class, $order );
                $this->resources->set(
                    Customer::class,
                    $this->get_customer( $order )
                );

                $this->trigger_automation();
            },
            10,
            1
        );
    }
}

Register the event from your custom plugin. In this example, the event class file is in the same directory as the file containing the registration code:

add_filter(
    'shopmagic/core/events',
    function ( array $events ): array {
        require_once __DIR__ . '/class-order-email-resent-event.php';

        $events['yourprefix_order_email_resent'] =
            new \YourNamespace\OrderEmailResentEvent();

        return $events;
    }
);

ShopMagic initializes the event and supplies its execution context. Do not call initialize() or trigger_automation() on the instance created in the registration callback.

After registration, select Order email resent in the automation editor, configure the actions, and activate the automation.

If an existing integration uses the identifier invoice_resend_evest from the previous documentation example, retain that identifier to preserve references in saved automations.