Integrating external SDKs

In this tutorial, you will learn how to integrate an external SDK into your plugin. By integrating an external SDK and adding a dependency between your plugin and a repository on Packagist, you can access the functionality of the external SDK.

Step 1: Cloning the HelloWorld plugin

In this tutorial, we will extend the functionality of the HelloWorld plugin by integrating Guzzle, a PHP HTTP client. We then use the external SDK to send an HTTP request to an API, e.g. the Packagist API, to retrieve certain information.

The HelloWorld plugin structure

Below, you find an overview of the existing structure of our HelloWorld plugin.

HelloWorld/
    ├── resources/
    │   └── views/
    │       └── content/
    │           └── hello.twig
    │
    ├── src/
    │   ├── Providers/
    │   │   ├── HelloWorldServiceProvider.php
    │   │   └── HelloWorldRouteServiceProvider.php
    │   │
    │   └── Controllers/
    │       └── ContentController.php
    │
    ├── plugin.json // plugin information
    └── // additional files (Readme, license etc.)

Step 2: Extending the plugin structure

In order to integrate the external SDK, we have to make changes to the following existing files. We also have to add a new folder with a new file:

  1. Update the plugin.json
  2. Create the resources/lib folder and add the guzzle_connector.php file
  3. Extend the ContentController.php
  4. Extend the hello.twig

Updating the plugin.json

First, we have to specify the dependencies of our plugin to the Guzzle SDK by updating the plugin.json file.

HelloWorld/plugin.json
{
    "name":"HelloWorld",
    "description":"My first plugin",
    "namespace":"HelloWorld",
    "author":"Your name",
    "type":"template",
    "serviceProvider":"HelloWorld\\Providers\\HelloWorldServiceProvider",
    "dependencies" : {
        "guzzlehttp/guzzle": "6.2.*"
    }
}

Creating the guzzle_connector.php

External PHP code can only be executed in PHP files that are saved in the lib folder. So, we create a new PHP file that will be the link between the plentymarkets plugin API and an external API.

We take the code example from Guzzle and make some adaptions so that the code fits our needs. Remember that we want to send an HTTP request to the Packagist API. Let's search packages by name.

HelloWorld/resources/lib/guzzle_connector.php
<?php

$client = new \GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://packagist.org/search.json',
    [
        'query' => ['q' => SdkRestApi::getParam('packagist_query')]
    ]
);

/** @return array */
return json_decode($res->getBody(), true);

Extending the ContentController

In order to execute the previously created PHP file, we need to enable HTTP requests in the ContentController, add functionality to address the PHP response and process the returned data.

HelloWorld/src/Controllers/ContentController.php
<?php

namespace HelloWorld\Controllers;

use Plenty\Plugin\Controller;
use Plenty\Plugin\Templates\Twig;
use Plenty\Modules\Plugin\Libs\Contracts\LibraryCallContract;
use Plenty\Plugin\Http\Request;

/**
 * Class ContentController
 * @package HelloWorld\Controllers
 */
class ContentController extends Controller
{
	/**
	 * @param Twig $twig
	 * @param LibraryCallContract $libCall
	 * @param Request $request
	 * @return string
	 */
	public function sayHello(
		Twig $twig,
		LibraryCallContract $libCall,
		Request $request
	)
	{

		$packagistResult =
			$libCall->call(
				'HelloWorld::guzzle_connector',
				['packagist_query' => $request->get('search')]
			);
		return $twig->render('HelloWorld::content.hello', $packagistResult);
	}
}

Making a request

We mentioned above that we want to search Packagist packages by name. So when sending the HTTP request to get all packages with the name plentymarkets, e.g. with Postman, we receive the following response consisting of the results array and the total number of packages:

https://packagist.org/search.json?q=plentymarkets
{
    "results": [
    {
        "name": "plentymarkets/plugin-hack-api",
        "description": "API for plentymarkets plugin development with Hack",
        "url": "https://packagist.org/packages/plentymarkets/plugin-hack-api",
        "repository": "https://github.com/plentymarkets/plugin-hack-api",
        "downloads": 13,
        "favers": 1
    },
    {
        "name": "composer/installers",
        "description": "A multi-framework Composer library installer",
        "url": "https://packagist.org/packages/composer/installers",
        "repository": "https://github.com/composer/installers",
        "downloads": 4931419,
        "favers": 641
    },
    {
        "name": "alexcold/yii2-plentyconnector",
        "description": "PlentyMarkets SOAP API connector",
        "url": "https://packagist.org/packages/alexcold/yii2-plentyconnector",
        "repository": "https://github.com/alexcold/yii2-plentyconnector",
        "downloads": 10,
        "favers": 0
    },
    {
        "name": "plentymarkets/plugin-hello-world",
        "description": "Creates an empty frontend plugin for plentymarkets plugin development",
        "url": "https://packagist.org/packages/plentymarkets/plugin-hello-world",
        "repository": "https://github.com/plentymarkets/plugin-hello-world",
        "downloads": 12,
        "favers": 0
    }
    ],
    "total": 4
}

Extending the twig template

In our TWIG template we don't need all the information of the JSON response. We only want to display the total number of packages, the package name and the package repository. If no packages were found, we want to display the text No entries.

HelloWorld/resources/views/content/hello.twig
<h1>Hello World!</h1>

<p>{{ packagistResult.total }} Results</p>
<ul>
    {% for packagistItem in packagistResult.results %}
        <li>{{ packagistItem.name }} : {{ packagistItem.repository }}</li>
    {% else %}
        <li>No entries</li>
    {% endfor %}
</ul>

Searching for packages

Next, we deploy the plugin in a plugin set. Now, we are able to search for packages via the address bar of the browser. Open your browser and go to www.your-plentystore.com/hello. The template will be rendered and an empty result list will be displayed.

By adding ?search=plentymarkets to the URL, we will send an HTTP request to Packagist that returns all packages with the search word plentymarkets. The items of the result will be rendered in the result list. Requests are limited to prevent an overflow of queries.