Available APIs

This chapter describes the various APIs and data models existing in this extension and which might be of use to developers.

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:

Name Type Description
$table string Name of the table to store the data into.
$index integer Index of the relevant external configuration.
$rawData mixed The data to store, either as XML (string) or PHP array.

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.

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”.
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).

Note

These values are not used for any reporting for now. The number of updates is used in functional tests. Improved reporting could ensue in the future.