Result - store status provided by the LimeSurvey's API (instead of raw data) & do not process the data (because it's unknown)

src/Meritoo/LimeSurvey/ApiClient/Exception/CannotProcessDataException.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\LimeSurvey\ApiClient\Exception;
+
+/**
+ * An exception used while raw data returned by the LimeSurvey's API cannot be processed
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class CannotProcessDataException extends \Exception
+{
+    /**
+     * Class constructor
+     *
+     * @param string $reason Reason why data cannot be processed, e.g. "Invalid user name or password"
+     */
+    public function __construct($reason)
+    {
+        $template = 'Raw data returned by the LimeSurvey\'s API cannot be processed. Reason: \'%s\'.';
+        $message = sprintf($template, $reason);
+
+        parent::__construct($message);
+    }
+}

src/Meritoo/LimeSurvey/ApiClient/Result/Result.php

@@ -10,6 +10,7 @@ namespace Meritoo\LimeSurvey\ApiClient\Result;
 
 use Meritoo\Common\Collection\Collection;
 use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
+use Meritoo\LimeSurvey\ApiClient\Exception\CannotProcessDataException;
 use Meritoo\LimeSurvey\ApiClient\Result\Processor\ResultProcessor;
 use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
 
@@ -35,6 +36,13 @@ class Result
      */
     private $rawData;
 
+    /**
+     * Status, information returned instead of usual/normal result
+     *
+     * @var string
+     */
+    private $status;
+
     /**
      * Processor of the raw data fetched while talking to the LimeSurvey's API
      *
@@ -52,7 +60,7 @@ class Result
     public function __construct($method, array $rawData)
     {
         $this->method = MethodType::getValidatedMethod($method);
-        $this->rawData = $rawData;
+        $this->setRawDataAndStatus($rawData);
     }
 
     /**
@@ -71,16 +79,43 @@ class Result
      * @param bool $raw (optional) If is set to true, raw data provided by the LimeSurvey's API will be returned.
      *                  Otherwise - prepared/processed.
      * @return array|Collection|BaseItem
+     * @throws CannotProcessDataException
      */
     public function getData($raw = false)
     {
+        /*
+         * Raw data should be returned only?
+         * Let's do it
+         */
         if ($raw) {
             return $this->rawData;
         }
 
+        /*
+         * Status is unknown?
+         * Let's process the raw data
+         */
+        if (empty($this->status)) {
             return $this->getProcessedData($this->rawData);
         }
 
+        /*
+         * Oops, the raw data returned by the LimeSurvey's API cannot be processed, because status was provided.
+         * Well, probably something is broken and... there is no data.
+         */
+        throw new CannotProcessDataException($this->status);
+    }
+
+    /**
+     * Returns status, information returned instead of usual/normal result
+     *
+     * @return string
+     */
+    public function getStatus()
+    {
+        return $this->status;
+    }
+
     /**
      * Returns processed data based on the raw data returned by the LimeSurvey's API
      *
@@ -119,4 +154,23 @@ class Result
 
         return $this->resultProcessor;
     }
+
+    /**
+     * Sets status, information returned instead of usual/normal result and raw data returned by the LimeSurvey's API
+     *
+     * @param array $rawData Raw data returned by the LimeSurvey's API
+     */
+    private function setRawDataAndStatus(array $rawData)
+    {
+        /*
+         * Status was provided?
+         * Well, probably something is broken and... there is no data
+         */
+        if (isset($rawData['status'])) {
+            $this->status = trim($rawData['status']);
+            $rawData = [];
+        }
+
+        $this->rawData = $rawData;
+    }
 }

tests/Meritoo/LimeSurvey/Test/ApiClient/Exception/CannotProcessDataExceptionTest.php

