Updated the client regarding the mosparo v1.1 changes and updated the README

Author: zepich

README.md

@@ -83,14 +83,27 @@ To verify the form data, call `verifySubmission` with the form data in an array
  *                        radio and so on) have to be removed from this array
  * @param string $mosparoSubmitToken Submit token which mosparo returned on the form initialization
  * @param string $mosparoValidationToken Validation token which mosparo returned after the form was validated
- * @return Mosparo\ApiClient\VerificationResult Returns a VerificationResult object with the response from mosparo
+ * @return \Mosparo\ApiClient\VerificationResult Returns a VerificationResult object with the response from mosparo
  * 
  * @throws \Mosparo\ApiClient\Exception Submit or validation token not available.
  * @throws \Mosparo\ApiClient\Exception An error occurred while sending the request to mosparo.
  */
 $result = $client->verifySubmission($formData, $mosparoSubmitToken, $mosparoValidationToken);
 ```
 
+#### Request the statistical data
+mosparo also has an API method to get the statistical data for a project. You can use the method `getStatisticByDate` to get the statistical data. You can specify the range in seconds or a start date from which mosparo should return the statistical data. This method will return a `StatisticResult` object.
+```php
+/**
+ * @param int $range = 0 The range in seconds for which mosparo should return the statistical data (will be rounded up to a full day since mosparo v1.1)
+ * @param \DateTime $startDate = null The Start date from which on mosparo should return the statistical data (requires mosparo v1.1)
+ * @return \Mosparo\ApiClient\StatisticResult Returns a StatisticResult object with the response from mosparo
+ * 
+ * @throws \Mosparo\ApiClient\Exception An error occurred while sending the request to mosparo.
+ */
+$result = $client->getStatisticByDate($range, $startDate);
+```
+
 ### VerificationResult
 
 #### Constants
@@ -116,4 +129,15 @@ Returns the verification status of one field.
 Returns true, if there were verification issues.
 
 #### getIssues(): array
-Returns an array with all verification issues.
+Returns an array with all verification issues.
+
+### StatisticResult
+
+#### getNumberOfValidSubmissions(): int
+Returns the total number of valid submissions in the requested date range.
+
+#### getNumberOfSpamSubmissions(): int
+Returns the total number of spam submissions in the requested date range.
+
+#### getNumbersByDate(): array
+Returns an array with all statistical data for the requested time range. The date is the key in the array, while an array is set as a value. The array contains a key `numberOfValidSubmissions` with the number of valid submissions and a key `numberOfSpamSubmissions` with the number of spam submissions.

src/Client.php

@@ -155,13 +155,14 @@ public function validateSubmission(array $formData, string $submitToken = null,
      * Retrieves the statistics data from mosparo for the given time range,
      * counted by date.
      *
-     * @param int $range Time range in seconds
+     * @param int $range Time range in seconds (will be rounded up to a full day since mosparo v1.1)
+     * @param \DateTime $startDate The start date from which the statistics are to be returned (requires mosparo v1.1)
      * @return \Mosparo\ApiClient\StatisticResult
      *
-     * @throws \Mosparo\ApiClient\Exception Submit or validation token not available.
      * @throws \Mosparo\ApiClient\Exception An error occurred while sending the request to mosparo.
+     * @throws \Mosparo\ApiClient\Exception Response from API invalid.
      */
-    public function getStatisticByDate(int $range = 0): StatisticResult
+    public function getStatisticByDate(int $range = 0, \DateTime $startDate = null): StatisticResult
     {
         $requestHelper = new RequestHelper($this->publicKey, $this->privateKey);
 
@@ -172,6 +173,10 @@ public function getStatisticByDate(int $range = 0): StatisticResult
             $queryData['range'] = $range;
         }
 
+        if ($startDate !== null) {
+            $queryData['startDate'] = $startDate->format('Y-m-d');
+        }
+
         $requestSignature = $requestHelper->createHmacHash($apiEndpoint . $requestHelper->toJson($queryData));
 
         $data = [

src/RequestHelper.php

@@ -68,8 +68,6 @@ public function prepareFormData(array $formData): array
             } else {
                 if (is_numeric($value)) {
                     $value = strval($value);
-                } else if ($value === null) {
-                    $value = '';
                 }
 
                 $data[$key] = hash('sha256', $value);

tests/ClientTest.php

@@ -236,6 +236,42 @@ public function testGetStatisticByDateWithRange()
         $this->assertEquals($numbersByDate, $result->getNumbersByDate());
     }
 
+    public function testGetStatisticByDateWithStartDate()
+    {
+        $publicKey = 'testPublicKey';
+        $privateKey = 'testPrivateKey';
+        $numbersByDate = [
+            '2021-04-29' => [
+                'numberOfValidSubmissions' => 2,
+                'numberOfSpamSubmissions' => 5
+            ]
+        ];
+
+        // Set the response
+        $this->handler->append(new Response(200, ['Content-Type' => 'application/json'], json_encode([
+            'result' => true,
+            'data' => [
+                'numberOfValidSubmissions' => 2,
+                'numberOfSpamSubmissions' => 5,
+                'numbersByDate' => $numbersByDate
+            ]
+        ])));
+
+        // Start the test
+        $apiClient = new Client('http://test.local', $publicKey, $privateKey, ['handler' => $this->handlerStack]);
+
+        $result = $apiClient->getStatisticByDate(0, new \DateTime('2024-01-01'));
+
+        // Check the result
+        $this->assertInstanceOf(StatisticResult::class, $result);
+        $this->assertEquals(count($this->history), 1);
+        $this->assertEquals('startDate=2024-01-01', $this->history[0]['request']->getUri()->getQuery());
+
+        $this->assertEquals(2, $result->getNumberOfValidSubmissions());
+        $this->assertEquals(5, $result->getNumberOfSpamSubmissions());
+        $this->assertEquals($numbersByDate, $result->getNumbersByDate());
+    }
+
     public function testGetStatisticByDateReturnsError()
     {
         $this->expectException(Exception::class);
@@ -255,4 +291,13 @@ public function testGetStatisticByDateReturnsError()
 
         $result = $apiClient->getStatisticByDate();
     }
+
+    public function testDeprecatedValidateSubmissionMethod()
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Submit or validation token not available.');
+
+        $apiClient = new Client('http://test.local', 'testPublicKey', 'testPrivateKey', ['handler' => $this->handlerStack]);
+        $result = $apiClient->validateSubmission(['name' => 'John Example']);
+    }
 }