Skip to content

Latest commit

 

History

History
386 lines (256 loc) · 13.4 KB

how-to.rst

File metadata and controls

386 lines (256 loc) · 13.4 KB
Raw

HOW TO

How to use this library

Contents

Getting started

See the getting started guide.

Switching between stateful & stateless messages (Soap Header 4)

If you do not require an active context in your session, you're better off using stateless messages.

However, for many operations, you'll need an active context (a PNR context, a pricing context, ...).

You can easily switch from stateful to stateless messages at runtime with:

$client->setStateful(false); //Enable stateless messages

$client->setStateful(true); //Enable stateful messages

It's also possible to specify the default stateful setting at construction time of the client (stateful is enabled by default):

use Amadeus\Client;
use Amadeus\Client\Params;

$params = new Params([
    'sessionHandlerParams' => [
        //... other parameters omitted for clarity ...
        'stateful' => false,
    ]
]);

$client = new Client($params);

Ending a stateful session (Soap Header 4)

After doing multiple calls with a stateful session, there are two ways to end the session:

  • do a Security_SignOut call:
$client->signOut(); //Terminates an active stateful session. There is no active session with stateless messages.
  • set an 'endSession' message option on the last call you want to make:
$client->pnrRetrieve(
    new PnrRetrieveOptions(['recordLocator' => 'ABC123']),
    ['endSession' => true]
);

WSAP's with multiple WSDL's

Amadeus sometimes provides you with multiple WSDL files in a single WSAP. New features in the Amadeus Web Services are sometimes implemented as "interfaces". This library supports those interfaces (although at the time of writing, it does not yet support any message that can be found in an interface WSDL).

You can provide all the WSDL's in your WSAP by passing an array of wsdl's in the Client Params:

use Amadeus\Client;
use Amadeus\Client\Params;

//Set up the client with necessary parameters:

$params = new Params([
    'authParams' => [
        'officeId' => 'BRUXX1111',
        'userId' => 'WSBENXXX',
        'passwordData' => 'dGhlIHBhc3N3b3Jk'
    ],
    'sessionHandlerParams' => [
        'soapHeaderVersion' => Client::HEADER_V4,
        'wsdl' => [
            '/home/user/mytestproject/data/amadeuswsdl/1ASIWXXXXXX_PDT_20160101_080000.wsdl',
            '/home/user/mytestproject/data/amadeuswsdl/1ASIWXXXXXX_PDT_MediaServer_1.0_4.0.wsdl'
        ],
        'logger' => new Psr\Log\NullLogger()
    ]
]);

$client = new Client($params);

You can now call messages from any of the loaded WSDL while staying in the same session & context.

Handling sessions with Soap Header 2

Soap Header 2 based applications are a bit more cumbersome to handle in order to get a successful certification:

  • you need to implement session pooling in order to limit the number of session creation/destruction events
  • you need to enforce your maximum number of concurrent sessions
  • you need to send a separate authentication message before you can do anything

This library does not provide any session pooling mechanism, you'll have to implement this yourself.

You can get a current session's info (for later re-use) by calling

$client->getSessionData();

You can restore a previous current session after you retrieved it from your session pool for later re-use:

$previousSessionData = [
    'sessionId' => 'XFHZEKLRZHREJ',
    'sequenceNumber' => 5,
    'securityToken' => 'RKLERJEZLKRHZEJKLRHEZJKLREZRHEZK'
];

$client->setSessionData($previousSessionData);

Handling the response

The response from a Web Service call made through this library will be an instance of the Amadeus\Client\Result class: this object contains:

  • A status to indicate if the message was successful (FATAL, ERROR, WARN, INFO, OK) (property status)
  • Any error or other messages that provide more information about the status (property messages)
  • The response object as generated by the \SoapClient (property response)
  • The message XML string (property responseXml) (can be disabled)

When processing a response from the Amadeus Web Services, the library will check for any error or other status messages in the response and set the status accordingly.

Sometimes it's useful if the result from the SOAP call gets returned as a PHP object, sometimes a string containing the XML document of the SOAP-BODY is more useful.

For example, when trying to extract specific information from a PNR, it can be useful to load the PNR_Reply as a \DOMDocument and query it using a \DOMXPath object: for this, you can use the Amadeus\Client\Result::responseXml from the result object.

Disabling XML as string in Result

When working with large messages, it may be preferred to not return the XML as string in the responseXml property of the Result: This behaviour can be disabled or enabled with a parameter in the Client's parameterset (Amadeus\Client\Params):

use Amadeus\Client;
use Amadeus\Client\Params;

$params = new Params([
    'returnXml' => false,
    // Other parameters omitted for this example
]);

$client = new Client($params);

When configured as in the above example, the responseXml property will not be populated with the XML string.

You can override the default behaviour for a message by passing an array with a 'resultXml' key in the second parameter of a message call:

use Amadeus\Client;
use Amadeus\Client\Result;
use Amadeus\Client\RequestOptions\FareInformativePricingWithoutPnrOptions;

$options = new FareInformativePricingWithoutPnrOptions([
    //message options omitted for this example
]);

$result = $client->fareInformativePricingWithoutPnr(
    $options,
    ['returnXml' => true]
);

In the above example, the XML string will be populated in $result->responseXml, overriding the default behaviour.

