Search Knowledge Base Articles

Development

Action

The src/ folder contains the action code which is executed if a request arrives at an endpoint which was specified in the .canpi.yml deploy file. Canpi determines the engine based on the provided action string. The following engines are available:

Engines

PHP File

action: "${dir.src}/Todo/collection.php"
If the action points to a file with a php file extension Canpi simply includes this file. In the following an example implementation:

<?php
/**
 * @var \Canpi\Engine\ConnectorInterface $connector
 * @var \Canpi\Engine\ContextInterface $context
 * @var \Canpi\Engine\RequestInterface $request
 * @var \Canpi\Engine\Response\FactoryInterface $response
 * @var \Canpi\Engine\ProcessorInterface $processor
 * @var \Psr\Log\LoggerInterface $logger
 * @var \Psr\SimpleCache\CacheInterface $cache
 */

// @TODO handle request and return response

$response->build(200, [], [
    'message' => 'Hello World!',
]);

HTTP Url

action: "http://foo.bar"
If the action contains an http or https url the request gets forwarded to the defined endpoint. Canpi automatically adds some additional headers to the request which may be used by the endpoint i.e.:
X-Canpi-Route-Id: 72
X-Canpi-User-Anonymous: 1
X-Canpi-User-Id: 4
X-Canpi-App-Id: 3
X-Canpi-App-Key: 1ba7b2e5-fa1a-4153-8668-8a855902edda
X-Canpi-Remote-Ip: 127.0.0.1

Static file

action: "${dir.src}/static.json"

If the action points to a simple file Canpi will simply forward the content to the client. This is helpful if you want to build fast and sample API with dummy responses.

PHP Class

action: "App\\Todo\\CollectionAction"

If the action string is a PHP class Canpi tries to autoload this class through composer. The class must implement the Canpi\Engine\ActionInterface. This is the most advanced solution since it is also possible to access services from the DI container. In the following an example implementation:

<?php

namespace App\Todo;

use Canpi\Engine\ActionAbstract;
use Canpi\Engine\ContextInterface;
use Canpi\Engine\ParametersInterface;
use Canpi\Engine\RequestInterface;

class CollectionAction extends ActionAbstract
{
    public function handle(RequestInterface $request, ParametersInterface $configuration, 
                   ContextInterface $context)
    {
        // @TODO handle request and return response

        return $this->response->build(200, [], [
            'message' => 'Hello World!',
        ]);
    }
}

Examples

Please take a look at the recipes section of our website, there we have example code to complete a specific task i.e. send a HTTP request or query data from a database.

Connection

Inside an action you can use the connector to obtain a configured connection. The following list contains connection classes which you can use. Note some connections depend on PHP extensions or other client libraries, you have to install the fitting adapter in order to use the connection. Take a look at the adapter page for an overview of available adapters.

Sql

Connects to a SQL database using the doctrine DBAL library.

Class
Canpi\Adapter\Sql\Connection\Sql
Return
Doctrine\DBAL\Connection
Website
http://www.doctrine-project.org/projects/dbal.html
API
http://www.doctrine-project.org/api/dbal/2.5/class-Doctrine.DBAL.Connection.html


Config

type

The driver which is used to connect to the database

  • pdo_mysql = MySQL
  • pdo_pgsql = PostgreSQL
  • sqlsrv = Microsoft SQL Server
  • oci8 = Oracle Database
  • sqlanywhere = SAP Sybase SQL Anywhere
host
     
      The IP or hostname of the database server

username

      The name of the database user

password

    The password of the database user

database

    The name of the database which is used upon connection


MongoDB

Connects to a MongoDB using the official MongoDB library. Note this requires the PHP mongodb extension.

Class
Canpi\Adapter\Mongodb\Connection\MongoDB
Return
MongoDB\Database
Website
https://github.com/mongodb/mongo-php-library
API
https://docs.mongodb.com/php-library/master/reference/class/MongoDBDatabase/


config

url
The url must have the following format 
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
options
It is possible to provide option parameters. The options must be url encoded i.e. 
connect=1&fsync=1
database
The name of the database which is used upon connection

HTTP

Uses the Guzzle library to send HTTP requests.

Class
Canpi\Adapter\Http\Connection\Http
Return
GuzzleHttp\Client
Website
http://docs.guzzlephp.org/en/latest/

Config

url
       HTTP base url

username
        Optional username for authentication

password
       Optional password for authentication

proxy
       Optional HTTP proxy


AMQP

Provides a client to send messages to a RabbitMQ.

Class
Canpi\Adapter\Amqp\Connection\Amqp
Return
PhpAmqpLib\Connection\AMQPStreamConnection
Website
https://github.com/php-amqplib/php-amqplib

