Plugins

Depending on the required functionality, it will be necessary to implement a plugin.
A plugin is the highest level when starting a component.
It will not be required to implement a plugin, as the subject or observer level can cover the necessary needs in many cases.

When do I need a plugin?

It would help if consider implementing a plugin in either one of these cases.

You want to deal with all artifacts of an import, and you want to do something with the files before they are processed or after they have been processed, e.g. like the artifact plugin that compresses all the import artifacts into a ZIP and moves it to a configurable folder
You want to load some data from the database or the filesystem that will be needed later on in your subjects or observers, during the files will be processed, e.g. like the global data plugin that loads the available attributes and adds them to the registry
You need to pre-initialize something before the primary import process starts, e.g. like the cache warmer plugin that warms the registered repository
You need to do something after the import has been finished, e.g. like the missing options plugin that sends a list with missing option values, a configurable receiver

In general, you need a plugin if you want to interact before or after the primary import step, or you have to implement some business logic that needs access to all important artifacts at the same time.

How to implement a plugin?

A good example is the TechDivision\Import\Plugins\GlobalDataPlugin that is part of the Pacemaker Community Edition (CE) core.

In general, you do not have to write the plugin from scratch; instead, extend the TechDivision\Import\Plugins\AbstractPlugin class that implements the TechDivision\Import\Plugins\PluginInterface which must be implemented by every plugin.

The interface defines the setPluginConfiguration() method, which expects the plugin configuration with the optional parameters.

{
  "id": "import.plugin.global.data"
}

And the process() method that will have to implement the main plugin’s functionality.

The TechDivision\Import\Plugins\GlobalDataPlugin loads the global data, e.g. entity types from the import processor and injects it into the registry.

It makes it available by all following plugins, subjects, and observers and helps to avoid unnecessary database access.

namespace TechDivision\Import\Plugins;

use TechDivision\Import\Utils\RegistryKeys;

class GlobalDataPlugin extends AbstractPlugin
{
    /**
     * Process the plugin functionality.
     *
     * @return void
     * @throws \Exception Is thrown, if the plugin can not be processed
     */
    public function process()
    {

        // load the global data from the import processor
        $globalData = $this->getImportProcessor()->getGlobalData();

        // add the status with the global data
        $this->getRegistryProcessor()->mergeAttributesRecursive(
            RegistryKeys::STATUS,
            array(RegistryKeys::GLOBAL_DATA => $globalData)
        );
    }
}

OOTB Plug-Ins

The standard plugins are part of the Pacemaker Community Edition (CE) core and can be used OOTB.

When it is necessary to implement your components, you will go fine in most cases, if you do not implement your plugin, but instead use the SubjectPlugin and provide your functionality in the form of subjects, observers, and services.

Cache Warmer

Has been removed up with version 3.8.0

Global Data

Load’s the global data necessary for the import process from the database and adds it to the registry so that every plugin can access it. You can find a more detailed explanation of the plugin in the section above.

The configuration has to look like the following:

{
  "id": "import.plugin.global.data"
}

Subject

It is the plugin that does the main work by invoking the registered subjects and their registered observers and callbacks.

Using Pacemaker Community Edition (CE) as a framework, this plugin will be a good entry point to add your custom functionality.

In most cases, it will be enough to write a subject and observers that provides the necessary functionality and will be invoked by this plugin.

The plugin configuration is

{
  "id": "import.plugin.subject",
  "subjects": [ ... ]
}

You can always register as many subjects and observers as necessary.

Missing Option Values

This plugin provides the extended functionality to track whether an attribute option value, referenced in a CSV import file, is available or not, depending on debug mode enabled or not.

If the debug mode is not enabled, an exception will be thrown immediately. Otherwise, each missing attribute option value will be written to the CSV file missing-option-values.csv will be stored in the temporary import directory and optionally sent to the specified mail recipients.

The configuration of the plugin can look like

{
  "id": "import.plugin.missing.option.values",
  "swift-mailer" : {
    "id" : "import.logger.factory.transport.swift.smtp",
    "params" : {
      "to" : "tw@techdivision.com",
      "from" : "pacemaker@techdivision.com",
      "subject": "Something Went Wrong",
      "content-type" : "text/plain"
    },
    "transport" : {
      "params" : {
        "smtp-host" : "mail.techdivision.com",
        "smtp-port" : 25
      }
    }
  }
}

The swift-mailer configuration node is optional.

Only if the Swift Mailer configuration is available, the CSV file will be sent to the specified recipients.

Plugins

When do I need a plugin?

How to implement a plugin?

OOTB Plug-Ins

Cache Warmer

Global Data

Subject

Missing Option Values

WIR HÄTTEN IHNEN DIESE MELDUNG AUCH GERNE ERSPART ...