README

PHP library for consuming X-Road services.

It exposes service level request and response to the end application and hides low level logic (SOAP, HTTP).

The HTTP communication uses PSR-18 compatible client which must be installed separately. This approach gives full control over HTTP layer if needed.

Compatibility

PHP ^8.0

(For PHP ^7.2 use version 0.1.0)

Installation

composer install raigu/x-road-client

Usage

<?php
$service = \Raigu\XRoad\Service::create(
    'EE/COM/00000000/SubSys/Service/v0', // service name
    'EE/COM/00000000/SubSys', // client name
    \Raigu\XRoad\SecurityServer::create(
        'https://security-server.client.com', // client's security server
        new Client // Any PSR-18 compatible client.    
    )
);

$response = $service->request(<<<EOD
    <prod:testService xmlns:prod="http://test.x-road.fi/producer">
        <request>
            <responseBodySize>5</responseBodySize>
         </request>
    </prod:testService>
EOD
);

echo $response; // will output the service provider's response extracted from SOAP envelope 

Documentation

Service Request

Service request can be made based on WSDL using tools like Anayze WSDL or SoapUI. See video how to create one.

WSDL can be downloaded from X-Road catalog. Use service name to look it up.

Error Handling

The Service will throw an exception if:

• received response with status code other than 2xx
• received SOAP Fault.
• other communication problem

HTTP Communication

If you have a client which is not PSR-18 compatible but can handle PSR-7 request and response then you can write an adapter. For example if you have already installed Guzzle package and want to re-use it then you can create an adapter like this:

class GuzzleAdapter implements \Psr\Http\Client\ClientInterface
{
    /**
     * @var \GuzzleHttp\Client
     */
    private $client;

    public function sendRequest(\Psr\Http\Message\RequestInterface $request): \Psr\Http\Message\ResponseInterface
    {
        return $this->client->send($request);
    }

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

Demo

One way to check this library out is to set up local X-Road test server in docker and make a test request.

Install library locally.

$ git clone git@github.com:raigu/x-road-client.git
$ cd x-road-client
$ composer install

Execute X-Road test server in docker container

$ docker run --rm -p 8080:8080 petkivim/x-road-test-service:v0.0.3

Install PSR-18 client. In current sample we will be using

$ composer require php-http/curl-client

Create a file request.php in project's root directory:

<?php
require_once 'vendor/autoload.php';

$service = \Raigu\XRoad\Service::create(
    $name = 'NIIS-TEST/GOV/0245437-2/TestService/testService/v1',
    $client = 'NIIS-TEST/GOV/123456-7/testClient',
    \Raigu\XRoad\SecurityServer::create(
        'http://localhost:8080/test-service-0.0.3/Endpoint', // Win users: use your ip. Execute "docker-machine ip"
        new Http\Client\Curl\Client
    )
);

$response = $service->request(<<<EOD
    <prod:testService xmlns:prod="http://test.x-road.fi/producer">
        <request>
            <responseBodySize>5</responseBodySize>
            <responseAttachmentSize>0</responseAttachmentSize>
         </request>
    </prod:testService>
EOD
);

echo $response; // will output the service provider's response extracted from SOAP envelope 

Execute the script:

$ php request.php

You should see output:

<ts1:request xmlns:ts1="http://test.x-road.fi/producer">
    <ts1:responseBodySize>5</ts1:responseBodySize>
    <ts1:responseAttachmentSize>0</ts1:responseAttachmentSize>
</ts1:request>

See my blog post for more info about testing X-Road services manually.

License

Licensed under MIT