Available APIs

Import API

As mentioned earlier, External Import can be used from within another piece of code, just passing it data and benefiting from its mapping, transformation and storing features.

It is very simple to use this feature. You just need to assemble data in a format that External Import can understand (XML structure or PHP array) and call the appropriate method. All you need is an instance of class \Cobweb\ExternalImport\Importer and a single call.

$importer = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Cobweb\ExternalImport\Importer::class);
$messages = $importer->import($table, $index, $rawData);

The call parameters are as follows:

The result is a multidimensional array of messages. The first dimension is a status and corresponds to the \TYPO3\CMS\Core\Messaging\AbstractMessage::ERROR, \TYPO3\CMS\Core\Messaging\AbstractMessage::WARNING and \TYPO3\CMS\Core\Messaging\AbstractMessage::OK constants. The second dimension is a list of messages. Your code should handle these messages as needed.

Data Model

The data that goes through the import process is encapsulated in the \Cobweb\ExternalImport\Domain\Model\Data class. This class contains two member variables:

rawData

The data as it is read from the external source or as it is passed to the import API. Given the current capacities of External Import, this may be either a string representing a XML structure or a PHP array.

extraData

An array available for anyone to write into and read from. This is some kind of storage space where any type of data can be stored and passed from step to step.

On top of the usual getter and setter, use addExtraData($key, $data) to add some data to this array using the defined array key.

records

The data as structured by External Import, step after step.

downloadable

Indicates whether the records variable contains data that is appropriate for downloading as CSV. The download feature is available in the preview mode of the backend module.

There are getters and setters for each of these.

Configuration Model

Whenever an import is run, the corresponding TCA configuration is loaded into an instance of the \Cobweb\ExternalImport\Domain\Model\Configuration class. The main member variables are:

table

The name of the table for which data is being imported.

index

The index of the configuration being used.

generalConfiguration

The general part of the External Import TCA configuration.

columnConfiguration

The columns configuration part of the External Import TCA configuration.

additionalFields

Array containing the list of additional fields. This should be considered a runtime cache for an often requested property.

countAdditionalFields

Number of additional fields. This is also a runtime cache.

steps

List of steps the process will go through. When the External Import configuration is loaded, the list of steps is established, based on the type of import (synchronized or via the API) and any custom steps. This ensures that custom steps are handled in a single place.

connector

The Configuration object also contains a reference to the Connector service used to read the external data, if any.

There are getters and setters for each of these.

Furthermore the setExcludedFromSavingFlagForColumn() method makes it possible to programmatically exclude (or re-include) a field from being saved to the database. By default, all additional fields are excluded. Using this method should not be necessary is most normal usage scenarios.

The Importer class

Beyond the import() method mentioned above the \Cobweb\ExternalImport\Importer class also makes a number of internal elements available via getters:

getExtensionConfiguration

Get an array with the unserialized extension configuration.

getExternalConfiguration

Get the current instance of the Configuration model.

setContext/getContext

Define or retrieve the execution context. This is mostly informative and is used to set a context for the log entries. Expected values are "manual", "cli", "scheduler" and "api". Any other value can be set, but will not be interpreted by the External Import extension. In the Log module, such values will be displayed as "Other".

Warning

setContext/getContext is deprecated. Use setCallType/getCallType instead.

setCallType/getCallType

Define or retrieve the execution context. This is based on the \Cobweb\ExternalImport\Enum\CallType enumeration. It is normally set by External Import itself, but can be set from the outside, especially when using External Import as an API (in which case, the call type should set to \Cobweb\ExternalImport\Enum\CallType::Api).

setDebug/getDebug

Define or retrieve the debug flag. This makes it possible to programatically turn debugging on or off.

setVerbose/getVerbose

Define or retrieve the verbosity flag. This is currently used only by the command-line utility for debugging output.

and a few more which are not as significant and can be explored by anyone interested straight in the source code.

For reporting, the \Cobweb\ExternalImport\Importer class also provides the addMessage() method which takes as arguments a message and a severity (using the constants of the \TYPO3\CMS\Core\Messaging\AbstractMessage class).

The call context

External Import may be called in various contexts (command line, Scheduler task, manual call in the backend or API call). While the code tries to be as generic as possible, it is possible to hit some limits in some circumstances. The "call context" classes have been designed for such situations.

A call context class must inherit from \Cobweb\ExternalImport\Context\AbstractCallContext and implement the necessary methods. There is currently a single method called outputDebug() which is supposed to display some debug output. Currently a specific call context exists only for the command line and makes it possible to display debugging information in the Symfony console.

The reporting utility

The \Cobweb\ExternalImport\Utility\ReportingUtility class is in charge of giving feedback in various contexts, lik sending an email once a synchronization is finished.

It provides a generic API for storing values from Step classes that could make sense in terms of reporting. Currently this is used only by the \Cobweb\ExternalImport\Step\StoreDataStep class which reports on the number of operations performed (inserts, updates, deletes and moves).