@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\LimeSurvey\Test\ApiClient\Exception;
+
+use Generator;
+use Meritoo\Common\Test\Base\BaseTestCase;
+use Meritoo\Common\Type\OopVisibilityType;
+use Meritoo\LimeSurvey\ApiClient\Exception\CannotProcessDataException;
+
+/**
+ * Test case of an exception used while raw data returned by the LimeSurvey's API cannot be processed
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class CannotProcessDataExceptionTest extends BaseTestCase
+{
+    public function testConstructorVisibilityAndArguments()
+    {
+        static::assertConstructorVisibilityAndArguments(CannotProcessDataException::class, OopVisibilityType::IS_PUBLIC, 1, 1);
+    }
+
+    /**
+     * @param string $reason          Reason why data cannot be processed, e.g. "Invalid user name or password"
+     * @param string $expectedMessage Expected exception's message
+     *
+     * @dataProvider provideReason
+     */
+    public function testConstructorMessage($reason, $expectedMessage)
+    {
+        $exception = new CannotProcessDataException($reason);
+        static::assertEquals($expectedMessage, $exception->getMessage());
+    }
+
+    /**
+     * Provides reason why data cannot be processed
+     *
+     * @return Generator
+     */
+    public function provideReason()
+    {
+        $template = 'Raw data returned by the LimeSurvey\'s API cannot be processed. Reason: \'%s\'.';
+
+        yield[
+            'unknown',
+            sprintf($template, 'unknown'),
+        ];
+
+        yield[
+            'Invalid user name or password',
+            sprintf($template, 'Invalid user name or password'),
+        ];
+    }
+}

tests/Meritoo/LimeSurvey/Test/ApiClient/Result/ResultTest.php

@@ -12,6 +12,7 @@ use DateTime;
 use Meritoo\Common\Test\Base\BaseTestCase;
 use Meritoo\Common\Type\OopVisibilityType;
 use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
+use Meritoo\LimeSurvey\ApiClient\Exception\CannotProcessDataException;
 use Meritoo\LimeSurvey\ApiClient\Result\Result;
 use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
 use PHPUnit_Framework_MockObject_MockObject;
@@ -45,6 +46,14 @@ class ResultTest extends BaseTestCase
      */
     private $notIterableData;
 
+    /**
+     * Status provided instead of real data.
+     * An array with one key: "status".
+     *
+     * @var array
+     */
+    private $statusInsteadData;
+
     /**
      * Result with empty data returned by the LimeSurvey's API.
      * Mock of the tested class.
@@ -69,6 +78,13 @@ class ResultTest extends BaseTestCase
      */
     private $notIterableDataResult;
 
+    /**
+     * Result with status provided instead of real data
+     *
+     * @var Result
+     */
+    private $statusInsteadDataResult;
+
     public function testConstructorVisibilityAndArguments()
     {
         static::assertConstructorVisibilityAndArguments(Result::class, OopVisibilityType::IS_PUBLIC, 2, 2);
@@ -110,6 +126,12 @@ class ResultTest extends BaseTestCase
         static::assertEquals($this->iterableData, $iterableData);
     }
 
+    public function testGetDataUsingProcessedDataWhoCannotBeProcessed()
+    {
+        $this->expectException(CannotProcessDataException::class);
+        $this->statusInsteadDataResult->getData();
+    }
+
     public function testGetProcessedDataVisibilityAndArguments()
     {
         static::assertMethodVisibilityAndArguments(Result::class, 'getProcessedData', OopVisibilityType::IS_PRIVATE, 1, 1);
@@ -120,6 +142,20 @@ class ResultTest extends BaseTestCase
         static::assertMethodVisibilityAndArguments(Result::class, 'getResultProcessor', OopVisibilityType::IS_PRIVATE);
     }
 
+    public function testGetStatusWhenIsNotProvided()
+    {
+        $result = new Result(MethodType::ADD_PARTICIPANTS, []);
+
+        static::assertEquals(null, $result->getStatus());
+        static::assertEquals([], $result->getData(true));
+    }
+
+    public function testGetStatusWhenIsProvided()
+    {
+        static::assertEquals($this->statusInsteadData['status'], $this->statusInsteadDataResult->getStatus());
+        static::assertEquals([], $this->statusInsteadDataResult->getData(true));
+    }
+
     /**
      * {@inheritdoc{
      */
@@ -149,6 +185,10 @@ class ResultTest extends BaseTestCase
             ],
         ];
 
+        $this->statusInsteadData = [
+            'status' => 'Invalid data',
+        ];
+
         $emptyData = [
             MethodType::LIST_SURVEYS,
             $this->emptyData,
@@ -167,6 +207,7 @@ class ResultTest extends BaseTestCase
         $this->emptyDataResult = $this->getResultMock($emptyData);
         $this->iterableDataResult = $this->getResultMock($iterableData);
         $this->notIterableDataResult = $this->getResultMock($notIterableData);
+        $this->statusInsteadDataResult = new Result(MethodType::LIST_PARTICIPANTS, $this->statusInsteadData);
     }
 
     /**