Connector Services 

Language

en

Version

7.0

Description

Base for a family of services used to connect to external data sources and fetch data from them.

Keywords

data import, fetch data, services

Copyright

2007-2026

Author

François Suter (Idéative)

Email

typo3@ideative.ch

License

This document is published under the Creative Commons BY 4.0 license.

Rendered

Wed, 22 Apr 2026 09:47:36 +0000

The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from www.typo3.org.

Introduction 

The main idea of Connector services is to have a basic framework for developing scripts that connect to third-party applications and retrieve data from them. These services are specifically tagged (connector.service) and each service has a type corresponding to a third-party application. Detailed information is provided in the Developer's manual.

This structure makes connection scripts reusable. It also makes them easier to use thanks to a general API. Connector services can be called both from the fronted and the backend. An example of extension using connector services is “external_import”.

Screenshots 

A view of the BE module which makes it possible to test connections and the data they return.

Installation 

This extension does nothing all by itself. Connectors must be developed for specific third-party applications. However this extension must be installed since it provides the base class from which all connector services inherit.

$service = $connectorRegistry->getServiceForType('json', $parameters);

Configuration 

The configuration is up to each specific connector according to its needs.

A BE module is provided to test connections.

The steps to use this tool are simple:

1. Choose a particular service from the drop-down menu. Only available services are in the list. If some services are unavailable, a warning will be displayed at the top of the screen.
2. Enter all the necessary parameters in the text field. For each parameter, enter its name, an equal (=) sign and its value (as in the screenshot above).
3. Choose the output format ("raw" will return the native format for the type of resource being connected to).
4. Click on the "Test!" button. If the connection is successful, the data fetched by the connector service will be displayed below the form. If some error happens, a message will be displayed at the top of the page.

Developer's manual 

The main interest of the connector services is to manage connections to remote systems and provide a common API for extensions needing such connections. This chapter describes said API and gives some indications about how to implement your own connector services.

Connector API 

The Connector Service API is described by interface \Cobweb\Svconnector\Service\ConnectorServiceInterface.

This interface is implented in class \Cobweb\Svconnector\Service\ConnectorBase, which also contains a number of convenience methods. Among the methods described below, some go beyond the public interfance and belong to the connector base. It is recommended that all custom connector services extend the connector base rather than reimplementing boilerplate code.

getType()

This method returns the type of the connector service. The type is representative of the kind of data it can handle, e.g. csv for the "svconnector_csv" service. When using registration via attribute, the type comes from the attribute and will be set by the ConnectorRegistry class.

Input

none

Output

string

getName()

This method returns a human-readable name for the service. Same remark as above.

Input

none

Output

string

initialize()

This method performs any necessary initialization for the connector service. It is called automatically by the registry when instanciating the service. The base class \Cobweb\Svconnector\Service\ConnectorBase contains a default implementation which fires an event allowing custom initialization processes. If you should need to implement your own version of the initialize() method in your connector service, make sure to call the parent method or to dispatch the :phpCobwebSvconnectorEventInitializeConnectorEvent, since users of your service will expect that.

Input

none

Output

void

isAvailable()

This method is called when a connector service is requested via the registry. It is designed to check whether the service is actually available or not. It is expected to return a boolean value accordingly. If the service is not available, the registry will throw a \Cobweb\Svconnector\Exception\UnavailableServiceException.

Input

none

Output

boolean

getSampleConfiguration()

