init

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present sms77 e.K.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,77 @@
+![](https://www.sms77.io/wp-content/uploads/2019/07/sms77-Logo-400x79.png)
+
+# Plugin for LimeSurvey
+This plugin adds the possibility to send SMS for survey invitations and reminders.
+
+## Prerequisites
+- Limesurvey CE - only tested with version 5.x
+- An API Key from [sms77](https://www.sms77.io)
+
+## Installation
+
+1. Download the [latest release](https://github.com/sms77io/LimeSurvey/releases/latest/download/sms77-limesurvey-latest.zip)
+2. Extract the archive to `/path/to/limesurvey/plugins`
+3. Login to the administration, go to `Configuration -> Plugins` and activate the plugin
+4. Click on `sms77`, go to `Settings`, configure it to your needs and click `Save`
+
+## Usage
+
+### Send SMS invitation to survey participants
+1. Create a survey and set it to closed-access mode.
+2. Add a participant to the survey.
+3. Go to `Survey participants`, click `Manage attributes` and add a field for the mobile phone number.
+4. Click the pencil icon in the participant entry row and set a mobile phone in the `Additional attributes` tab.
+5. Go to `Simple plugins -> sms77`.
+6. Make sure that the attribute field matches the name of the mobile phone field which you just created.
+7. Make sure that the event type `Invitation` is added.
+8. Go to `Survey participants` and click `Generate tokens`.
+9. Click `Invitations & reminders` and choose or `Send email invitation` from the dropdown.
+10. Edit the form and click `Send invitations`.
+
+### Send SMS reminder to survey participants
+The procedure for sending SMS reminders is pretty much the same as for invitations.
+You just need to tweak these two steps:
+For step 7 make sure that the event type `Reminder` is added.
+For step 9 choose `Send email reminder` instead.
+
+
+## Configuration Options
+
+### API Key
+An API key from sms77 required for sending - create one in your [developer dashboard](https://app.sms77.io/developer)
+
+### Attribute Field
+Defines the attribute field where the mobile phone number is stored
+
+### Send Email
+If enabled, both SMS and email gets sent
+
+### Event Types
+Defines on which event type(s) the plugin is activated.
+Multiple entries are allowed.
+The following events are implemented:
+- Invitation
+- Reminder
+
+### Flash
+Depending on the phone, flash SMS get displayed directly in the display and won't get saved
+
+### SMS Text
+Define the SMS text to be sent. 
+You can make use of the following placeholders which get replaced with its corresponding value or an empty string:
+
+{EMAIL} => the participant's email address
+
+{FIRSTNAME} => the participant's first name
+
+{LASTNAME} => the participant's last name
+
+{SURVEY_URL} => the survey URL
+
+
+
+## Support
+
+Need help? Feel free to [contact us](https://www.sms77.io/en/company/contact/).
+
+[![MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)

config.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<config>
+    <metadata>
+        <name>sms77</name>
+        <type>plugin</type>
+        <creationDate>2021-12-16</creationDate>
+        <lastUpdate>2021-12-16</lastUpdate>
+        <author>sms77 e.K.</author>
+        <authorUrl>https://www.sms77.io/</authorUrl>
+        <authorEmail>[email protected]</authorEmail>
+        <supportUrl>https://www.sms77.io/</supportUrl>
+        <version>1.0.0</version>
+        <license>MIT</license>
+        <description><![CDATA[Send SMS via sms77]]></description>
+    </metadata>
+    <compatibility>
+        <version>5.0</version>
+    </compatibility>
+    <updaters>
+        <updater disabled="disabled">
+            <stable>1</stable>
+            <type>rest</type>
+            <source>https://github.com/sms77io/LimeSurvey</source>
+            <manualUpdateUrl>https://github.com/sms77io/LimeSurvey</manualUpdateUrl>
+        </updater>
+    </updaters>
+</config>

sms77.php

@@ -0,0 +1,232 @@
+<?php
+
+class sms77 extends PluginBase {
+    static protected $description = 'Send SMS via sms77';
+    static protected $name = 'sms77';
+    protected $settings = [
+        'apiKey' => [
+            'help' => 'Get yours @ https://app.sms77.io/developer',
+            'htmlOptions' => ['required' => 'required'],
+            'label' => 'API Key',
+            'type' => 'password',
+        ],
+        'attributeField' => [
+            'default' => 'attribute_1',
+            'help' => 'The attribute field for the mobile phone number',
+            'htmlOptions' => ['required' => 'required'],
+            'label' => 'Attribute Field',
+            'type' => 'string',
+        ],
+        'email' => [
+            'default' => 0,
+            'help' => 'Enabling this setting will send both SMS and email',
+            'label' => 'Send Email',
+            'type' => 'boolean',
+        ],
+        'enabled' => [
+            'default' => [],
+            'help' => 'Defines on which events the SMS plugin should be activated',
+            'htmlOptions' => ['multiple' => 'multiple'],
+            'label' => 'Event Types',
+            'options' => [
+                'invite' => 'Invitation',
+                'remind' => 'Reminder',
+            ],
+            'type' => 'select',
+        ],
+        'flash' => [
+            'default' => 0,
+            'help' => 'Depending on the device, the SMS gets displayed directly in the display and won\'t get saved',
+            'label' => 'Flash',
+            'type' => 'boolean',
+        ],
+        'from' => [
+            'default' => '',
+            'help' => 'Value displayed as the SMS sender',
+            'label' => 'From',
+            'htmlOptions' => ['maxlength' => 16],
+            'type' => 'string',
+        ],
+        'text' => [
+            'default' => 'Dear {FIRSTNAME} {LASTNAME},' . PHP_EOL
+                . 'we invite you to participate in the survey below:' . PHP_EOL
+                . '{SURVEY_URL}' . PHP_EOL
+                . 'Survey Team',
+            'help' => 'You may use the placeholders '
+                . '{EMAIL}, {FIRSTNAME}, {LASTNAME} and {SURVEY_URL}',
+            'htmlOptions' => ['maxlength' => 1520, 'rows' => 7],
+            'label' => 'SMS Text',
+            'type' => 'text',
+        ],
+    ];
+    protected $storage = 'DbStorage';
+
+    /**
+     * @return void
+     */
+    public function init() {
+        $this->subscribe('beforeSurveySettings');
+        $this->subscribe('beforeTokenEmail');
+        $this->subscribe('newSurveySettings');
+    }
+
+    /**
+     * @param string $token
+     * @param string $surveyId
+     * @return string
+     */
+    private function buildSurveyLink($token, $surveyId) {
+        $protocol = 'http';
+        if (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on') $protocol .= 's';
+
+        return $protocol . '://' . $_SERVER['SERVER_NAME']
+            . '/index.php/survey/index/sid/' . $surveyId . '/token/' . $token;
+    }
+
+    /**
+     * @param array $tokenData
+     * @param string $surveyId
+     * @return string
+     */
+    private function buildMessage(array $tokenData, $surveyId) {
+        return str_replace(
+            [
+                '{EMAIL}',
+                '{FIRSTNAME}',
+                '{LASTNAME}',
+                '{SURVEY_URL}',
+            ],
+            [
+                (string)$tokenData['email'],
+                (string)$tokenData['firstname'],
+                (string)$tokenData['lastname'],
+                $this->buildSurveyLink($tokenData['token'], $surveyId),
+            ],
+            $this->get(
+                'text',
+                'Survey',
+                $surveyId,
+                $this->settings['text']['default']
+            )
+        );
+    }
+
+    /**
+     * This function handles sending SMS messages
+     * If it's an email invite, it doesn't interfere and keeps the settings as they are
+     * @return void
+     */
+    public function beforeTokenEmail() {
+        $event = $this->getEvent();
+        if (!$event) return;
+
+        $surveyId = (string)$event->get('survey');
+        $enabled = (array)$this->get('enabled', 'Survey', $surveyId);
+        $emailType = $event->get('type');
+
+        if (!in_array($emailType, $enabled)) return;
+
+        $tokenData = $event->get('token');
+        $attributeField = $this->get('attributeField');
+
+        if (!isset($tokenData[$attributeField])) {
+            echo $this->gT('sms77 plugin is enabled.')
+                . $this->gT('If you do not wish to send SMS invitations, disable it')
+                . $this->gT('If you intend to use it, the SMS was not sent.')
+                . $this->gT('Add an attribute with the phone number or "NA" for emails.');
+            exit;
+        }
+
+        $to = (string)$tokenData[$attributeField];
+
+        if (empty($to) || $to === 'NA') return;
+
+        if (!$this->get('email')) $this->event->set('send', false);
+
+        $text = $this->buildMessage($tokenData, $surveyId);
+
+        if (100 !== $this->sms(compact('text', 'to'))) {
+            echo $this->gT('SMS not sent. Please contact an administrator.');
+            exit;
+        }
+    }
+
+    /**
+     *  This function handles sending the http request.
+     *  Proxy settings should be configured.
+     *  The third argument (request_header) is optional
+     *  returns the response from the external page/API
+     * @param array $payload
+     * @return int
+     */
+    private function sms(array $payload) {
+        $apiKey = $this->get('apiKey');
+
+        if (!$apiKey) {
+            echo $this->gT('Can not send SMS because of missing sms77 API key.');
+            exit;
+        }
+
+        $from = $this->get('from');
+        if (!empty($from)) $payload['from'] = $from;
+
+        $curlHandle = curl_init('https://gateway.sms77.io/api/sms');
+        $options = [
+            CURLOPT_HTTPHEADER => [
+                'Accept: application/json',
+                'Content-type: application/json',
+                'SentWith: LimeSurvey',
+                'X-Api-Key: ' . $apiKey,
+            ],
+            CURLOPT_POSTFIELDS => json_encode($payload),
+            CURLOPT_RETURNTRANSFER => true,
+        ];
+
+        curl_setopt_array($curlHandle, $options);
+
+        $response = curl_exec($curlHandle);
+
+        curl_close($curlHandle);
+
+        return (int)(is_bool($response) ? $response : json_decode($response)->success);
+    }
+
+    /**
+     * This event is fired by the administration panel to gather extra settings
+     * available for a survey. These settings override the global settings.
+     * The plugin should return setting meta data.
+     * @return void
+     */
+    public function beforeSurveySettings() {
+        $settings = $this->settings;
+        $surveyId = $this->event->get('survey');
+
+        unset($settings['enabled']['help']);
+
+        foreach (['attributeField', 'email', 'enabled', 'flash', 'from', 'text'] as $key)
+            $settings[$key]['current'] = $this->get(
+                $key,
+                'Survey',
+                $surveyId,
+                $this->get($key, null, null, $settings[$key]['default'])
+            );
+
+        $this->event->set('surveysettings.' . $this->id, [
+            'name' => get_class($this),
+            'settings' => $settings,
+        ]);
+    }
+
+    /**
+     * This event is fired when survey settings is saved.
+     * @return void
+     */
+    public function newSurveySettings() {
+        foreach ($this->event->get('settings') as $k => $v) {
+            if (!isset($v) && isset($this->settings[$k]['default']))
+                $v = $this->settings[$k]['default'];
+
+            $this->set($k, $v, 'Survey', $this->event->get('survey'));
+        }
+    }
+}