The opposite is also possible: enable by default but disable when calling specific messages:

use Amadeus\Client;
use Amadeus\Client\Result;
use Amadeus\Client\Params;
use Amadeus\Client\RequestOptions\FareInformativePricingWithoutPnrOptions;

$params = new Params([
    'returnXml' => true, //'true' is the default value and can be omitted.
    // Other parameters omitted for this example
]);

$options = new FareInformativePricingWithoutPnrOptions([
    //message options omitted for this example
]);

$result = $client->fareInformativePricingWithoutPnr(
    $options,
    ['returnXml' => false]
);

Errors

The Amadeus web services can be tricky with regards to error detection. In most verbs, you have to look for the presence of error nodes in the response to see if everything went allright.

We try to ease your pain a little by analyzing the messages we support and look for error nodes. If any are found, we will put any error messages in the Amadeus\Client\Result::messages property of the result and set the result status accordingly.

If the Amadeus server responds with a \SoapFault, the library will convert this to a Result object with status 'FATAL'.

To override this behaviour, look at the Amadeus\Client\ResponseHandler\ResponseHandlerInterface. You can inject your custom implementation of the ResponseHandlerInterface on Client instantiation in the Amadeus\Client\Params::$responseHandler property.

Custom SoapClient options

You can override the default \SoapClient options by passing them in the Session Handler Params:

$params = new Params([
    'sessionHandlerParams' => [
        // ...
        // other parameters omitted for clarity
        // ...
        'soapClientOptions' => [
            'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP
        ]
    ],
    'requestCreatorParams' => [
        'receivedFrom' => 'my test project'
    ]
]);

SoapClient options provided as such will override the default settings defined in Amadeus\Client\Session\Handler\Base::$soapClientOptions and must be provided in the correct format as specified in the PHP manual: http://php.net/manual/en/soapclient.soapclient.php

Logging request and response

As you can see in the example above, you can provide a PSR-3 compatible Logging object on client instantiation. When you do this, all requests and responses in XML format will be logged to it.

This can be useful for debugging purposes, or when working with Amadeus Support.

Here's an example of how to use a Monolog logging object, which logs to a simple ascii file:

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Amadeus\Client;
use Amadeus\Client\Params;
use Amadeus\Client\RequestOptions\PnrRetrieveOptions;

$msgLog = new Logger('RequestResponseLogs');
$msgLog->pushHandler(new StreamHandler('/var/www/myapp/logs/requestresponse.log', Logger::INFO));


//Set up the client with logger:

$params = new Params([
    'sessionHandlerParams' => [
        'logger' => $msgLog
        // Other parameters omitted in this example
    ]
]);

$client = new Client($params);

$pnrResult = $client->pnrRetrieve(
    new PnrRetrieveOptions(['recordLocator' => 'ABC123'])
);

If you now check the logfile's contents, it will contain the request and response for the PNR_Retrieve call you just made.

Getting individual requests and responses

If you don't want to log all requests and responses to a logfile, but you need to inspect a single request or response for debugging or other purposes, you can use:

$lastMessageSent = $client->getLastRequest();

$lastResponseReceived = $client->getLastResponse();

If you also need the HTTP headers, that's possible too (exposes PHP's \SoapClient::__getLastRequestHeaders() and \SoapClient::__getLastResponseHeaders()):

$lastRequestHeaders = $client->getLastRequestHeaders();

$lastResponseHeaders = $client->getLastResponseHeaders();

Dealing with multiple versions of a message in your WSDL

Often, when your WSDL gets upgraded to new message versions by Amadeus, they will leave the older versions of the message in the WSDL. When using such a WSDL, the library will use the message in the WSDL it finds first (=the oldest version).

If you want the library to use the newest version of a message, you have to manually remove the old versions from the WSDL file.

Transaction Flow Link header

An option can be enabled on a WSAP where all message operations are tagged with a unique ID which can be used by an application developer to link certain messages to a certain session or user on their system. This is called the Transaction Flow Link.

To use this feature, initialize your client like this:

$params = new Params([
    // Other parameters omitted for this example!
    'sessionHandlerParams' => [
        'soapHeaderVersion' => Client::HEADER_V4,
        'wsdl' => '/home/user/mytestproject/data/amadeuswsdl/1ASIWXXXXXX_PDT_20160101_080000.wsdl',
        // Other parameters omitted for this example!
        'enableTransactionFlowLink' => true,
    ],
]);

$client = new Client($params);

Used like this, a Consumer ID will be generated on the first request which will be used during subsequent request.

If you want to re-use the same Consumer ID in subsequent Client instances, you'll have to get the current Consumer ID like this:

$consumerId = $client->getConsumerId();

Then, when re-instantiating a client, you can restore a previously used Consumer ID like this:

$consumerId = $client->setConsumerId($consumerId);

or like this:

$params = new Params([
    // Other parameters omitted for this example!
    'sessionHandlerParams' => [
        'soapHeaderVersion' => Client::HEADER_V4,
        'wsdl' => '/home/user/mytestproject/data/amadeuswsdl/1ASIWXXXXXX_PDT_20160101_080000.wsdl',
        // Other parameters omitted for this example!
        'enableTransactionFlowLink' => true,
        'consumerId' => $consumerId,
    ],
]);

$client = new Client($params);

EXAMPLE MESSAGES

See examples.