config

host
        The IP or hostname of the RabbitMQ server

port
        The port used to connect to the AMQP broker. The port default is 5672

user
        The login string used to authenticate with the AMQP broker

password
       The password string used to authenticate with the AMQP broker

vhost
      The virtual host to use on the AMQP broker

Beanstalk

Provides a client to send messages to a Beanstalkd.

Class
Canpi\Adapter\Beanstalk\Connection\Beanstalk
Return
Pheanstalk\Pheanstalk
Website
https://github.com/pda/pheanstalk


config

host
   
   The IP or hostname of the Beanstalk server

port

Optional the port of the Beanstalk server

Cassandra

Connects to a Cassandra database using the official PHP library. Requires the CASSANDRA PHP extension.

Class
Canpi\Adapter\Cassandra\Connection\Cassandra
Return
Cassandra\Session
Website
https://github.com/datastax/php-driver
API
http://datastax.github.io/php-driver/api/Cassandra/interface.Session/

config

host
       Configures the initial endpoints. Note that the driver will automatically discover and connect to the rest of the cluster

port
      Specify a different port to be used when connecting to the cluster

keyspace
      Optional keyspace name


Elasticsearch

Connects to a Elasticsearch database using the official PHP library.

Class
Canpi\Adapter\Elasticsearch\Connection\Elasticsearch
Return
Elasticsearch\Client
Website
https://github.com/elastic/elasticsearch-php


config

host

      Comma separated list of elasticsearch hosts i.e.
192.168.1.1:9200,192.168.1.2

Memcache

Uses the native PHP memcached extension to connect to a memcache server.

Class
Canpi\Adapter\Memcache\Connection\Memcache
Return
Memcached
Website
http://php.net/manual/de/book.memcached.php

config

host
      Comma seperated list of [ip]:[port] i.e.   
192.168.2.18:11211,192.168.2.19:11211

Neo4j

     Connects to a Neo7j graph database using the official PHP library.

Class
Canpi\Adapter\Neo4j\Connection\Neo4j
Return
GraphAware\Neo4j\Client\ClientInterface
Website
https://github.com/graphaware/neo4j-php-client

config

uri
 
  URI of the connection i.e. http://neo4j:password@localhost:7474

SOAP

Provides a client to send SOAP requests.

Class
Canpi\Adapter\Soap\Connection\Soap
Return
SoapClient
Website
http://php.net/manual/de/class.soapclient.php


config

wsdl
    Location of the WSDL specification

location
   Required if no WSDL is available

uri
  Required if no WSDL is available

version

Optional SOAP version

  • 1 = SOAP 1.1
  • 2 = SOAP 1.2
username
Optional username for authentication

password
Optional password for authentication

Business logic

In case your API is not a simple CRUD app you probably need to execute some more complex business logic. This chapter shows options how you can organize this business logic for simple reuse.

In general an action should not contain any business logic it should simply forward the data to the fitting library or service. It is equivalent to a controller in a classical framework environment. If an action contains too many lines of code or you copy specific code snippets into different actions it is a smell to extract this logic into an external service. Inside an action you can then reuse this external service.

Canpi is designed to help you write framework independent code. That means that all services which you develop are complete free of Canpi specific code so you can simply reuse those components in another context.

DI Container

Canpi uses a DI container to manage all internal services. In Canpi all services are defined in a simple PHP class so there is no yaml configuration. To define a custom service you need to create a container class i.e. at src/Dependency/Container.php. This class then needs to extend the Canpi container:

<?php

namespace App\Dependency;

use Canpi\Impl\Dependency\Container as CanpiContainer;

class Container extends CanpiContainer
{
    public function getMyService(): MyServiceInterface
    {
        return new MyService(
            $this->get('connector')->getConnection('System'),
            $this->get('engine_dispatcher')
        );
    }
}
In this example we simply define a new service. To use this container you need to create a new instance of this container at the container.php file.

<?php

$container = new Fusio\Impl\Dependency\Container();
$container->setParameter('config.file', __DIR__ . '/configuration.php');

return $container;
Then you can use the autowire feature of the DI container to receive the dependencies through constructor injection. In the following we create an action which automatically receives the MyServiceInterface based on the type-hint. It is important that the type-hint and the return type of the method at the DI container match.

<?php

namespace App\Action\Page;

use Canpi\Engine\ActionAbstract;
use Canpi\Engine\ContextInterface;
use Canpi\Engine\ParametersInterface;
use Canpi\Engine\RequestInterface;

class MyAction extends ActionAbstract
{
    private $myService;

