Simple integrations

About this module

This module provides a configuration entity, Integration, and a connection service, ConnectionClient, which, when combined, will allow a developer to set up integrations and connect to them with ease.

When used correctly, this module will save you from having to add connection details in your code, and will put control of integrations into site administrators' hands. It reduces the amount of hardcoding required and allows the config integrations to be stored as exportable config.

There is an interface which allows administrators to view and edit the integrations. On its own, this module does nothing except to provide a framework for connecting to other sites.

This module is mostly useful for REST connections. If you need to extend this for use with SOAP connections, the Meng AsyncSoap library works really well: https://packagist.org/packages/meng-tian/async-soap-guzzle

Integration entities

There is no way to add an Integration entity through the user interface.

If you want to create an Integration entity, you must add it in the config/install/ directory of your custom module. These values are editable through the user interface, under the Configuration > Integrations menu link.

An Integration must include an external end point and an authentication type. If no authentication is required, then you can set it to 'none'.

If an Integration is not set to 'Active', no requests should be made. There is some rudimentary prevention in place for this.

If an Integration is in 'debug mode', you can trigger logging. This is useful for recording which requests are made with which parameters etc. It's up to the developer to make sure that debug logging happens - it's just a useful flag.

Connection client

The Connection client extends Drupal's core httpClient service, providing some default functions to configure any requests you may make.

In order to create a Connection, you must provide a valid Integration. The Integration is the source of any configuration for a Connection, so you won't be able to create a Connection unless you've got an Integration to feed it. (If you don't need to provide details from an Integration, just use Drupal's core httpClient service.)

There are two ways to create a Connection. You can create it on a page using a controller, by extending the ConnectionController class. You will have a fully-fledged Connection client that is linked to the Integration you provide.

Alternatively, you can instantiate it directly:

$client = new ConnectionClient();
$client->setIntegration($integration);
$client->configure();

$request = $client->get($client->getRequestEndPoint(), $client->getRequestConfig());