Do not fetch all participants of given survey to get information if participant has filled the survey

src/Base/Result/BaseParticipant.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Meritoo\LimeSurvey\ApiClient\Base\Result;
+
+/**
+ * Base class for participant of survey.
+ * Used as a foundation for short or full participant's data.
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+abstract class BaseParticipant extends BaseItem
+{
+    /**
+     * ID of the participant
+     *
+     * @var int
+     */
+    protected $id;
+
+    /**
+     * First name of the participant
+     *
+     * @var string
+     */
+    protected $firstName;
+
+    /**
+     * Last name of the participant
+     *
+     * @var string
+     */
+    protected $lastName;
+
+    /**
+     * E-mail of the participant
+     *
+     * @var string
+     */
+    protected $email;
+
+    /**
+     * Returns ID of the participant
+     *
+     * @return int
+     */
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    /**
+     * Returns first name of the participant
+     *
+     * @return string
+     */
+    public function getFirstName()
+    {
+        return $this->firstName;
+    }
+
+    /**
+     * Returns last name of the participant
+     *
+     * @return string
+     */
+    public function getLastName()
+    {
+        return $this->lastName;
+    }
+
+    /**
+     * Returns e-mail of the participant
+     *
+     * @return string
+     */
+    public function getEmail()
+    {
+        return $this->email;
+    }
+}

src/Base/Result/BaseParticipantsCollection.php

@@ -0,0 +1,142 @@
+<?php
+
+namespace Meritoo\LimeSurvey\ApiClient\Base\Result;
+
+use Meritoo\Common\Collection\Collection;
+use Meritoo\Common\Exception\Method\DisabledMethodException;
+
+/**
+ * Base class for participants' collection
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+abstract class BaseParticipantsCollection extends Collection
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function add($element, $index = null)
+    {
+        throw new DisabledMethodException(__METHOD__, 'addParticipant');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function addMultiple($elements, $useIndexes = false)
+    {
+        throw new DisabledMethodException(__METHOD__, 'addParticipants');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function has($element)
+    {
+        throw new DisabledMethodException(__METHOD__, 'hasParticipantsOfSurvey');
+    }
+
+    /**
+     * Adds participants of given survey
+     *
+     * @param Collection $participants Participants to add. Collection of ParticipantShort or Participant instances.
+     * @param int        $surveyId     ID of survey
+     * @return $this
+     */
+    public function addParticipants(Collection $participants, $surveyId)
+    {
+        /*
+         * No participants?
+         * Nothing to do
+         */
+        if ($participants->isEmpty()) {
+            return $this;
+        }
+
+        $this
+            ->getBySurvey($surveyId)
+            ->addMultiple($participants);
+
+        return $this;
+    }
+
+    /**
+     * Returns participants of given survey
+     *
+     * If there are no participants of given survey, adds an empty collection who will store participants.
+     * So, this method will return collection always.
+     *
+     * @param int $surveyId ID of survey
+     * @return Collection
+     */
+    public function getBySurvey($surveyId)
+    {
+        /*
+         * There are no participants of given survey?
+         * Let's add an empty collection who will store participants
+         */
+        if (!isset($this[$surveyId])) {
+            $this[$surveyId] = new Collection();
+        }
+
+        return $this[$surveyId];
+    }
+
+    /**
+     * Returns information if there are participants of given survey
+     *
+     * @param int $surveyId ID of survey
+     * @return bool
+     */
+    public function hasParticipantsOfSurvey($surveyId)
+    {
+        return false === $this
+                ->getBySurvey($surveyId)
+                ->isEmpty();
+    }
+
+    /**
+     * Adds participant of given survey
+     *
+     * @param BaseParticipant $participant Participant to add
+     * @param int             $surveyId    ID of survey
+     * @return $this
+     */
+    public function addParticipant(BaseParticipant $participant, $surveyId)
+    {
+        $this
+            ->getBySurvey($surveyId)
+            ->add($participant);
+
+        return $this;
+    }
+
+    /**
+     * Returns participant of given survey
+     *
+     * @param int    $surveyId         ID of survey
+     * @param string $participantEmail E-mail of searched participant
+     * @return BaseParticipant|null
+     */
+    public function getParticipantOfSurvey($surveyId, $participantEmail)
+    {
+        $participants = $this->getBySurvey($surveyId);
+
+        /*
+         * No participants?
+         * Nothing to do
+         */
+        if ($participants->isEmpty()) {
+            return null;
+        }
+
+        foreach ($participants as $participant) {
+            if ($participant->getEmail() == $participantEmail) {
+                return $participant;
+            }
+        }
+
+        return null;
+    }
+}