    public function __construct(MyServiceInterface $myService)
    {
        $this->myService = $myService;
    }

    public function handle(RequestInterface $request, ParametersInterface $configuration,
       ContextInterface $context)
    {
        $body = [
            'result' => $this->myService->doStuff();
        ];

        return $this->response->build(200, [], $body);
    }
}

Library

The simplest solution is to move business logic into a separate PHP class. This class can be autoloaded through composer. You can place this class either directly into the src/ folder or develop a custom PHP package and require this package through composer.

In general a library should work with a specific connection. The following example shows a simple custom logger implementation which you could use in different actions.

<?php

$connection = $connector->get('Mysql-1');

$myLogger = new MyLogger($connection);
$myLogger->log('A new log entry');

A simple implementation of the logger could look like:

<?php

namespace Acme\MyLib;

use Doctrine\DBAL\Connection;

class MyLogger
{
    /**
     * @var \Doctrine\DBAL\Connection
     */
    protected $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public function log($message)
    {
        $this->connection->insert('my_table', [
            'message' => $message,
        ]);
    }
}

Microservice

If your business logic is more complex or has specific performance requirements you could also develop it as an external microservice. This has the advantage that service is completely decoupled from your app and it is also possible to use a complete different language. Usually you can talk to the micro service through HTTP. But it would be also possible to use a different protocol i.e. an AMQP connection to use a message queue.

<?php

$client = $connector->get('Http-1');

$myClient = new MyClient($client);
$myClient->send(['foo' => 'bar']);
A simple client implementation could look like:

<?php

namespace Acme\MyLib;

use GuzzleHttp\Client;

class MyClient
{
    /**
     * @var \GuzzleHttp\Client
     */
    protected $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function send($data)
    {
        $this->client->post('http://foo.bar/my_service', [
            'json' => $data
        ]);
    }
}

Deploy

The .Canpi.yml deploy file is the main configuration file to develop an API with Canpi. This chapter explains in detail the format.

routes

A route is the rule which redirects the incoming request to an action. If a request arrives the first route which matches is used. In order to be able to evolve an API it is possible to add multiple versions for the same route. For each version it is possible to specify the allowed request methods. Each method describes the request and response schema and the action which is executed upon request. If a request method is public it is possible to request the API endpoint without an access token.

version: 1
methods:
  GET:
    public: true
    response: Todo-Collection
    action: "${dir.src}/Todo/collection.php"
  POST:
    public: false
    request: Todo
    response: Todo-Message
    action: "${dir.src}/Todo/insert.php"

The request and response key reference a schema name which was defined under the schema key. It is also possible to use the Passthru schema which simply redirects all data. The action key reference an action.

Path

