Merge branch 'dev-soapheader-2' into merging-soapheader2-dev

Conflicts:
	src/Amadeus/Client/Session/Handler/SoapHeader4.php
	tests/Amadeus/ClientTest.php

README.md

@@ -14,7 +14,7 @@ The Amadeus documentation portal can be found at https://webservices.amadeus.com
 
 * PHP 5.4+
 * SOAP and XSL extensions activated
-* A WSDL & authentication details from Amadeus
+* A WSDL & authentication details from Amadeus _(SoapHeader 4 or SoapHeader 2)_
 
 # Installation
 

docs/about-get-started.rst

@@ -11,7 +11,7 @@ See `the Amadeus Web Services website <https://webservices.amadeus.com/>`_ for m
 The basic pieces of information you will need to use this library are:
 
 - **The WSDL file with all its includes**: You can just extract the ZIP file you received from Amadeus to a location on your filesystem where the client can access it.
-- **The authentication information required to start a session**: Office ID's, User Id (=Originator), Password, Duty Code. *For legacy WSAP's using Soap Header 1 or 2, you'll need: Office ID, Originator, Organization ID, Password Length, Password Data. Soap Header 1 & 2 is not yet implemented in this library*
+- **The authentication information required to start a session**: Office ID's, User Id (=Originator), Password, Duty Code. *For legacy WSAP's using Soap Header 1 or 2, you'll need: Office ID, Originator, Organization ID, Password Length, Password Data. Soap Header 1 is not yet implemented in this library*
 
 You usually receive this information after the project kick-off has been done and a support person has been assigned to your project.
 
@@ -20,9 +20,12 @@ Support for Amadeus Soap Header versions
 ****************************************
 Upon receiving access, Amadeus will give you a Web Service Access Point with a specific Soap Header version to use. This will define how you can handle session management *(e.g. support for stateless calls, requiring session pooling or not)*.
 
-This library is initially built to support the current Soap Header v4, which is the Soap Header Version you would get for a new WSAP requested today (2016).
+This library is built to support the current **Soap Header 4** and the legacy **Soap Header 2**.
 
-Legacy applications using already certified WSAP's can still be running on legacy Soap Header versions - most notably Soap Header 1 & 2. This library currently doesn't support those yet, but we plan to add that in the future.
+- Soap Header 4 is the Soap Header Version you would get for a new WSAP requested today (2016).
+- Soap Header 2 is still in use in legacy applications.
+
+Legacy applications using already certified WSAP's can still be running on legacy Soap Header versions (Soap Header 1 & 2). This library doesn't support Soap Header 1 at the moment.
 
 ******************************************
 Support for different versions of messages
@@ -52,6 +55,8 @@ Install the client library in your PHP project by requiring the package with Com
 Set up a test client
 ********************
 
+Soap Header 4 example:
+
 .. code-block:: php
 
     <?php
@@ -85,13 +90,56 @@ Set up a test client
         new PnrRetrieveOptions(['recordLocator' => 'ABC123'])
     );
 
+Soap Header 2 example:
+
+.. code-block:: php
+
+    <?php
+
+    use Amadeus\Client;
+    use Amadeus\Client\Params;
+    use Amadeus\Client\RequestOptions\PnrRetrieveOptions;
+
+    //Set up the client with necessary parameters:
+
+    $params = new Params([
+        'sessionHandlerParams' => [
+            'soapHeaderVersion' => Client::HEADER_V2,
+            'wsdl' => '/home/user/mytestproject/data/amadeuswsdl/1ASIWXXXXXX_PDT_20110101_080000.wsdl', //Points to the location of the WSDL file for your WSAP. Make sure the associated XSD's are also available.
+            'logger' => new Psr\Log\NullLogger(),
+            'authParams' => [
+                'officeId' => 'BRUXX1111', //The Amadeus Office Id you want to sign in to - must be open on your WSAP.
+                'userId' => 'WSBENXXX', //Also known as 'Originator' for Soap Header 1 & 2 WSDL's
+                'passwordData' => 'dGhlIHBhc3N3b3Jk' // **base 64 encoded** password
+                'passwordLength' => 12,
+                'dutyCode' => 'SU',
+                'organizationId' => 'DUMMY-ORG',
+            ]
+        ],
+        'requestCreatorParams' => [
+            'receivedFrom' => 'my test project' // The "Received From" string that will be visible in PNR History
+        ]
+    ]);
+
+    $client = new Client($params);
+
+    $authResult = $client->securityAuthenticate();
+
+    if (isset($authResult->processStatus->statusCode) && $authResult->processStatus->statusCode === 'P') {
+        //We are authenticated!
+        $pnrContent = $client->pnrRetrieve(
+            new PnrRetrieveOptions(['recordLocator' => 'ABC123'])
+        );
+    }
+
 
 ******************
 Messages supported
 ******************
 
 This is the list of messages that are at least partially supported at this time:
 
+- Security_Authenticate
 - Security_SignOut
 - PNR_Retrieve
 - PNR_RetrieveAndDisplay
@@ -135,5 +183,3 @@ On the to-do list / work in progress:
 - Ticket_DisplayTST
 - Ticket_DeleteTST
 - SalesReports_DisplayQueryReport
-
-- Support for SoapHeader V2

docs/samples.rst

@@ -4,9 +4,9 @@ EXAMPLES
 
 Here are some examples of how you can handle some problems you might encounter and how to send specific messages.
 
-***********************************************
-Switching between stateful & stateless messages
-***********************************************
+***************************************************************
+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.
 
@@ -38,9 +38,9 @@ It's also possible to specify the default stateful setting at construction time
     $client = new Client($params);
 
 
