KATANA SDK for PHP5

PHP5 SDK to interface with the KATANA™ framework (https://katana.kusanagi.io).

Requirements

KATANA Framework 1.0+
libzmq
zmq extension
msgpack extension

Installation

The PHP5 SDK can be installed using composer.

composer require kusanagi/katana-sdk-php5

Getting Started

The SDK allow both Services and Middlewares to be created. Both of them require a source file and a configuration file pointing to it.

The first step to create a Service or a Middleware is to generate the configuration file, which will define the behavior of the component. In both cases the configuration include name and version of the component and the engine and source file to run it.

The configuration file for a Service define the different actions it can respond to, and can include http configuration so it can interact with a Gateway.

"@context": urn:katana:service
name: service_name
version: "0.1"
http-base-path: /0.1
info:
  title: Example Service
engine:
  runner: urn:katana:runner:php5
  path: ./example_service.php
action:
  - name: action_name
    http-path: /action/path

The configuration of a Middleware defines which kind of action (request, response or both), it responds to.

"@context": urn:katana:middleware
name: middleware_name
version: "0.1"
request: true
response: true
info:
  title: Example Middleware
engine:
  runner: urn:katana:runner:php5
  path: ./example_middleware.php

The following example illustrates how to create a Service. Given the previous configuration file, the source file must be located at ./example_service.php, define the actions and run the component:

<?php

require __DIR__ . '/vendor/autoload.php';

$service = new \Katana\Sdk\Service();

$service->action('action_name', function (\Katana\Sdk\Action $action) {
    $action->log('Start action');

    return $action;
});

$service->run();

The following example illustrates how to create a request middleware. Given the previous configuration file, the source file must be located at ./example_middleware.php, define the request and response and run the component:

<?php

require __DIR__ . '/vendor/autoload.php';

$middleware = new \Katana\Sdk\Middleware();

$middleware->request(function (\Katana\Sdk\Request $request) {
    $request->log('Start Request');

    return $request;
});

$middleware->response(function (\Katana\Sdk\Response $request) {
    $request->log('Start Response');

    return $request;
});

$middleware->run();

Examples

One common responsibility of the request Middlewares is routing request to the Service actions. For this the Middleware should set the target Service, version and action.

<?php

require __DIR__ . '/vendor/autoload.php';

$middleware = new \Katana\Sdk\Middleware();

$middleware->request(function (\Katana\Sdk\Request $request) {
    $request->setServiceName('service');
    $request->setServiceVersion('1.0.0');
    $request->setActionName('action');

    return $request;
});

Response Middleware commonly format the data in the transport to present a response.

<?php

require __DIR__ . '/vendor/autoload.php';

$middleware = new \Katana\Sdk\Middleware();

$middleware->response(function (\Katana\Sdk\Response $response) {
    $httpResponse = $response->getHttpResponse();
    $httpResponse->setBody(
        json_encode(
            $response->getTransport()->getData()
        )
    );
    $httpResponse->setStatus(200, 'OK');

    return $response;
});

A Service can be used to group some related functionality, like a CRUD for a business model.

<?php

require __DIR__ . '/vendor/autoload.php';

$service = new \Katana\Sdk\Service();

$service->action('read', function (\Katana\Sdk\Action $action) {
    $entity = $repository->get($action->getParam('id')->getValue());
    $action->setEntity($entity);

    return $action;
});

$service->action('delete', function (\Katana\Sdk\Action $action) {
    $entity = $repository->delete($action->getParam('id')->getValue());

    return $action;
});

$service->action('create', function (\Katana\Sdk\Action $action) {
    $repository->create(array_map(function (\Katana\Sdk\Param $param) {
        return $param->getValue();
    }, $action->getParams()));

    return $action;
});

$service->action('update', function (\Katana\Sdk\Action $action) {
    $repository->update(array_map(function (\Katana\Sdk\Param $param) {
        return $param->getValue();
    }, $action->getParams()));

    return $action;
});

$service->run();

Documentation

See the API for a technical reference of the SDK, or read the full specification.

For help using the framework see the documentation, or join the community.

Support

Please first read our contribution guidelines.

We use milestones to track upcoming releases inline with our versioning strategy, and as defined in our roadmap.

For commercial support see the solutions available or contact us for more information.

Contributing

If you'd like to know how you can help and support our Open Source efforts see the many ways to get involved.

Please also be sure to review our community guidelines.

License

KUSANAGI, the sword logo, KATANA and the "K" logo are trademarks and/or registered trademarks of KUSANAGI S.L. All other trademarks are property of their respective owners.

Licensed under the MIT License. Redistributions of the source code included in this repository must retain the copyright notice found in each file.

jameswatts/katana-sdk-php5