This method returns the sample configuration that gets loaded in the service testing backend module (see Configuration sample.

Input

none

Output

string

checkConfiguration()

This method is called whenever the connector configuration needs to be checked. It is typically called by the query() method, but can also be called by third-party code. It is expected to return a list of errors, warnings and notices (see: \Cobweb\Svconnector\Service\ConnectorBase::checkConfiguration() for the structure of the return array.

Warnings and notices are not considered blocking.

Input

none

Output

array of errors, warnings or notices

getCallContext()

This method returns the current call context object.

Input

none

Output

\Cobweb\Svconnector\Domain\Model\Dto\CallContext

getConnectionInformation()

This method returns any connection information that may have been set by the connector or events called by the connector.

Input

none

Output

php:CobwebSvconnectorDomainModelDtoConnectionInformation

logConfigurationCheck()

This method is used to cleanly report all configuration issues by logging them using the TYPO3 logging API. This is not automatically done by checkConfiguration() because some other form of action might be taken when services are used in third-party code.

When developing your own service, you should call this method right after checkConfiguration() in the query() method.

Input

array of errors, warnings or notices

Output

void

query()

Strictly speaking this method is not part of the API, since it is protected and thus not designed to be called directly. It is designed to encapsulate the distant source querying mechanism, so it is good programming practice to use it.

Input

none

Output

mixed (result from the distant source)

fetchRaw()

This method is expected to return the result of the query to the distant source as is, without transformation.

Input

none

Output

mixed (result from the distant source)

fetchXML()

This method is expected to return the result of the query to the distant source transformed into a XML structure (as a string).

Input

none

Output

string (XML structure)

fetchArray()

This method is expected to return the result of the query to the distant source transformed into a PHP array.

Input

none

Output

array

postProcessOperations()

This method is designed to be called back by whatever process called the connector in the first place when said process is done. It receives as argument some variable indicating the status of the process (typically this could be an indication of success or failure).

It doesn't do anything by itself, but just calls events (or hooks).

Input

A status indication (mixed)

Output

void

// Set some data
$service->getCallContext()->add('external_import', ['foo' => 'bar']);

// Get some data
$context = $service->getCallContext()->get();

// Set some data
$service->getConnectionInformation()->add('token', ['sso' => '$$XyZSecureCode42']);

[
   'headers' => [
      'token' => '{token.sso}'
   ]
]

[
   'headers' => [
      'token' => '$$XyZSecureCode42'
   ]
]

Implementing a connector service 

A custom connector service must implement the interface \Cobweb\Svconnector\Service\ConnectorServiceInterface. However, there is an abstract base class ( \Cobweb\Svconnector\Service\ConnectorBase) which contains some base implementations and some useful helper methods, it is thus recommended to extend that class rather than implementing the interface from scratch.

namespace MyName\MyExt\Service;
class ConnectorSpecialThingy extends \Cobweb\Svconnector\Service\ConnectorBase {
    protected string $extensionKey = 'my_ext';
    ...
}

It is considered a best practice to place your class file in the Classes/Services folder of your extension. It must declare an $extensionKey member variable, as this is used by the API to fetch the sample configuration.

You must then register your service with the connector registry. This is done using the \Cobweb\Svconnector\Attribute\AsConnectorService attribute, with the service's type and name passed as attribute arguments (the type is critical, since this is what identifies a service; the name is a description):

#[AsConnectorService(type: 'json', name: 'JSON connector')]
class ConnectorJson extends ConnectorBase
{
   ...
}

Cobweb\SvconnectorCsv\Service\ConnectorCsv:
  public: true
  arguments:
    - !tagged_iterator connector.service

The base service provides an instance \TYPO3\CMS\Lang\LanguageService independently of context (FE or BE).

If you need to implement the __construct() method, make sure to call parent::__construct() within it.

Throwing exceptions 

A connector may encounter errors while performing its task that could not be detected upstream during the initialization phase. In such a case, it is recommended to interrupt the process and throw an exception with an informative error message.

Applications using connector services should be ready to receive exceptions and should thus encapsulate calls to any of the "fetch" methods in a try/catch block:

try {
	$result = $serviceObject->fetchRaw($parameters);
	// Do something...
}
catch (\Exception $e) {
	// Issue error message or log error, whatever...
}

All connector services should use the base exception class \Cobweb\Svconnector\Exception\ConnectorException or extend it.

Events 

The "svconnector" extension provides a number of events which can be used by the concrete connector implementations. Except is special cases - since all connector services share a common way of working - it should not be necessary to develop custom events.

It is strongly recommended that you trigger these events in your custom connector services, because use case may strongly vary from user to user, and they will welcome the possibility of manipulating the data retrieved by the service in its various forms.

Utilities 

The extension also provides a couple of utility classes. Their features are described here.

$phpArray = \Cobweb\Svconnector\Utility\ConnectorUtility::convertXmlToArray($xml)

$xml = '<?xml version="1.0" encoding="utf-8" standalone="yes" ?>' . "\n" . GeneralUtility::array2xml($result);

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['svconnector']['fileReader']['MYKEY']

$this->fileUtility->setError('Some reason here');

$fileUtility = GeneralUtility::makeInstance(\Cobweb\Svconnector\Utility\FileUtility::class);
$fileContent =  $fileUtility->getFileContent($parameters['filename']);

$error =  $fileUtility->getError();

$fileUtility = GeneralUtility::makeInstance(\Cobweb\Svconnector\Utility\FileUtility::class);
// Get the content stored into a temp file
$filename =  $fileUtility->getFileAsTemporaryFile($parameters['filename']);
// Read from the file
$content = file_get_contents($filename);
// Remove the file
unlink($filename);

Configuration sample 

The testing BE module can read configuration samples from existing connector services. This makes it easier to enter a configuration for testing, in particular to avoid forgetting some important parameter. This sample configuration does not have to be declared in any way, but is expected to be strictly located in Resources/Public/Samples/Configuration.json .

It consists of a simple JSON file. Check the existing connector services (Feed, JSON, SQL, CSV) for examples.

Sitemap