Return more helpful data from a poll

Also update dubious docs that appear to have been
copy/pasted from a VAT use case.

src/GiftAid.php

@@ -865,25 +865,10 @@ public function requestClaimData()
      *
      * If the resource is still pending this method will return the same array
      * as declarationRequest() -- 'endpoint', 'interval' and 'correlationid' --
-     * if not then it'll return lots of useful information relating to the return
-     * and payment of any VAT due in the following array format:
+     * if not then it'll also return 2 additional array keys:
      *
-     *  message => an array of messages ('Thank you for your submission', etc.).
-     *  accept_time => the time the submission was accepted by the HMRC server.
-     *  period => an array of information relating to the period of the return:
-     *    id => the period ID.
-     *    start => the start date of the period.
-     *    end => the end date of the period.
-     *  payment => an array of information relating to the payment of the return:
-     *    narrative => a string representation of the payment (generated by HMRC)
-     *    netvat => the net value due following this return.
-     *    payment => an array of information relating to the method of payment:
-     *      method => the method to be used to pay any money due, options are:
-     *        - nilpayment: no payment is due.
-     *        - repayment: a repayment from HMRC is due.
-     *        - directdebit: payment will be taken by previous direct debit.
-     *        - payment: payment should be made by alternative means.
-     *      additional => additional information relating to this payment.
+     *  submission_response_xml     => The whole XML response Body, as a string
+     *  submission_response_message => The first `->SuccessResponse->Message` key from the Body.
      *
      * @param string $correlationId The correlation ID of the resource to poll. Can be skipped with a null value.
      * @param string $pollUrl       The URL of the Gateway to poll.
@@ -928,10 +913,15 @@ public function declarationResponsePoll($correlationId = null, $pollUrl = null)
         if (!$this->responseHasErrors()) {
             $messageQualifier = (string) $this->fullResponseObject->Header->MessageDetails->Qualifier;
             if ($messageQualifier === 'response') {
+
+                /** @var \SimpleXMLElement $body */
+                $body = $this->getResponseBody();
                 return [
-                    'correlationid'       => $correlationId,
-                    'submission_request'  => $this->fullRequestString,
-                    'submission_response' => $this->fullResponseString
+                    'correlationid'                 => $correlationId,
+                    'submission_request'            => $this->fullRequestString,
+                    'submission_response'           => $this->fullResponseString,
+                    'submission_response_xml'       => $body->asXML(),
+                    'submission_response_message'   => (string) $body->SuccessResponse->Message,
                 ];
             }
 

tests/GovTalk/GiftAid/GiftAidTest.php

@@ -583,6 +583,32 @@ public function testDeclarationResponsePoll(): void
         $this->assertSame('A19FA1A31BCB42D887EA323292AACD88', $response['correlationid']);
     }
 
+    public function testMultiClaimPollSuccessAndResponseDataFormat(): void
+    {
+        $this->setMockHttpResponse('MultiClaimResponsePoll.xml');
+        $this->gaService = $this->setUpService(); // Use client w/ mock queue.
+
+        $response = $this->gaService->declarationResponsePoll(
+            '456',
+            'https://secure.dev.gateway.gov.uk/poll'
+        );
+
+        $this->assertArrayNotHasKey('errors', $response);
+        $this->assertEquals('response', $this->gaService->getResponseQualifier());
+
+        $this->assertArrayHasKey('correlationid', $response);
+        $this->assertArrayHasKey('submission_response', $response);
+        $this->assertArrayHasKey('submission_response_xml', $response);
+        $this->assertArrayHasKey('submission_response_message', $response);
+
+        $this->assertIsString($response['submission_response']);
+        $this->assertIsString($response['submission_response_xml']);
+        $this->assertIsString($response['submission_response_message']);
+
+        $this->assertEquals('456', $response['correlationid']);
+        $this->assertEquals('Thank you for your submission', $response['submission_response_message']);
+    }
+
     public function testRequestClaimData()
     {
         $this->setMockHttpResponse('RequestClaimDataResponse.xml');

tests/GovTalk/GiftAid/Mock/MultiClaimResponsePoll.xml

@@ -0,0 +1 @@
+<?xml version='1.0' encoding='UTF-8'?><GovTalkMessage xmlns="http://www.govtalk.gov.uk/CM/envelope"><EnvelopeVersion>2.0</EnvelopeVersion><Header><MessageDetails><Class>HMRC-CHAR-CLM-MULTI</Class><Qualifier>response</Qualifier><Function>submit</Function><TransactionID>123</TransactionID><CorrelationID>456</CorrelationID><ResponseEndPoint PollInterval="10">https://secure.dev.gateway.gov.uk/poll</ResponseEndPoint><Transformation>XML</Transformation><GatewayTimestamp>2022-04-04T14:56:57.187</GatewayTimestamp></MessageDetails><SenderDetails/></Header><GovTalkDetails><Keys></Keys></GovTalkDetails><Body><SuccessResponse xmlns="http://www.inlandrevenue.gov.uk/SuccessResponse"><IRmarkReceipt><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:SignedInfo><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><dsig:Reference><dsig:Transforms><dsig:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"><dsig:XPath>(count(ancestor-or-self::node()|/gti:GovTalkMessage/gti:Body)=count(ancestor-or-self::node())) and (count(ancestor-or-self::node()|/gti:GovTalkMessage/gti:Body/*[name()='IRenvelope']/*[name()='IRheader']/*[name()='IRmark'])!=count(ancestor-or-self::node()))</dsig:XPath></dsig:Transform><dsig:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><dsig:DigestValue>someDigest</dsig:DigestValue></dsig:Reference></dsig:SignedInfo><dsig:SignatureValue>someSig==</dsig:SignatureValue><dsig:KeyInfo><dsig:X509Data><dsig:X509Certificate>someCert=</dsig:X509Certificate></dsig:X509Data></dsig:KeyInfo></dsig:Signature><Message code="0000">HMRC has received the HMRC-CHAR-CLM-MULTI document ref: 92100000000000 at 08.53 on 04/04/2022. The associated IRmark was: 7QAAAAA000000AAAAAAAAA. We strongly recommend that you keep this receipt electronically, and we advise that you also keep your submission electronically for your records. They are evidence of the information that you submitted to HMRC.</Message></IRmarkReceipt><Message code="077001">Thank you for your submission</Message><AcceptedTime>2022-04-04T08:53:35.179</AcceptedTime></SuccessResponse></Body></GovTalkMessage>