A small leak can sink a great ship. ~ Benjamin Franklin
We have seen the basic setup and configuration for Mautic plugins that leverage the integrations bundle, in the previous blog post. The key part of any IntegrationBundle is handling the authentication mechanism.
So in this blog post, we will be covering various types of authentication and using one authentication type in the plugin that we built in the last blog post. We will continue developing the same plugin.
IntegrationBundle from Mautic Core supports multiple authentication provider methods- like API-based authentication, Basic Auth, OAuth1a, OAuth2, OAuth2 Two-Legged, OAuth2 Three-Legged, etc. The IntegrationBundle provides all these authentication protocols to be used as Guzzle HTTP Client.
In this blog post, we will implement Basic Auth authentication with a third-party service.
The following steps enable our plugin to have the Basic Auth authentication:
- Have a form with fields for storing the basic auth credentials Form/Type/AuthType.php.
- Prepare a “Credentials” class to be used by the Client class.
- Prepare a “Client” service class to be used by a dedicated APIConsumer class.
- Use Client service and implement API call-related methods in APIConsumer service class.
The plugin depends on third-party APIs to have data to manipulate. And these APIs are gated with the authentication and authorization mechanisms. For the course of this post, we have chosen Basic Auth as the authentication method.
Basic Auth needed a username and password to communicate with the API. So we need a form that accepts the username and password as a key. And this key is required when connecting with API endpoints.
Let's create a form and name it “ConfigAuthType.php” under the “MauticPlugin\HelloWorldBundle\Form\Type” namespace. This class extends the AbstractType class of Symfony. We need to implement the "buildForm()" method to add the required field. Example code should look like this:
You can see the full version here.
It's now time to tell Mautic to pick up this form during configuration. To do so, we have to define an Integration service class implementing ConfigFormInterface, ConfigFormAuthInterface. The ConfigFormAuthInterface is the interface that lets you specify the configuration form using the getAuthConfigFormName method.
So we name this class "ConfigSupport" and place this under the "MauticPlugin\HelloWorldBundle\Integration\Support." Here are the snippets from the class ConfigSupport:
You can find the complete ConfigSupport class here.
Time to let the IntegrationBunddle know about our "ConfigSupport" class. To do so, add a service as integration or create a service listing with the mautic.config_integration tag. The following is the code snippet of the Config.php (the plugin configuration file).
Now, at this point, we have the following things ready:
- A service class to register the configuration support class.
- A class to provide the configuration.
- One can view all the code changes for step 1 here in this commit.
For the Basic Auth, the Integrations bundle uses the “HttpFactory” class to build the http-client. Now, this class needs an object called “Credentials,” consisting of all the required keys for authentication.
If you notice the “getClient()” method of HttpFactory class under the “Mautic\IntegrationsBundle\Auth\Provider\BasicAuth\” namespace, it needs an object of “AuthCredentialsInterface.”
So our next step will be to create a separate class for credentials and create a new custom client to use those credentials.
For that, create a new class called “Credentials” under MauticPlugin\HelloWorldBundle\Connection
The class should be like given below:
This is a trimmed version of the class, and you can find the full version here.
Now that we have completed the Credentials class, we need to create a client who will make HTTP requests. Typically, we don’t need to create a separate client class if we don’t have additional logic to handle. In such cases, we can just call HttpFactory class and get the client like:
In our case, apart from fetching data, we need to cache it and polish it to be easily used for Mautic’s Lead entity.
So we will create a new class called “Client” under the namespace MauticPlugin\HelloWorldBundle\Connection.
The job of the “Client” class is to get the object of ClientInterface (\GuzzleHttp\ClientInterface).
If you need the full class details, you can just follow this link here. Because we are kind and we want to share more, we will quickly review a few methods that interest us and work with the Credentials class we wrote previously.
Here in the “getClient()” method, we are calling the “getCredentials()” method, which is creating a “Credentials” object using API keys.
By using the credentials object, we will get the client via the HttpFactory service call.
So at the end of this phase, we have the following things:
- Credentials object to pass into getClient() method.
- New Client class to manipulate get() method and fetch other configuration.
- New Config.php file inside the “HelloWorldBundle/Integrations” folder to bring configuration and different integration settings.
We are now ready with the entire setup to store credentials and send the request. Now, it is time to use them in any other class or anywhere that we want to use.
In our current plugin, we have created a separate class called “ApiConsumer.” The reason is, we have several other get methods and API calls, so consolidating all the API methods into a single class is easier to manage.
To use our Client service, created via Client.php, we need to create a service that can use this class. That way, we can reuse this class without worrying about anything else.
Create a new service called “helloworld.connection.client” and add it to the Config.php in the other services section.
Similarly, we need to add additional services for the ApiConsumer class to call from other services.
You can refer to the source code to view the entire ApiConsumer class. Here is a snippet of the get() method.
As you can see, we are directly using the Client service’s reference and call the get method from the Client.php.
So at this point, we are done with the third step, where we used our authentication mechanism to fetch the data from the API.
You can refer to the commit to see the code for this step.
Now that we have the plugin ready to communicate with third-party API to churn out more leads, let us thank IntegrationBundle's authentication support.
You can find about different authentication supports here.
Also, we have the third blog post coming up about how to manage and sync data coming from API. So stay tuned!!