ParticipantService - a service that serves participants

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

@@ -0,0 +1,143 @@
+<?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\Common\Collection\Collection;
+use Meritoo\Common\Exception\Method\DisabledMethodException;
+use Meritoo\LimeSurvey\ApiClient\Result\Item\Participant;
+
+/**
+ * Participants of survey.
+ * 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 Participants extends Collection
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function add($element, $index = null)
+    {
+        throw new DisabledMethodException(__METHOD__, 'addParticipants');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function addMultiple($elements, $useIndexes = false)
+    {
+        throw new DisabledMethodException(__METHOD__, 'addParticipants');
+    }
+
+    /**
+     * Adds participants of given survey
+     *
+     * @param Collection $participants Participants to add. Collection of Participant 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 Participant $participant Participant to add
+     * @param int         $surveyId    ID of survey
+     * @return $this
+     */
+    public function addParticipant(Participant $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 Participant|null
+     */
+    public function getParticipantOfSurvey($surveyId, $participantEmail)
+    {
+        /* @var Collection $participants */
+        $participants = $this->getBySurvey($surveyId);
+
+        if ($participants->isEmpty()) {
+            return null;
+        }
+
+        /* @var Participant $participant */
+        foreach ($participants as $participant) {
+            if ($participant->getEmail() == $participantEmail) {
+                return $participant;
+            }
+        }
+
+        return null;
+    }
+}

src/Meritoo/LimeSurvey/ApiClient/Service/ParticipantService.php

@@ -0,0 +1,142 @@
+<?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\Service;
+
+use Meritoo\Common\Collection\Collection;
+use Meritoo\LimeSurvey\ApiClient\Client\Client;
+use Meritoo\LimeSurvey\ApiClient\Result\Collection\Participants;
+use Meritoo\LimeSurvey\ApiClient\Result\Item\Participant;
+use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
+
+/**
+ * Serves participants
+ *
+ * @author    Krzysztof Niziol <krzysztof.niziol@meritoo.pl>
+ * @copyright Meritoo.pl
+ */
+class ParticipantService
+{
+    /**
+     * Client of the LimeSurvey's API
+     *
+     * @var Client
+     */
+    private $client;
+
+    /**
+     * Participants of survey.
+     * All participants grouped per survey.
+     *
+     * @var Participants
+     */
+    private $allParticipants;
+
+    /**
+     * Class constructor
+     *
+     * @param Client       $client          Client of the LimeSurvey's API
+     * @param Participants $allParticipants (optional) Participants of survey. All participants grouped per survey.
+     */
+    public function __construct(Client $client, Participants $allParticipants = null)
+    {
+        if (null === $allParticipants) {
+            $allParticipants = new Participants();
+        }
+
+        $this->client = $client;
+        $this->allParticipants = $allParticipants;
+    }
+
+    /**
+     * Returns participants of given survey
+     *
+     * @param int $surveyId ID of survey
+     * @return Collection
+     */
+    public function getSurveyParticipants($surveyId)
+    {
+        $hasSurvey = $this
+            ->allParticipants
+            ->hasParticipantsOfSurvey($surveyId);
+
+        if (!$hasSurvey) {
+            $arguments = [
+                $surveyId,
+            ];
+
+            $participants = $this
+                ->client
+                ->run(MethodType::LIST_PARTICIPANTS, $arguments)
+                ->getData();
+
+            $this
+                ->allParticipants
+                ->addParticipants($participants, $surveyId);
+        }
+
+        return $this
+            ->allParticipants
+            ->getBySurvey($surveyId);
+    }
+
+    /**
+     * Returns information if given survey has participant with given e-mail
+     *
+     * @param int    $surveyId ID of survey
+     * @param string $email    E-mail address of the participant
+     * @return bool
+     */
+    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);
+    }
+
+    /**
+     * Adds participant with given data to survey with given ID
+     *
+     * @param int    $surveyId  ID of survey
+     * @param string $firstName First name of the participant to add
+     * @param string $lastName  Last ame of the participant to add
+     * @param string $email     E-mail address of the participant to add
+     * @return Participant
+     */
+    public function addParticipant($surveyId, $firstName, $lastName, $email)
+    {
+        $participantsData = [
+            [
+                'firstname' => $firstName,
+                'lastname'  => $lastName,
+                'email'     => $email,
+            ],
+        ];
+
+        $arguments = [
+            $surveyId,
+            $participantsData,
+        ];
+
+        $participantCollection = $this
+            ->client
+            ->run(MethodType::ADD_PARTICIPANTS, $arguments)
+            ->getData();
+
+        $this
+            ->allParticipants
+            ->addParticipants($participantCollection, $surveyId);
+
+        return $participantCollection->getFirst();
+    }
+}