ParticipantService - getParticipant() & hasParticipantFilledSurvey() methods - returns participant of survey & information if participant has filled survey

src/Exception/MissingParticipantOfSurveyException.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Meritoo\LimeSurvey\ApiClient\Exception;
+
+/**
+ * An exception used when participant of survey is missing
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class MissingParticipantOfSurveyException extends \Exception
+{
+    /**
+     * Class constructor
+     *
+     * @param int    $surveyId ID of survey
+     * @param string $email    E-mail address of the participant
+     */
+    public function __construct($surveyId, $email)
+    {
+        $template = 'Participant with e-mail %s of survey with ID %s is missing. Maybe was not added to the survey?';
+        $message = sprintf($template, $surveyId, $email);
+
+        parent::__construct($message);
+    }
+}

src/Service/ParticipantService.php

@@ -10,6 +10,7 @@ namespace Meritoo\LimeSurvey\ApiClient\Service;
 
 use Meritoo\Common\Collection\Collection;
 use Meritoo\LimeSurvey\ApiClient\Client\Client;
+use Meritoo\LimeSurvey\ApiClient\Exception\MissingParticipantOfSurveyException;
 use Meritoo\LimeSurvey\ApiClient\Result\Collection\Participants;
 use Meritoo\LimeSurvey\ApiClient\Result\Item\Participant;
 use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
@@ -149,4 +150,38 @@ class ParticipantService
 
         return $participantCollection->getFirst();
     }
+
+    /**
+     * Returns participant with given e-mail of given survey
+     *
+     * @param int    $surveyId ID of survey
+     * @param string $email    E-mail address of the participant
+     * @return Participant|null
+     */
+    public function getParticipant($surveyId, $email)
+    {
+        return $this
+            ->allParticipants
+            ->getParticipantOfSurvey($surveyId, $email);
+    }
+
+    /**
+     * Returns information if participant with given e-mail has filled given survey
+     *
+     * @param int    $surveyId ID of survey
+     * @param string $email    E-mail address of the participant
+     * @return bool
+     *
+     * @throws MissingParticipantOfSurveyException
+     */
+    public function hasParticipantFilledSurvey($surveyId, $email)
+    {
+        if ($this->hasParticipant($surveyId, $email)) {
+            return true === $this
+                    ->getParticipant($surveyId, $email)
+                    ->isCompleted();
+        }
+
+        throw new MissingParticipantOfSurveyException($surveyId, $email);
+    }
 }

tests/Exception/MissingParticipantOfSurveyExceptionTest.php

@@ -0,0 +1,57 @@
+<?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 Meritoo\Common\Test\Base\BaseTestCase;
+use Meritoo\Common\Type\OopVisibilityType;
+use Meritoo\LimeSurvey\ApiClient\Exception\MissingParticipantOfSurveyException;
+
+/**
+ * Test case of an exception used when participant of survey is missing
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class MissingParticipantOfSurveyExceptionTest extends BaseTestCase
+{
+    public function testConstructorVisibilityAndArguments()
+    {
+        static::assertConstructorVisibilityAndArguments(MissingParticipantOfSurveyException::class, OopVisibilityType::IS_PUBLIC, 2, 2);
+    }
+
+    /**
+     * @param int    $surveyId        ID of survey
+     * @param string $email           E-mail address of the participant
+     * @param string $expectedMessage Expected exception's message
+     *
+     * @dataProvider provideSurveyIdAndEmail
+     */
+    public function testConstructorMessage($surveyId, $email, $expectedMessage)
+    {
+        $exception = new MissingParticipantOfSurveyException($surveyId, $email);
+        static::assertEquals($expectedMessage, $exception->getMessage());
+    }
+
+    public function provideSurveyIdAndEmail()
+    {
+        $template = 'Participant with e-mail %s of survey with ID %s is missing. Maybe was not added to the survey?';
+
+        yield[
+            1,
+            'lorem@ipsum.com',
+            sprintf($template, 1, 'lorem@ipsum.com'),
+        ];
+
+        yield[
+            1234,
+            'another@email.comm',
+            sprintf($template, 1234, 'another@email.comm'),
+        ];
+    }
+}

tests/Service/ParticipantServiceTest.php

@@ -13,6 +13,7 @@ use Meritoo\Common\Test\Base\BaseTestCase;
 use Meritoo\Common\Type\OopVisibilityType;
 use Meritoo\LimeSurvey\ApiClient\Client\Client;
 use Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration;
+use Meritoo\LimeSurvey\ApiClient\Exception\MissingParticipantOfSurveyException;
 use Meritoo\LimeSurvey\ApiClient\Manager\JsonRpcClientManager;
 use Meritoo\LimeSurvey\ApiClient\Manager\SessionManager;
 use Meritoo\LimeSurvey\ApiClient\Result\Collection\Participants;
@@ -122,6 +123,44 @@ class ParticipantServiceTest extends BaseTestCase
         static::assertInstanceOf(Participant::class, $result);
     }
 
+    public function testGetParticipant()
+    {
+        $rpcClientManager = $this->getJsonRpcClientManager(0);
+        $sessionManager = $this->getSessionManager();
+
+        $this->createServiceWithoutParticipants($rpcClientManager, $sessionManager);
+        $this->createServiceWithParticipants($rpcClientManager, $sessionManager);
+
+        static::assertNull($this->serviceWithoutParticipants->getParticipant(1, 'john@scott.com'));
+        $participant = $this->serviceWithParticipants->getParticipant(1, 'john@scott.com');
+        static::assertInstanceOf(Participant::class, $participant);
+
+        static::assertEquals('John', $participant->getFirstName());
+        static::assertEquals('Scott', $participant->getLastName());
+        static::assertEquals('john@scott.com', $participant->getEmail());
+    }
+
+    public function testHasParticipantFilledSurveyWithException()
+    {
+        $this->expectException(MissingParticipantOfSurveyException::class);
+
+        $rpcClientManager = $this->getJsonRpcClientManager(1);
+        $sessionManager = $this->getSessionManager();
+        $this->createServiceWithoutParticipants($rpcClientManager, $sessionManager);
+
+        $this->serviceWithoutParticipants->hasParticipantFilledSurvey(1, 'john@scott.com');
+    }
+
+    public function testHasParticipantFilledSurvey()
+    {
+        $rpcClientManager = $this->getJsonRpcClientManager(0);
+        $sessionManager = $this->getSessionManager();
+        $this->createServiceWithParticipants($rpcClientManager, $sessionManager);
+
+        static::assertTrue($this->serviceWithParticipants->hasParticipantFilledSurvey(1, 'john@scott.com'));
+        static::assertFalse($this->serviceWithParticipants->hasParticipantFilledSurvey(1, 'mary@jane.com'));
+    }
+
     /**
      * Returns configuration used while connecting to LimeSurvey's API
      *
@@ -191,8 +230,13 @@ class ParticipantServiceTest extends BaseTestCase
                     'firstname' => 'John',
                     'lastname'  => 'Scott',
                     'email'     => 'john@scott.com',
+                    'completed' => 'Y',
+                ]),
+                (new Participant())->setValues([
+                    'firstname' => 'Mary',
+                    'lastname'  => 'Jane',
+                    'email'     => 'mary@jane.com',
                 ]),
-                new Participant(),
             ]),
             2 => new Collection([
                 new Participant(),