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 :php\Cobweb\Svconnector\Event\InitializeConnectorEvent, 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 receives the list of connector parameters as an input and 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

array of parameters

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:\Cobweb\Svconnector\Domain\Model\Dto\ConnectionInformation

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 the usual list of parameters, plus 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

array of parameters (deprecated, pass an empty array instead) and a status

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'
   ]
]