How to create custom actions in ShopMagic

To create a custom action:

1. Extend WPDesk\ShopMagic\Workflow\Action\Action.
2. Register the action using the shopmagic/core/actions filter.

The examples below apply to ShopMagic 4.8.9. Place custom code in a separate WordPress plugin. Load the action class after the ShopMagic Action class is available and register the filter before ShopMagic initializes its action collection.

Creating a new action class#

WPDesk\ShopMagic\Workflow\Action\Action is an abstract class that provides configuration fields, parameter access, logging, and placeholder processing.

For email actions, you can extend:

WPDesk\ShopMagic\Workflow\Action\Builtin\SendMail\AbstractSendMailAction

Naming your action#

Implement get_name(): string. Its return value is the action name displayed in the automation editor.

public function get_name(): string {
    return 'Change Customer Role';
}

Use a WordPress translation function if the name requires localization.

Creating UI for your action#

Return an array of ShopMagicVendor\WPDesk\Forms\Field objects from get_fields(): array.

Available field classes are located in:

vendor_prefixed/wpdesk/wp-forms/src/Field

ShopMagic converts the fields into a JSON schema and passes it to the automation editor through its REST API.

Adding a text input#

public function get_fields(): array {
    return array_merge(
        parent::get_fields(),
        [
            ( new \ShopMagicVendor\WPDesk\Forms\Field\InputTextField() )
                ->set_label( 'Custom text field' )
                ->set_name( 'text_field' ),
        ]
    );
}

• set_label() sets the visible label.
• set_name() sets the key used to store and retrieve the field value.
• parent::get_fields() preserves the standard Description field.

Field classes also provide configuration methods such as set_required() and set_readonly().

Read saved values during execution using get_parameters():

$parameters = $this->get_parameters();

$text = $parameters->has( 'text_field' )
    ? (string) $parameters->get( 'text_field' )
    : '';

Calling get() for a missing parameter throws WPDesk\ShopMagic\Workflow\ValueNotFound.

If the field accepts placeholders, process its value explicitly:

$text = $this->placeholder_processor->process( $text );

Creating business logic for action#

Implement:

public function execute(
    \WPDesk\ShopMagic\Workflow\Event\DataLayer $resources
): bool;

Execution results:

• Return true when the action succeeds.
• Return false for an expected failure that does not require an additional explanation.
• Throw WPDesk\ShopMagic\Workflow\Action\ActionExecutionFailure when execution fails and requires an error message.

Declare required resources in get_required_data_domains(): array. Read them from the DataLayer argument passed to execute(). Use $resources->has() to check availability; $resources->get() throws ResourceNotFound if a resource is missing.

The following action changes a registered customer's role to premium-customer. The role must already exist in WordPress.

use WPDesk\ShopMagic\Customer\Customer;
use WPDesk\ShopMagic\Workflow\Action\Action;
use WPDesk\ShopMagic\Workflow\Action\ActionExecutionFailure;
use WPDesk\ShopMagic\Workflow\Event\DataLayer;

class ChangeCustomerRole extends Action {

    public function get_name(): string {
        return 'Change Customer Role';
    }

    public function get_required_data_domains(): array {
        return [ Customer::class ];
    }

    public function execute( DataLayer $resources ): bool {
        $customer = $resources->get( Customer::class );

        // Guest customers have no WordPress user role to update.
        if ( $customer->is_guest() ) {
            return false;
        }

        $user = get_user_by( 'id', (int) $customer->get_id() );

        if ( ! $user instanceof \WP_User ) {
            throw new ActionExecutionFailure(
                'The WordPress user could not be found.'
            );
        }

        if ( get_role( 'premium-customer' ) === null ) {
            throw new ActionExecutionFailure(
                'The premium-customer role does not exist.'
            );
        }

        $user->set_role( 'premium-customer' );

        return true;
    }
}

set_role() replaces the user's existing roles.

Select an order event and add a product filter to restrict this action to purchases of the required product. The action itself does not check purchased products.

Hook newly created action into ShopMagic#

Register the action using the shopmagic/core/actions filter:

add_filter(
    'shopmagic/core/actions',
    function ( array $actions ): array {
        $actions['change_customer_role'] = new ChangeCustomerRole();

        return $actions;
    }
);

The registered action is available in the automation editor.

Action identifier#

Use an associative array. ShopMagic uses the array key as the action identifier.

The identifier must:

• Be unique among registered actions.
• Remain unchanged after automations using the action have been saved.

Reusing an existing identifier can replace another action. Changing the identifier can prevent saved automations from resolving the original action.