The path can contain variable path fragments. It is possible to access these variable path fragments inside an action. The following list describes the syntax.

  • /news No variable path fragment only the request to /news matches this route
  • /news/:news_id Simple variable path fragment. This route matches to any value except a slash. I.e. /news/foo or /news/12 matches this route
  • /news/$year<[0-9]+> Variable path fragment with a regular expression. I.e. only /news/2015 matches this route
  • /file/*path Variable path fragment which matches all values. I.e. /file/foo/bar or /file/12 matches this route

Status

Beside the version every route can also have a status field. By default the status is set to 4 (Development). If you change the status to 1 (Production) it is not longer possible to change the API endpoint through the backend. The following list describes each status

  • 4 = Development Used as first status to develop a new API endpoint. It adds a “Warning” header to each response that the API is in development mode.
  • 1 = Production Used if the API is ready for production use. If the API transitions from development to production all databases settings are copied into the route. That means changing a schema or action will not change the API endpoint.
  • 2 = Deprecated Used if you want to deprecate a specific version of the API. Adds a “Warning” header to each response that the API is deprecated.
  • 3 = Closed Used if you dont want to support a specific version anymore. Returns an error message with a 410 Gone status code

schema

The schema defines the format of the request and response data. It uses the JsonSchema format. Inside a schema it is possible to refer to other schema definitions by using the $ref key and the file protocol i.e. file:///[file].

{
    "id": "http://acme.com/schema",
    "type": "object",
    "title": "schema",
    "properties": {
        "name": {
            "type": "string"
        },
        "author": {
            "$ref": "file:///author.json"
        },
        "date": {
            "type": "string",
            "format": "date-time"
        }
    }
}

connection

A connection provides a class which helps to connect to another service.

Acme-Mysql:
  class: canpi\Adapter\Sql\Connection\Sql
  config:
    type: pdo_mysql
    host: localhost
    username: root
    password: test
    database: canpi

Integration

Canpi is often used to create a REST API beside an existing web app. This chapter describes best practices how you can integrate your app without ignoring the business logic.

At first we should distinguish between read and write requests. A read request is a request which does not modify the state (database) of your app. For this case you can also connect directly to your app database. A write request modifies the state (database) of your app i.e. it creates a new record. In this case you most likely want to run the business logic of your app so that all data gets validated and all depending mechanisms are executed. For this case there are multiple ways to run your business logic:

HTTP

Your app provides an internal API which gets called by Canpi. In this case your action uses a HTTP connection to call the internal API of your app. The internal API also does not need to have a great design since the user only faces the Canpi endpoints. I.e. you could create a simple api.php script which bootstraps your app and invokes a specific method.

RPC</3>

Your app provides an RPC service (i.e. Apache Thrift or GRPC) which can be called by Canpi. This has also the advantage that the performance is much better then an internal HTTP API because modern RPC services mostly serialize the data into an optimized binary format instead of JSON or XML.

Message-Queue

Your app provides a message queue which Canpi can use. This has also great performance but it is a unidirectional connection, this means the message queue can never return a response to Canpi. In most cases the response message must be defined in the action. Canpi has connections to connect to a AMQP or Beanstalk message queue.

SQL

In case you have no additional business logic which needs to be executed you can also directly connect to the database and insert a new entry.

Include

Another (but not recommended) solution is to include your app bootstrap code inside an action. This is possible but then you are mixing the context between your existing app and Canpi. In most cases it is recommended to use one of the approaches described above. But for some small apps it might be also feasible since this has basically no performance penalty.

Schema

By default you need to write standard JSON Schema files to provide a schema for the request and response format of an endpoint. Besides this it is also possible to create a PHP class with specific annotations which can be transformed into JSON Schema by Canpi. This has the advantage that your action will receive this specific class as request body. At the resources/schemas.yaml file you can define a new schema using a simple PHP class name instead of a file:

MySchema: 'App\Schema\Todo'

The schema class can look like i.e.:

<?php

namespace App\Schema;

/**
 * @Title("Todo")
 */
class Todo
{
    /**
     * @Key("id")
     * @Type("integer")
     */
    protected $id;
    /**
     * @Key("status")
     * @Type("integer")
     */
    protected $status;
    /**
     * @Key("title")
     * @Type("string")
     * @MaxLength(64)
     */
    protected $title;
    /**
     * @Key("insert_date")
     * @Type("string")
     * @Format("date-time")
     */
    protected $insertDate;
    /**
     * @param int $id
     */
    public function setId(?int $id)
    {
        $this->id = $id;
    }
    /**
     * @return int
     */
    public function getId() : ?int
    {
        return $this->id;
    }
    /**
     * @param int $status
     */
    public function setStatus(?int $status)
    {
        $this->status = $status;
    }
    /**
     * @return int
     */
    public function getStatus() : ?int
    {
        return $this->status;
    }
    /**
     * @param string $title
     */
    public function setTitle(?string $title)
    {
        $this->title = $title;
    }
    /**
     * @return string
     */
    public function getTitle() : ?string
    {
        return $this->title;
    }
    /**
     * @param \DateTime $insertDate
     */
    public function setInsertDate(?\DateTime $insertDate)
    {
        $this->insertDate = $insertDate;
    }
    /**
     * @return \DateTime
     */
    public function getInsertDate() : ?\DateTime
    {
        return $this->insertDate;
    }
}

If you run the deploy command Canpi will generate a JSON Schema based on the provided annotations. Canpi uses the PSX Schema library, please take a look at project for more information about available annotations.

If you use the example schema class as request schema you would receive a PassthruRecord at your action. Through the getPayload method you can get the complete Todo instance containing the data of the request.

<?php

namespace App\Action;

use Canpi\Engine\ActionAbstract;
use Canpi\Engine\ContextInterface;
use Canpi\Engine\ParametersInterface;
use Canpi\Engine\RequestInterface;

class Test extends ActionAbstract
{
    public function handle(RequestInterface $request, ParametersInterface $configuration, 
      ContextInterface $context)
    {
        /** @var \Fusio\Impl\Record\PassthruRecord $data */
        $data = $request->getBody();

        // access the getter of the todo instance through the symfony property access component
        $title = $data->getProperty('title');

        // get the App\Schema\Todo instance
        $todo = $data->getPayload();

        return $this->response->build(200, [], [
            'success' => true,
            'title' => $title
        ]);
    }
}

Did you find this article useful?

Related Articles

  • Getting Started

    Welcome, this documentation shows all available endpoints of the internal CanPi API. Through the API...

  • Backend

    This chapter contains information about the backend. The following pages are extracted from the onli...