How to integrate an SDK

Hello World Tutorial With External SDKs

Introduction

This tutorial is aimed at plentymarkets users who completed the first Hello World Tutorial, and want to integrate an external SDK into their 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. Here you can find the github repository for this plugin in the branch h

External SDKs will not be executed in plentymarkets directly. We separated the code of an external SDK from the
plentymarkets plugin code for security reasons. The code of the external SDK is executed on another server that
is not connected to the plentymarkets servers.

Let’s take a look at the result first, to see what we want to implement.

Figure 1. The route without a search

Figure 2. The route with results

First File

The first thing that we are going to do is create a plugin.json, which contains all information about our plugin, that we need. This is the same as in base Hello World tutorial. We extend it with a dependency.

{
      "name":"HelloWorld", (1)
      "description":"My first plugin", (2)
      "namespace":"HelloWorld", (3)
      "author":"plentysystems AG", (4)
      "type":"template", (5)
      "serviceProvider":"HelloWorld\\Providers\\HelloWorldServiceProvider", (6)
      "dependencies" : {
            "guzzlehttp/guzzle": "6.3.*" (7)
      }
}

1	This is the name of our plugin. This is also how it will be displayed in the repository.
2	A description for our plugin
3	We recommend that you use the name of the plugin folder as the namespace root. This service provider is the central location to register services in the plugin.
4	The Author of the plugin, your company name or your personal name.
5	The type of the plugin, for now accept, that this is a template, there are also other type, which we will explain later.
6	The namespace of our ServiceProvider (We haven’t created it yet)
7	We add the new attribute dependencies. The value for this attribute consists of the repository name on Packagist, here guzzlehttp/guzzle and the required version, e.g. version 6.3.*. The asterisk means that any version starting with 6.3, e.g. 6.3.0, 6.3.1 or 6.3.2, is fine.

Folder Structure

Furthermore we will now present you the structure including all the files, that we will need for our Hello World Plugin. 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:

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

HelloWorld/
  resources/
    lib/
      guzzle_connector.php (1)
    views/
      content/
        hello.twig
  src/
    Providers/
      HelloWorldRouteServiceProvider.php
      HelloWorldServiceProvider.php
    Controllers/
      ContentController.php
  plugin.json

1	This is the file that we have added. The guzzle_connector will execute it.

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.

guzzle_connector.php

<?php

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

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

1	In the request function, we state the HTTP method and <2> the URL
2	we use the request option query to add a query string to the request.
3	We return the requested JSON data in decoded form. Note that if a string is returned, it must be UTF-8 encoded.

SdkRestApi is a helper class that enables the communication between plentymarkets plugins and external SDKs. This class provides information about the requests sent by the plugin.

In the getParam function of our query, we use packagist_query. This variable will be described in the code explanation of our ContentController.

Extending the ContentController

As we want to display more data we will have to modify 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.

ContentController.php

<?php

namespace HelloWorld\Controllers;

use Plenty\Plugin\Controller;
use Plenty\Plugin\Templates\Twig;
use Plenty\Modules\Plugin\Libs\Contracts\LibraryCallContract; (1)
use Plenty\Plugin\Http\Request; (2)

/**
 * 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, (1)
		Request $request (2)
	)
	{

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

1	We add the Request dependency. It allows us to obtain an instance of the current HTTP request in `sayHello()`.
2	LibraryCallContract is used for addressing our PHP file and processing the response.
3	This variable stores the result of our Packageist search.
4	The `call()` method requires the `$libCall` parameter and an array of request parameters. In `$libCall`, we state that our connector is located in the HelloWorld plugin: `HelloWorld::guzzle_connector`.
5	In the array of request parameters, we take up `packagist_query` and assign the `$request` parameter to it. This param allows us, to request any search term by adding `search` to our URL.
6	The `$packagistResult` is then passed to the render function and available in our template.

Note that, we cannot directly return classes because the plentymarkets plugin interface is not familiar with these classes. We can only return simple data types or objects with an API that returns the objects as a JSON string.

Making a request

We mentioned above that we want to search Packagist packages by name. So when sending the HTTP request to https://packagist.org/search.json?q=plentymarkets 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:

The Response

{
   "results":[
      {
         "name":"composer\/installers",
         "description":"A multi-framework Composer library installer",
         "url":"https:\/\/packagist.org\/packages\/composer\/installers",
         "repository":"https:\/\/github.com\/composer\/installers",
         "downloads":32907230,
         "favers":1310
      },
      {
         "name":"repat\/plentymarkets-rest-client",
         "description":"REST Client for Plentymarkets",
         "url":"https:\/\/packagist.org\/packages\/repat\/plentymarkets-rest-client",
         "repository":"https:\/\/github.com\/repat\/plentymarkets-rest-client",
         "downloads":1332,
         "favers":13
      },
      ...
   ],
   "total":19,
   "next":"https:\/\/packagist.org\/search.json?q=plentymarkets\u0026page=2"
}

If there’s an error, you will receive the following response instead:

array(6) {
  'error' =>
    bool(true)
  'error_no' =>
    int(404)
  'error_msg' =>
    string(10) "error msg"
  'error_file' =>
    string(10) "/path/to/lib/file"
  'error_line' =>
    int(11)
  'lib_call_response' =>
    NULL
}

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.

hello.twig

<h1>Hello World!</h1>

<p>{{ packagistResult.total }} Results</p> (1)
<ul>
    {% for packagistItem in packagistResult.results %} (2)
        <li>{{ packagistItem.name }} : {{ packagistItem.repository }}</li> (3)
    {% else %} (4)
        <li>No entries</li> (5)
    {% endfor %}
</ul>

1	We defined packagistResult in the ContentController. It contains the information of our HTTP response. We use the variable `{{ packagistResult.total }}` to render the total number of results.
2	In this loop, we loop over each item in the results array.
3	We list each package in the browser with name and repository by using the variables `{{ packagistResult.name }}` and `{{ packagistResult.repository }}`.
4	The `{% else %}` clause will render, if no iteration took place because the sequence was empty.
5	So we display `No entries`.

Searching for packages

Now we deploy the plugin in a PluginSet. 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.

Once you have changed the files in your local HelloWorld folder, the changes must be pushed to GitHub. You also have to update the plugin in your plentymarkets inbox by pulling the changes from GitHub. Finally, you have to deploy the plugin again to display the changes in your browser.

Bonus: Styling the result

With additional styling we can improve the user experience of our plugin. So let’s add a searchbar and a fancy user interface. You can access this result in the same git repository in the hello-world-sdk-fancy branch.

Figure 3. How we want it to look like

For this result we will have to add a CSS and a JavaScript file. Therefor we add a css folder with `fancy.css in it and a `buttonlistener.js in a js folder inside resources.

HelloWorld/
  resources/
    css/ (1)
      fancy.css
    js/ (2)
      buttonlistener.js
    lib/
      guzzle_connector.php (1)
    views/
      content/
        hello.twig
  src/
    Providers/
      HelloWorldRouteServiceProvider.php
      HelloWorldServiceProvider.php
    Controllers/
      ContentController.php
  plugin.json

1	The new css folder, with fancy.css in it.
2	The new js folder, with our JavaScript code.

Let’s take a look at the new hello.twig file