Migration Guide

The release of ShopMagic version 3.0 brings a lot of changes to the code base, causing incompatibilities with the previous release. The guide describes all the major changes you need to make to bring your extensions for ShopMagic in line with the latest structure.

Housekeeping changes

The release of ShopMagic 3.0 was an excuse to clean up the structure of the code, and consequently, significant changes to the namespaces and the naming of most classes themselves.

Changes to namespaces

Among the most commonly used components of the plug-in are Action , Event , Placeholder and Filter . From now on, they have all been moved to a common namespace -- Workflow . This means that in order to correctly refer to the extended classes, you need to make a similar change:

1c1
< use WPDesk\ShopMagic\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder;
---
> use WPDesk\ShopMagic\Workflow\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder;

Abstract classes for core components.

Until now, the extension-ready components (Action , Event , Placeholder , Filter ) had an interface implemented by an abstract class with the prefix Basic (e.g. abstract class BasicAction implements Action ). ShopMagic version 3 abandons interfaces, moving common logic and contracts to an abstract class. Leaving aside for now the issue of changes occurring in the contracts themselves, if you extended a class named Basic, you must update your code as follows:

1c1
< class MyCustomAction extends BasicAction {
---
> class MyCustomAction extends Action {

Creating extensions

Originally, in order to add a new placeholder or event to ShopMagic, you had to plug into, for example, a hook named shopmagic/core/events and add the newly created class there. With version 3.0, ShopMagic introduces the concept of extensions, i.e. simple classes, declaring all added components. If you prefer object-oriented programming, this solution may be more convenient for you.

You will create such an extension by extending the WPDesk\ShopMagic\Extensions\AbstractExtension class. There you will find 4 simple methods, returning associative arrays (or a list in case of placeholders):

• get_actions .
• get_events .
• get_filters .
• get_placeholders .

You can find an example extension inWPDesk\ShopMagic\Extensions\Builtin\CoreExtension .

After creating such an extension you will register it inside the hook shopmagic/core/initialized/v2 .

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

However, a new method for adding extensions is not required -- using existing hooks remains supported and is just as effective a method for adding new elements. The classes declaring all extensions are primarily intended to make it easier to manage more components being added; adding a single placeholder via hook may simply be more convenient.

Injecting dependencies in extensions

A new feature is the ability to declare only the name of the class you are adding to the extension, instead of creating it with all the dependencies present in the constructor.

class CustomExtension extends AbstractExtension {
    public function get_actions(): array {
        return [
            'classic_action' => new ClassicAction( new MyDependency() ),
            // Using dependency injection to create a class.
            'di_enhanced_action' => DiEnhancedAction::class,
        ];
    }
}

Using the above method, classes with extensions that use components available in ShopMagic can be created with all the necessary dependencies, which helps simplify the creation of complex classes.

Adding tabs with settings

ShopMagic version 3.0 significantly changes the plugin's architecture approach and supports all elements displayed to the user via the WordPress REST API. One of the elements you may want to add when creating an extension to ShopMagic is the settings tab. Since version 3.0, the way this component is managed and the API that supports it has changed.

Settings no longer have a render method, as all field data is sent as JSON schema. In addition, from now on you can cover the get_settings_persistence method if you want to use a different method of saving data than the default one (saving each item to the wp_options table).

If you want, you can continue to add settings using the hook shopmagic/core/settings/tabs , but now the ShopMagic API also gives you an object-oriented solution.

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

A properly created settings class will from now on be visible as a tab on the Settings page in the ShopMagic admin panel.

ShopMagic extensions in a nutshell.

Version 3.0 brings some changes to the WPDesk\ShopMagic\Integration\ExternalPluginAccess class, which is the main access API used for extending ShopMagic functionality.

Remember, this is the only (except for hooks) official and safe way to introduce custom functionality for ShopMagic. This class API will maintain backward compatibility, and any plans to withdraw functionality will be communicated in advance accordingly. Using other ways for extending ShopMagic is not considered stable and can be changed at will, without prior indication in the plugin, and will not necessarily be considered a key change.

ExternalPluginAccess from version 3.0 loses access to such methods as:

• get_placeholder_factory .
• get_customer_factory .
• get_customer_provider .
• get_guest_factory .
• get_outcome_information
• get_outcome_information
• get_outcome_tablet_factory
• get_outcome_table .

In most cases, these classes no longer exist in the new version of the plugin or are an implementation detail, not suitable for use in extensions.

If you need access to some class defined in ShopMagic, you can still reach for it via ExternalPluginAccess::get_container , which returns a dependency container. Keep in mind, however, that this method is designed to create composite container that will be integrated into your extension, rather than directly pulling dependencies.

The ExternalPluginAccess class is available as an argument in the hook shopmagic/core/initialized/v2 . Using it, you can, among other things:

• Add a new extension with automation elements (actions, placeholders, events, filters).
• Create a new tab in settings.
• Add a validator for automation, which can check the compliance of business logic conditions before running an action (example CustomerLanguageValidator ).
• Add a sample data set, used when testing actions (e.g., testing messages).
• Reach for the application event log class.
• Add action execution logic (e.g., delaying actions based on business goals).

All methods are described in more detail in the comments in the source file.

Changes to hooks

Removed hooks

• shopmagic/core/initialized : alternative shopmagic/core/initialized/v2 .
• shopmagic/core/action/after_execute : alternative shopmagic/core/action/after_execution .
• shopmagic/core/action/config/before , shopmagic_automation_action_settings : version 3.0 is based on REST API queries, and all metaboxes have been removed. If you want to put additional fields in the action, use the decorator pattern.
• shopmagic/core/automation/event_fired .
• shopmagic/core/manual_action/confirm_template/after_action_fields .
• shopmagic/core/settings/ready , shopmagic/core/settings/tabs/saved : review the changes made in adding tabs with settings.
• shopmagic/core/settings/template_resolvers .
• shopmagic/core/factory/placeholder , shopmagic/core/factory/event , shopmagic/core/factory/filter , shopmagic/core/factory/action .
• shopmagic/core/placeholder/template_resolver .
• shopmagic/core/placeholders/legacy : alternative shopmagic/core/placeholders .
• shopmagic/core/guest/timestamp_format , shopmagic/core/outcomes/timestamp_format .
• shopmagic/core/admin/automation_field_resolver .

Deprecated hooks

• shopmagic_settings_save .