src/Result/Collection/Participants.php

@@ -8,9 +8,7 @@
 
 namespace Meritoo\LimeSurvey\ApiClient\Result\Collection;
 
-use Meritoo\Common\Collection\Collection;
-use Meritoo\Common\Exception\Method\DisabledMethodException;
-use Meritoo\LimeSurvey\ApiClient\Result\Item\ParticipantShort;
+use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseParticipantsCollection;
 
 /**
  * Collection of participants' short data.
@@ -22,130 +20,6 @@ use Meritoo\LimeSurvey\ApiClient\Result\Item\ParticipantShort;
  * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
  * @copyright Meritoo.pl
  */
-class Participants extends Collection
+class Participants extends BaseParticipantsCollection
 {
-    /**
-     * {@inheritdoc}
-     */
-    public function add($element, $index = null)
-    {
-        throw new DisabledMethodException(__METHOD__, 'addParticipants');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function addMultiple($elements, $useIndexes = false)
-    {
-        throw new DisabledMethodException(__METHOD__, 'addParticipants');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function has($element)
-    {
-        throw new DisabledMethodException(__METHOD__, 'hasParticipantsOfSurvey');
-    }
-
-    /**
-     * Adds participants of given survey
-     *
-     * @param Collection $participants Participants to add. Collection of ParticipantShort classes.
-     * @param int        $surveyId     ID of survey
-     * @return $this
-     */
-    public function addParticipants(Collection $participants, $surveyId)
-    {
-        /*
-         * No participants?
-         * Nothing to do
-         */
-        if ($participants->isEmpty()) {
-            return $this;
-        }
-
-        $this
-            ->getBySurvey($surveyId)
-            ->addMultiple($participants);
-
-        return $this;
-    }
-
-    /**
-     * Adds participant of given survey
-     *
-     * @param ParticipantShort $participant Participant to add
-     * @param int              $surveyId    ID of survey
-     * @return $this
-     */
-    public function addParticipant(ParticipantShort $participant, $surveyId)
-    {
-        $this
-            ->getBySurvey($surveyId)
-            ->add($participant);
-
-        return $this;
-    }
-
-    /**
-     * Returns information if there are participants of given survey
-     *
-     * @param int $surveyId ID of survey
-     * @return bool
-     */
-    public function hasParticipantsOfSurvey($surveyId)
-    {
-        return false === $this
-                ->getBySurvey($surveyId)
-                ->isEmpty();
-    }
-
-    /**
-     * Returns participants of given survey
-     *
-     * If there are no participants of given survey, adds an empty collection who will store participants.
-     * So, this method will return collection always.
-     *
-     * @param int $surveyId ID of survey
-     * @return Collection
-     */
-    public function getBySurvey($surveyId)
-    {
-        /*
-         * There are no participants of given survey?
-         * Let's add an empty collection who will store participants
-         */
-        if (!isset($this[$surveyId])) {
-            $this[$surveyId] = new Collection();
-        }
-
-        return $this[$surveyId];
-    }
-
-    /**
-     * Returns participant of given survey
-     *
-     * @param int    $surveyId         ID of survey
-     * @param string $participantEmail E-mail of searched participant
-     * @return ParticipantShort|null
-     */
-    public function getParticipantOfSurvey($surveyId, $participantEmail)
-    {
-        /* @var Collection $participants */
-        $participants = $this->getBySurvey($surveyId);
-
-        if ($participants->isEmpty()) {
-            return null;
-        }
-
-        /* @var ParticipantShort $participant */
-        foreach ($participants as $participant) {
-            if ($participant->getEmail() == $participantEmail) {
-                return $participant;
-            }
-        }
-
-        return null;
-    }
 }

src/Result/Collection/ParticipantsDetails.php

@@ -0,0 +1,36 @@
+<?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\Result\Collection;
+
+use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseParticipantsCollection;
+
+/**
+ * Collection of participants' full data.
+ * All participants grouped per survey.
+ *
+ * It's a collection of participants' collections.
+ * The survey ID is used as an index per each collection of participants, so they are grouped by survey.
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class ParticipantsDetails extends BaseParticipantsCollection
+{
+    /**
+     * Returns information if survey with given ID has participant with given e-mail address
+     *
+     * @param int    $surveyId         ID of survey
+     * @param string $participantEmail E-mail of searched participant
+     * @return bool
+     */
+    public function hasParticipantOfSurvey($surveyId, $participantEmail)
+    {
+        return null !== $this->getParticipantOfSurvey($surveyId, $participantEmail);
+    }
+}

src/Result/Item/Participant.php

@@ -10,7 +10,7 @@ namespace Meritoo\LimeSurvey\ApiClient\Result\Item;
 
 use DateTime;
 use Meritoo\Common\Utilities\Date;
-use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
+use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseParticipant;
 
 /**
  * One item of the result/data: full data of one participant
@@ -18,15 +18,8 @@ use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
  * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
  * @copyright Meritoo.pl
  */
-class Participant extends BaseItem
+class Participant extends BaseParticipant
 {
-    /**
-     * ID of the participant
-     *
-     * @var int
-     */
-    private $id;
-
     /**
      * Another ID of the participant?
      * Don't know where it is used.
@@ -42,27 +35,6 @@ class Participant extends BaseItem
      */
     private $mpId;
 
-    /**
-     * First name of the participant
-     *
-     * @var string
-     */
-    private $firstName;
-
-    /**
-     * Last name of the participant
-     *
-     * @var string
-     */
-    private $lastName;
-
-    /**
-     * E-mail of the participant
-     *
-     * @var string
-     */
-    private $email;
-
     /**
      * Status of the e-mail
      *
@@ -229,16 +201,6 @@ class Participant extends BaseItem
         }
     }
 
-    /**
-     * Returns ID of the participant
-     *
-     * @return int
-     */
-    public function getId()
-    {
-        return $this->id;
-    }
-
     /**
      * Returns another ID of the participant?
      * Don't know where it is used.
@@ -260,36 +222,6 @@ class Participant extends BaseItem
         return $this->mpId;
     }
 
-    /**
-     * Returns first name of the participant
-     *
-     * @return string
-     */
-    public function getFirstName()
-    {
-        return $this->firstName;
-    }
-
-    /**
-     * Returns last name of the participant
-     *
-     * @return string
-     */
-    public function getLastName()
-    {
-        return $this->lastName;
-    }
-
-    /**
-     * Returns e-mail of the participant
-     *
-     * @return string
-     */
-    public function getEmail()
-    {
-        return $this->email;
-    }
-
     /**
      * Returns status of the e-mail
      *

src/Result/Item/ParticipantShort.php

@@ -8,7 +8,7 @@
 
 namespace Meritoo\LimeSurvey\ApiClient\Result\Item;
 
-use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
+use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseParticipant;
 
 /**
  * One item of the result/data: short data of one participant
@@ -16,36 +16,8 @@ use Meritoo\LimeSurvey\ApiClient\Base\Result\BaseItem;
  * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
  * @copyright Meritoo.pl
  */
-class ParticipantShort extends BaseItem
+class ParticipantShort extends BaseParticipant
 {
-    /**
-     * ID of the participant
-     *
-     * @var int
-     */
-    private $id;
-
-    /**
-     * First name of the participant
-     *
-     * @var string
-     */
-    private $firstName;
-
-    /**
-     * Last name of the participant
-     *
-     * @var string
-     */
-    private $lastName;
-
-    /**
-     * E-mail of the participant
-     *
-     * @var string
-     */
-    private $email;
-
     /**
      * {@inheritdoc}
      */
@@ -64,46 +36,6 @@ class ParticipantShort extends BaseItem
         }
     }
 
-    /**
-     * Returns ID of the participant
-     *
-     * @return int
-     */
-    public function getId()
-    {
-        return $this->id;
-    }
-
-    /**
-     * Returns first name of the participant
-     *
-     * @return string
-     */
-    public function getFirstName()
-    {
-        return $this->firstName;
-    }
-
-    /**
-     * Returns last name of the participant
-     *
-     * @return string
-     */
-    public function getLastName()
-    {
-        return $this->lastName;
-    }
-
-    /**
-     * Returns e-mail of the participant
-     *
-     * @return string
-     */
-    public function getEmail()
-    {
-        return $this->email;
-    }
-
     /**
      * Returns short data of participant created from full data of participant
      *

src/Service/ParticipantService.php

@@ -13,6 +13,7 @@ use Meritoo\LimeSurvey\ApiClient\Client\Client;
 use Meritoo\LimeSurvey\ApiClient\Exception\CannotProcessDataException;
 use Meritoo\LimeSurvey\ApiClient\Exception\MissingParticipantOfSurveyException;
 use Meritoo\LimeSurvey\ApiClient\Result\Collection\Participants;
+use Meritoo\LimeSurvey\ApiClient\Result\Collection\ParticipantsDetails;
 use Meritoo\LimeSurvey\ApiClient\Result\Item\Participant;
 use Meritoo\LimeSurvey\ApiClient\Result\Item\ParticipantShort;
 use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
@@ -41,21 +42,39 @@ class ParticipantService
      */
     private $allParticipants;
 
+    /**
+     * Collection of participants' full data.
+     * All participants grouped per survey.
+     *
+     * @var Participants
+     */
+    private $participantsDetails;
+
     /**
      * Class constructor
      *
-     * @param Client       $client          Client of the LimeSurvey's API
-     * @param Participants $allParticipants (optional) Collection of participants' short data. All participants
-     *                                      grouped per survey.
+     * @param Client              $client               Client of the LimeSurvey's API
+     * @param Participants        $allParticipants      (optional) Collection of participants' short data. All participants
+     *                                                  grouped per survey.
+     * @param ParticipantsDetails $participantsDetails  (optional) Collection of participants' full data. All
+     *                                                  participants grouped per survey.
      */
-    public function __construct(Client $client, Participants $allParticipants = null)
-    {
+    public function __construct(
+        Client $client,
+        Participants $allParticipants = null,
+        ParticipantsDetails $participantsDetails = null
+    ) {
         if (null === $allParticipants) {
             $allParticipants = new Participants();
         }
 
+        if (null === $participantsDetails) {
+            $participantsDetails = new ParticipantsDetails();
+        }
+
         $this->client = $client;
         $this->allParticipants = $allParticipants;
+        $this->participantsDetails = $participantsDetails;
     }
 
     /**
@@ -93,13 +112,10 @@ class ParticipantService
                     ->run(MethodType::LIST_PARTICIPANTS, $arguments)
                     ->getData();
             } catch (CannotProcessDataException $exception) {
-                $reason = $exception->getReason();
-
                 /*
-                 * Reason of the exception is different than "Oops, there is no participants. Everything else is fine."?
-                 * Let's throw the exception
+                 * Oops, something is broken, because the reason is different than "there are no participants"
                  */
-                if (ReasonType::NO_PARTICIPANTS_FOUND !== $reason) {
+                if (ReasonType::NO_PARTICIPANTS_FOUND !== $exception->getReason()) {
                     throw $exception;
                 }
 
@@ -125,14 +141,7 @@ class ParticipantService
      */
     public function hasParticipant($surveyId, $email)
     {
-        /*
-         * I have to get all participants of survey to avoid problem when participants exist but are not loaded
-         */
-        $this->getSurveyParticipants($surveyId);
-
-        return null !== $this
-                ->allParticipants
-                ->getParticipantOfSurvey($surveyId, $email);
+        return null !== $this->getParticipantDetails($surveyId, $email);
     }
 
     /**
@@ -192,9 +201,12 @@ class ParticipantService
          */
         $this->getSurveyParticipants($surveyId);
 
-        return $this
+        $participant = $this
             ->allParticipants
             ->getParticipantOfSurvey($surveyId, $email);
+
+        /* @var ParticipantShort $participant */
+        return $participant;
     }
 
     /**
@@ -203,22 +215,45 @@ class ParticipantService
      * @param int    $surveyId ID of survey
      * @param string $email    E-mail address of the participant
      * @return Participant|null
+     *
+     * @throws CannotProcessDataException
      */
     public function getParticipantDetails($surveyId, $email)
     {
-        $arguments = [
-            $surveyId,
-            [
-                'email' => $email,
-            ],
-        ];
+        if (!$this->participantsDetails->hasParticipantOfSurvey($surveyId, $email)) {
+            $participant = null;
+
+            $arguments = [
+                $surveyId,
+                [
+                    'email' => $email,
+                ],
+            ];
+
+            try {
+                /* @var Participant $participant */
+                $participant = $this
+                    ->client
+                    ->run(MethodType::GET_PARTICIPANT_PROPERTIES, $arguments)
+                    ->getData();
+            } catch (CannotProcessDataException $exception) {
+                /*
+                 * Oops, something is broken, because the reason is different than "participant was not found"
+                 */
+                if (ReasonType::NO_PARTICIPANT_PROPERTIES !== $exception->getReason()) {
+                    throw $exception;
+                }
+            }
+
+            if (null !== $participant) {
+                $this->participantsDetails->addParticipant($participant, $surveyId);
+            }
+        }
 
         $participant = $this
-            ->client
-            ->run(MethodType::GET_PARTICIPANT_PROPERTIES, $arguments)
-            ->getData();
+            ->participantsDetails
+            ->getParticipantOfSurvey($surveyId, $email);
 
-        /* @var Participant $participant */
         return $participant;
     }
 
@@ -234,20 +269,9 @@ class ParticipantService
     public function hasParticipantFilledSurvey($surveyId, $email)
     {
         if ($this->hasParticipant($surveyId, $email)) {
-            $arguments = [
-                $surveyId,
-                [
-                    'email' => $email,
-                ],
-            ];
-
-            /* @var Participant $participant */
-            $participant = $this
-                ->client
-                ->run(MethodType::GET_PARTICIPANT_PROPERTIES, $arguments)
-                ->getData();
-
-            return true === $participant->isCompleted();
+            return true === $this
+                    ->getParticipantDetails($surveyId, $email)
+                    ->isCompleted();
         }
 
         throw new MissingParticipantOfSurveyException($surveyId, $email);

src/Type/ReasonType.php

@@ -26,6 +26,13 @@ class ReasonType extends BaseType
      */
     const NO_PARTICIPANTS_FOUND = 'No survey participants found.';
 
+    /**
+     * Reason of exception when there is no participant's properties/details
+     *
+     * @var string
+     */
+    const NO_PARTICIPANT_PROPERTIES = 'Error: No results were found based on your attributes.';
+
     /**
      * Reason of exception when there is no surveys
      *