Migration Guide

This guide covers changes required when migrating custom ShopMagic extensions from version 2.x to 3.0. Later API changes verified against ShopMagic 4.8.9 are listed under API updates after 3.0.

Housekeeping changes#

Changes to namespaces#

Actions, events, filters, and placeholders use the WPDesk\ShopMagic\Workflow namespace. Update imports in custom extensions.

For example:

- use WPDesk\ShopMagic\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder;
+ use WPDesk\ShopMagic\Workflow\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder;

Abstract classes for core components#

Custom components must extend the corresponding abstract class:

Component	Abstract class
Action	WPDesk\ShopMagic\Workflow\Action\Action
Event	WPDesk\ShopMagic\Workflow\Event\Event
Filter	WPDesk\ShopMagic\Workflow\Filter\Filter
Placeholder	WPDesk\ShopMagic\Workflow\Placeholder\Placeholder

Replace inheritance from the former Basic* classes:

- class MyCustomAction extends BasicAction {
+ class MyCustomAction extends Action {

Update implemented methods to match the contracts of the new base class. Changing the parent class alone does not complete the migration.

Creating extensions#

Extend WPDesk\ShopMagic\Workflow\Extensions\AbstractExtension to register components together.

Override the methods required by the extension:

Method	Components
get_actions()	Actions
get_events()	Events
get_filters()	Filters
get_placeholders()	Placeholders

Each method returns an array of component instances or class names.

For actions, events, and filters, array keys are assigned as component IDs. Keep existing IDs when migrating: saved automations reference these IDs.

Placeholders are registered by the name returned by get_name().

For a built-in implementation, see WPDesk\ShopMagic\Workflow\Extensions\Builtin\CoreExtension.

Register the extension through shopmagic/core/initialized/v2:

use WPDesk\ShopMagic\Integration\ExternalPluginsAccess;

add_action(
    'shopmagic/core/initialized/v2',
    static function ( ExternalPluginsAccess $core ) {
        $core->add_extension( new MyCustomExtension() );
    }
);

MyCustomExtension represents your extension class. Register the callback before the initialization hook runs, and ensure the class is available when the callback executes.

Registration through the following filters remains supported:

• shopmagic/core/actions
• shopmagic/core/events
• shopmagic/core/filters
• shopmagic/core/placeholders

Injecting dependencies in extensions#

Components can be registered as instances or class names:

use WPDesk\ShopMagic\Workflow\Extensions\AbstractExtension;

class CustomExtension extends AbstractExtension {

    public function get_actions(): array {
        return [
            'classic_action' => new ClassicAction( new MyDependency() ),
            'di_enhanced_action' => DiEnhancedAction::class,
        ];
    }
}

The classes in this example represent your custom action and dependency implementations.

Use a class name only if the ShopMagic container can resolve the class and its constructor dependencies. Otherwise, pass an instantiated object.

Adding tabs with settings#

Settings fields are returned through the REST API as a JSON schema. A custom tab does not render its fields through a render() method.

Custom tabs must implement WPDesk\ShopMagic\Admin\Settings\SettingTab.

The WPDesk\ShopMagic\Admin\Settings\FieldSettingsTab base class provides form and data handling. Subclasses must define:

Method	Purpose
get_tab_slug()	Returns the tab identifier.
get_tab_name()	Returns the tab label.
get_fields()	Returns the field objects used to build the settings schema.

get_settings_persistence() supplies the storage used to read and save settings. The default implementation in FieldSettingsTab uses WordPress options with a prefix based on the tab slug.

Register a tab through the initialization hook:

use WPDesk\ShopMagic\Integration\ExternalPluginsAccess;

add_action(
    'shopmagic/core/initialized/v2',
    static function ( ExternalPluginsAccess $core ) {
        $core->append_setting_tab( new MyCustomSettings() );
    }
);

MyCustomSettings represents your settings-tab implementation.

The registered tab appears on the ShopMagic settings page. The shopmagic/core/settings/tabs filter remains available as an alternative registration method.

For the later deprecation affecting settings persistence, see API updates after 3.0.

ShopMagic extensions in a nutshell#

WPDesk\ShopMagic\Integration\ExternalPluginsAccess provides the integration API passed to shopmagic/core/initialized/v2.

Use this API and the available hooks to extend ShopMagic. Internal classes outside the integration API may change without a compatibility guarantee.

The following methods were removed from the integration API in version 3.0:

• get_placeholder_factory()
• get_customer_factory()
• get_customer_provider()
• get_guest_factory()
• get_outcome_information()
• get_outcome_tablet_factory()
• get_outcome_table()

The integration API provides the following methods:

Method	Purpose
add_extension()	Registers actions, events, filters, and placeholders through an extension.
append_setting_tab()	Registers a settings tab.
add_validator()	Registers a workflow validator.
add_test_provider()	Registers a data provider for action tests.
get_logger()	Returns the application logger.
add_execution_creator()	Registers action execution creation logic.
get_version()	Returns the ShopMagic version.
get_container()	Returns a composite container wrapping the ShopMagic dependency container.

Check get_version() when an integration depends on a specific ShopMagic version.

Use get_container() when composing dependency containers for an extension. Access to an internal service through the container does not make that service part of the stable integration API.

Changes to hooks#

Removed hooks#

Removed hook	Replacement or required change
shopmagic/core/initialized	Use shopmagic/core/initialized/v2.
shopmagic/core/action/after_execute	Use shopmagic/core/action/after_execution. See the callback contract below.
shopmagic/core/action/config/before	Metabox configuration was removed. Use an action decorator to add fields.
shopmagic_automation_action_settings	Metabox configuration was removed. Use an action decorator to add fields.
shopmagic/core/automation/event_fired	No direct replacement listed.
shopmagic/core/manual_action/confirm_template/after_action_fields	No direct replacement listed.
shopmagic/core/settings/ready	Update the integration as described under Adding tabs with settings.
shopmagic/core/settings/tabs/saved	Update the integration as described under Adding tabs with settings.
shopmagic/core/settings/template_resolvers	No direct replacement listed.
shopmagic/core/factory/placeholder	No direct replacement listed.
shopmagic/core/factory/event	No direct replacement listed.
shopmagic/core/factory/filter	No direct replacement listed.
shopmagic/core/factory/action	No direct replacement listed.
shopmagic/core/placeholder/template_resolver	No direct replacement listed.
shopmagic/core/placeholders/legacy	Use shopmagic/core/placeholders.
shopmagic/core/guest/timestamp_format	No direct replacement listed.
shopmagic/core/outcomes/timestamp_format	No direct replacement listed.
shopmagic/core/admin/automation_field_resolver	No direct replacement listed.

shopmagic/core/action/after_execution#

The replacement hook receives three arguments, in this order:

1. $action
2. $automation
3. $event

Set the callback’s accepted argument count to 3 when using all three arguments.

The hook runs in a finally block, including after an exception during execution. It does not indicate that the action succeeded.

Deprecated hooks#

Deprecated hook	Replacement
shopmagic_settings_save	shopmagic/core/settings/before_save

shopmagic/core/settings/before_save receives the normalized data array for one automation action. The callback must return the array.

This filter does not handle settings-tab saves.

API updates after 3.0#

The following updates are verified against ShopMagic 4.8.9. Deprecated elements listed below remain present in that version.

Deprecated classes and methods#

Deprecated since	Deprecated API	Replacement
3.0.9	WPDesk\ShopMagic\Extensions\AbstractExtension	WPDesk\ShopMagic\Workflow\Extensions\AbstractExtension
3.0.9	ExternalPluginsAccess::set_validator()	ExternalPluginsAccess::add_validator()
3.0.12	update_fields_data() in actions, events, and filters	set_parameters( FieldValuesBag $parameters )
3.0.12	Action::get_fields_data()	Action::get_parameters()

FieldValuesBag uses the namespace WPDesk\ShopMagic\Workflow.

To convert an existing container:

use WPDesk\ShopMagic\Workflow\FieldValuesBag;

$parameters = FieldValuesBag::from_container( $container );

Action execution#

Custom actions must implement the following method signature:

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

Read execution data from the $resources argument.

Return:

• true when execution succeeds.
• false for an expected unsuccessful result that requires no further explanation.

Action::$resources is deprecated since 3.0.12. Do not use this property as the source of execution data in updated actions.

Settings persistence#

FieldSettingsTab::get_settings_persistence() is marked as deprecated since 4.3.0. Its deprecation notice recommends injecting persistence through the constructor.

The settings controller in ShopMagic 4.8.9 still calls get_settings_persistence() when reading and saving settings. Keep this method available in existing settings-tab implementations.