-*************************
-Ending a stateful session
-*************************
+*****************************************
+Ending a stateful session (Soap Header 4)
+*****************************************
 
 After doing multiple calls with a stateful session, there are two ways to end the session:
 
@@ -59,6 +59,30 @@ After doing multiple calls with a stateful session, there are two ways to end th
         ['endSession' => true]
     );
 
+************************************
+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
+
+.. code-block:: php
+
+    $client->getSessionData();
+
+You can restore a previous current session after you retrieved it from your session pool for later re-use:
+
+.. code-block:: php
+
+    $client->setSessionData($previousSessionData);
+
 
 *********************
 Handling the response

src/Amadeus/Client.php

@@ -36,8 +36,7 @@
  * Amadeus Web Service Client.
  *
  * TODO:
- * - have a solution for session pooling for stateful sessions (soapheader 1 & 2)
- * - support older versions of SoapHeader (1, 2)
+ * - support older versions of SoapHeader (1)
  * - implement calls for full online booking flow:
  *      SalesReports_DisplayQueryReport
  *      Air_MultiAvailability
@@ -97,6 +96,13 @@ class Client
      */
     protected $responseHandler;
 
+    /**
+     * Authentication parameters
+     *
+     * @var Params\AuthParams
+     */
+    protected $authParams;
+
     /**
      * Set the session as stateful (true) or stateless (false)
      *
@@ -149,13 +155,33 @@ public function getLastResponse()
         return $this->sessionHandler->getLastResponse();
     }
 
+    /**
+     * Restore a previously used session
+     *
+     * To be used when implementing your own session pooling system on legacy Soap Header 2 applications.
+     *
+     * @param array $sessionData
+     * @return bool
+     */
+    public function setSessionData(array $sessionData)
+    {
+        return $this->sessionHandler->setSessionData($sessionData);
+    }
+
     /**
      * Construct Amadeus Web Services client
      *
      * @param Params $params
      */
     public function __construct($params)
     {
+        if ($params->authParams instanceof Params\AuthParams) {
+            $this->authParams = $params->authParams;
+            if (isset($params->sessionHandlerParams) && $params->sessionHandlerParams instanceof Params\SessionHandlerParams) {
+                $params->sessionHandlerParams->authParams = $this->authParams;
+            }
+        }
+
         $this->sessionHandler = $this->loadSessionHandler(
             $params->sessionHandler,
             $params->sessionHandlerParams
@@ -174,6 +200,31 @@ public function __construct($params)
         );
     }
 
+    /**
+     * Authenticate.
+     *
+     * Parameters were provided at construction time (sessionhandlerparams)
+     *
+     * @return \stdClass
+     * @throws Exception
+     */
+    public function securityAuthenticate()
+    {
+        $msgName = 'Security_Authenticate';
+        $messageOptions = $this->makeMessageOptions([], false, false);
+
+        return $this->sessionHandler->sendMessage(
+            $msgName,
+            $this->requestCreator->createRequest(
+                $msgName,
+                new RequestOptions\SecurityAuthenticateOptions(
+                    $this->authParams
+                )
+            ),
+            $messageOptions
+        );
+    }
+
     /**
      * Terminate a session - only applicable to non-stateless mode.
      *

src/Amadeus/Client/Params.php

@@ -22,6 +22,7 @@
 
 namespace Amadeus\Client;
 
+use Amadeus\Client\Params\AuthParams;
 use Amadeus\Client\Params\RequestCreatorParams;
 use Amadeus\Client\Params\SessionHandlerParams;
 use Amadeus\Client\RequestCreator\RequestCreatorInterface;
@@ -57,6 +58,13 @@ class Params
      */
     public $responseHandler;
 
+    /**
+     * Parameters for authenticating to the Amadeus Web Services
+     *
+     * @var Params\AuthParams
+     */
+    public $authParams;
+
     /**
      * Parameters required to create the Session Handler
      *
@@ -72,7 +80,6 @@ class Params
     public $requestCreatorParams;
 
 
-
     /**
      * @param array $params
      */
@@ -98,6 +105,14 @@ protected function loadFromArray(array $params) {
             $this->responseHandler = $params['responseHandler'];
         }
 
+        if (isset($params['authParams'])) {
+            if ($params['authParams'] instanceof AuthParams) {
+                $this->authParams = $params['authParams'];
+            } elseif (is_array($params['authParams'])) {
+                $this->authParams = new AuthParams($params['authParams']);
+            }
+        }
+
         if (isset($params['sessionHandlerParams'])) {
             if ($params['sessionHandlerParams'] instanceof SessionHandlerParams) {
                 $this->sessionHandlerParams = $params['sessionHandlerParams'];

src/Amadeus/Client/RequestCreator/Base.php

@@ -50,6 +50,7 @@
 use Amadeus\Client\RequestOptions\QueuePlacePnrOptions;
 use Amadeus\Client\RequestOptions\QueueRemoveItemOptions;
 use Amadeus\Client\RequestOptions\RequestOptionsInterface;
+use Amadeus\Client\RequestOptions\SecurityAuthenticateOptions;
 use Amadeus\Client\RequestOptions\TicketCreateTstFromPricingOptions;
 use Amadeus\Client\Struct;
 
@@ -110,6 +111,17 @@ protected function createSecuritySignOut()
         return new Struct\Security\SignOut();
     }
 
+    /**
+     * Create request object for Security_Authenticate message
+     *
+     * @param SecurityAuthenticateOptions $params
+     * @return Struct\Security\Authenticate
+     */
+    protected function createSecurityAuthenticate(SecurityAuthenticateOptions $params)
+    {
+        return new Struct\Security\Authenticate($params);
+    }
+
     /**
      * Create request object for PNR_Retrieve message
      *