Getting started¶

This example provides the necessary information to get you started quickly. In this example we show you how to connect JTL-Wawi to a PHP-based platform and enable it to synchronize data between the two systems. Although it is not technically required to use PHP for JTL-Connector, this language is the only language we officially support on the server side.

While application environments like ASP.NET or Java can be used as well, you would then be required to implement the complete protocol logic by yourself. Of course you could mimic the structure of the provided PHP library, but this goes far beyond the scope of this beginner’s guide. We are going to continue using PHP in the course of this book.

Preliminary note¶

All code specific for this example, i.e. code that is specific for the targeted software system that should be connected to JTL-Wawi, resides in the jtl\Connector\Example namespace. You have to use a different namespace prefix for your implementation. A possible approach is to combine your company’s name with the system you want JTL-Wawi to connect to. So if your company was named “ACME Inc.” and you wanted to connect to your own hypothetic eCommerce platform called “ACME Shop” a suitable namespace prefix would be Acme\Connector\AcmeShop.

Note

Consider the PSR-0 and PSR-4 standard documents if you have any questions regarding the naming of PHP namespaces.

Architecture¶

The interface between JTL-Wawi and JTL-Connector consists of two layers. The first layer, provided by JTL-Software, is called jtlconnector.

jtlconnector arbitrates between JTL-Wawi and your so-called endpoint logic. Your endpoint is the last piece of code and bridges between jtlconnector and your target system.

To achieve this, JTL-Connector makes use of the widely known MVC pattern. jtlconnector provides the models and the view layer. Your opportunity is to provide the appropriate controller code to read data from or write data to your target system.

Controller Logic <insert image here>

index.php¶

index.php is the first script to be executed when JTL-Wawi tries to connect to JTL-Connector. Note that some software products require you to create a real plugin along with additional boilerplate code before you are able to pass execution to JTL-Connector. Consult the developer documentation of the target platform if you are unsure.

During this book we assume that we can place a file called index.php inside a jtlconnector/ directory so that it can be called from http://www.shopdomain.tld/jtlconnector/. It is up to you to make sure that this call succeeds in your environment before you may continue.

Place the following code inside index.php:

<?php
defined('CONNECTOR_DIR') || define("CONNECTOR_DIR", __DIR__);

include (__DIR__ . "/src/bootstrap.php");

bootstrap.php¶

We follow the widely adopted PSR-4 standard in this book. It is therefore recommended to use a “bootstrap file” that prepares the PHP execution environment, sets up autoloading, etc. As Composer is being used to manage library dependencies, the bootstrap file needs to load the autoloader generated by Composer, too.

<?php

// Initialize the autoloader generated by Composer
require_once (__DIR__ . "/../vendor/autoload.php");

use jtl\Connector\Application\Application;
use jtl\Connector\Example\Connector;

$application = null;

try {
    // ...

    // Connector instance
    $connector = Connector::getInstance();
    $application = Application::getInstance();
    $application->register($connector);
    $application->run();
} catch (\Exception $e) {
    if (is_object($application)) {
        $handler = $application->getErrorHandler()->getExceptionHandler();
        $handler($e);
    }
}

After the bootstrap code initializes the autoloader, it loads the Connector class and the application class. The application class manages communication with the client (usually JTL-Wawi), handles the protocol layer and forwards all requests to the Connector class. Its function is to handle these requests and returns the results back to the application object that wraps the result in the communication protocol and responds to the client.

The application implementation and thus the protocol layer, too, is shared between all PHP-based endpoints.

Note

It is strongly recommended to use the official implementation by JTL-Software (i.e. jtlconnector) because it is absolutely necessary for the protocol layer to be compatible with JTL-Wawi’s expectations. Your code only needs to make use of the classes and methods provided by jtlconnector. Modifications to this library are never necessary and therefore legally prohibited.