This chapter describes the various APIs and data models existing in this extension and which might be of use to developers.
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:
|$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
\TYPO3\CMS\Core\Messaging\AbstractMessage::OK constants. The second dimension is a list
of messages. Your code should handle these messages as needed.
The data that goes through the import process is encapsulated in the
\Cobweb\ExternalImport\Domain\Model\Data class. This class contains
two member variables:
- 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.
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.
- The data as structured by External Import, step after step.
There are getters and setters for each of these.
Whenever an import is run, the corresponding TCA configuration is loaded
into an instance of the
The main member variables are:
- The name of the table for which data is being imported.
- The index of the configuration being used.
- The general part of the External Import TCA configuration.
- The columns configuration part of the External Import TCA configuration.
- Array containing the list of additional fields. This should be considered a runtime cache for an often requested property.
- Number of additional fields. This is also a runtime cache.
- 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.
- 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.
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¶
import() method mentioned above the
also makes a number of internal elements available via getters:
- Get an array with the unserialized extension configuration.
- Get the current instance of the Configuration model.
- 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”.
- Define or retrieve the debug flag. This makes it possible to programatically turn debugging on or off.
- 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
addMessage() method which takes as arguments a message and a severity
(using the constants of the
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
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¶
\Cobweb\ExternalImport\Utility\ReportingUtility class is in charge
of giving feedback in various contexts, lik sending an email once a synchronization
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).
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.