Change directory structure and follow code convention - refs #7225

plugin/clockworksms/config.php

@@ -1,11 +1,15 @@
 <?php
-/* For licensing terms, see /license.txt */
+/* For licensing terms, see /vendor/license.txt */
-
-/* bbb parameters that will be registered in the course settings */
 
+/**
+ * Clockwork parameters that will be registered in the current settings
+ *
+ * @package chamilo.plugin.clockworksms
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
+ */
 require_once __DIR__ . '/../../main/inc/global.inc.php';
 require_once api_get_path(LIBRARY_PATH).'plugin.class.php';
 
 require_once 'lib/clockworksms.lib.php';
-require_once 'lib/clockworksms_api.php';
+require_once 'vendor/clockworksms_api.php';
 require_once 'lib/clockworksms_plugin.class.php';

plugin/clockworksms/index.php

@@ -1,3 +1 @@
 <?php
-
-?>

plugin/clockworksms/install.php

@@ -1,12 +1,15 @@
 <?php
+/* For licensing terms, see /vendor/license.txt */
+
 /**
  * This script is included by main/admin/settings.lib.php and generally
  * includes things to execute in the main database (settings_current table)
- * @package chamilo.plugin.bigbluebutton
+ *
+ * @package chamilo.plugin.clockworksms
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
  */
 /**
  * Initialization
  */
-
 require_once dirname(__FILE__).'/config.php';
 ClockworksmsPlugin::create()->install();

plugin/clockworksms/lib/clockworksms.lib.php

@@ -1,11 +1,12 @@
 <?php
-/* For licensing terms, see /license.txt */
+/* For licensing terms, see /vendor/license.txt */
 
 /**
- * Class clockworksms
+ * Class Clockworksms
- * This script initiates a video conference session, calling the Clockworksms
+ * This script handles incoming SMS information, process it and sends an SMS if everything is right
- * API
+ * 
- * @package chamilo.plugin.clockworksms
+ * @package chamilo.plugin.clockworksms.lib
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
  *
  * Clockworksms-Chamilo connector class
  */
@@ -18,20 +19,21 @@ class Clockworksms
 
     /**
      * Constructor (generates a connection to the API)
-     * @param string $apiKey
+     * @param   string  Clockworksms API key required to use the plugin
+     * @return  void
      */
     public function __construct($apiKey = null)
     {
         $plugin = ClockworksmsPlugin::create();
-        $clockworksms_plugin = $plugin->get('tool_enable');
+        $clockWorkSMSPlugin = $plugin->get('tool_enable');
         if (empty($apiKey)) {
-            $clockworksmsApiKey = $plugin->get('api_key');
+            $clockWorkSMSApiKey = $plugin->get('api_key');
         } else {
-            $clockworksmsApiKey = $apiKey;
+            $clockWorkSMSApiKey = $apiKey;
         }
         $this->table = Database::get_main_table('user_field_values');
-        if ($clockworksms_plugin == true) {
+        if ($clockWorkSMSPlugin == true) {
-            $this->apiKey = $clockworksmsApiKey;
+            $this->apiKey = $clockWorkSMSApiKey;
             // Setting Clockworksms api
             define('CONFIG_SECURITY_API_KEY', $this->apiKey);
             $trimmedApiKey = trim(CONFIG_SECURITY_API_KEY);
@@ -56,15 +58,36 @@ class Clockworksms
         }
     }
 
+    /**
+     * getMobilePhoneNumberById (retrieves a user mobile phone number by user id)
+     * @param   int User id
+     * @return  int User's mobile phone number
+     */
     private function getMobilePhoneNumberById($userId)
     {
         require_once api_get_path(LIBRARY_PATH).'extra_field.lib.php';
-        $mobilePhoneNumberExtraField = (new ExtraField('user'))->get_handler_field_info_by_field_variable('mobile_phone_number');
+        $mobilePhoneNumberExtraField = 
+        (new ExtraField('user'))->get_handler_field_info_by_field_variable('mobile_phone_number');
+        
         require_once api_get_path(LIBRARY_PATH).'extra_field_value.lib.php';
-        $mobilePhoneNumberExtraFieldValue = (new ExtraFieldValue('user'))->get_values_by_handler_and_field_id($userId, $mobilePhoneNumberExtraField['id']);
+        $mobilePhoneNumberExtraFieldValue = 
+        (new ExtraFieldValue('user'))->get_values_by_handler_and_field_id($userId, $mobilePhoneNumberExtraField['id']);
+        
         return $mobilePhoneNumberExtraFieldValue['field_value'];
     }
 
+    /**
+     * send (sends an SMS to the user)
+     * @param   array   Data needed to send the SMS. It is mandatory to include the
+     *                  'smsType' and 'userId' (or 'mobilePhoneNumber') fields at least.
+     *                  More data may be neccesary depending on the message type
+     * Example: $additional_parameters = array(
+     *              'smsType' => EXAMPLE_SMS_TYPE,
+     *              'userId' => $userId,
+     *              'moreData' => $moreData
+     *          );
+     * @return  void
+     */
     public function send($additionalParameters)
     {
         $trimmedKey = trim(CONFIG_SECURITY_API_KEY);
@@ -90,6 +113,15 @@ class Clockworksms
         }
     }
 
+    /**
+     * buildSms (builds an SMS from a template and data)
+     * @param   object  ClockworksmsPlugin object
+     * @param   object  Template object
+     * @param   string  Template file name
+     * @param   string  Text key from lang file
+     * @param   array   Data to fill message variables (if any)
+     * @return  object  Template object with message property updated
+     */
     public function buildSms($plugin, $tpl, $templateName, $messageKey, $parameters = null)
     {
         $result = Database::select(
@@ -115,6 +147,18 @@ class Clockworksms
         return $tpl->params['message'];
     }
 
+    /**
+     * getSms (returns an SMS message depending of its type)
+     * @param   array   Data needed to send the SMS. It is mandatory to include the
+     *                  'smsType' and 'userId' (or 'mobilePhoneNumber') fields at least.
+     *                  More data may be neccesary depending on the message type
+     * Example: $additional_parameters = array(
+     *              'smsType' => EXAMPLE_SMS_TYPE,
+     *              'userId' => $userId,
+     *              'moreData' => $moreData
+     *          );
+     * @return  string  A ready to be sent SMS
+     */
     public function getSms($additionalParameters)
     {
         $plugin = ClockworksmsPlugin::create();

plugin/clockworksms/lib/clockworksms_plugin.class.php

@@ -1,6 +1,12 @@
 <?php
+/* For licensing terms, see /vendor/license.txt */
+
 /**
  * Class ClockworksmsPlugin
+ * This script contains SMS type constants and basic plugin functions
+ * 
+ * @package chamilo.plugin.clockworksms.lib
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
  */
 class ClockworksmsPlugin extends Plugin
 {
@@ -51,12 +57,21 @@ class ClockworksmsPlugin extends Plugin
     public $isCoursePlugin = true;
     public $isMailPlugin = true;
 
-    static function create()
+    /**
+     * create (a singleton function that ensures ClockworksmsPlugin instance is
+     * created only once. If it is already created, it returns the instance)
+     * @return  object  ClockworksmsPlugin instance
+     */
+    public static function create()
     {
         static $result = null;
         return $result ? $result : $result = new self();
     }
 
+    /**
+     * Constructor
+     * @return  void
+     */
     protected function __construct()
     {
         $fields = array('tool_enable' => 'boolean', 'api_key' => 'text');
@@ -67,6 +82,11 @@ class ClockworksmsPlugin extends Plugin
         parent::__construct('0.1', 'Imanol Losada', $fields);
     }
 
+    /**
+     * addMobilePhoneNumberField (adds a mobile phone number field if it is not
+     * already created)
+     * @return  void
+     */
     private function addMobilePhoneNumberField()
     {
         $result = Database::select('mobile_phone_number', 'user_field');
@@ -86,6 +106,10 @@ class ClockworksmsPlugin extends Plugin
         }
     }
 
+    /**
+     * getSmsTypeOptions (returns all SMS types)
+     * @return  array   SMS types
+     */
     private function getSmsTypeOptions()
     {
         return array(
@@ -135,11 +159,18 @@ class ClockworksmsPlugin extends Plugin
         );
     }
 
+    /**
+     * install (installs the plugin)
+     * @return  void
+     */
     public function install()
     {
         $this->addMobilePhoneNumberField();
     }
-
+    /**
+     * install (uninstalls the plugin and removes all plugin's tables and/or rows)
+     * @return  void
+     */
     public function uninstall()
     {
         $tSettings = Database::get_main_table(TABLE_MAIN_SETTINGS_CURRENT);

plugin/clockworksms/plugin.php

@@ -1,5 +1,10 @@
 <?php
+/* For licensing terms, see /vendor/license.txt */
 
+/**
+ * @package chamilo.plugin.clockworksms
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
+ */
 require_once dirname(__FILE__).'/config.php';
 
 $plugin_info = ClockworksmsPlugin::create()->get_info();

plugin/clockworksms/readme.txt

@@ -1,253 +1,3 @@
-# Clockwork SMS API Wrapper for PHP
+This plugin enables Chamilo to send SMS messages to Chamilo users when a notification email is sent.
 
-This wrapper lets you interact with Clockwork without the hassle of having to create any XML or make HTTP calls.
+SMS message types (a new course is created, an account is approved and so on) can be enabled or disabled from it's plugin configuration option.
-
-## What's Clockwork?
-
-[Clockwork][2] is Mediaburst's SMS API.
-
-### Prerequisites
-
-* A [Clockwork][2] account
-
-## Usage
-
-Require the Clockwork library:
-
-```php
-require 'class-Clockwork.php';
-```
-
-### Sending a message
-
-```php
-$clockwork = new Clockwork( $API_KEY );
-$message = array( 'to' => '441234567891', 'message' => 'This is a test!' );
-$result = $clockwork->send( $message );
-```
-
-### Sending multiple messages
-
-We recommend you use batch sizes of 500 messages or fewer. By limiting the batch size it prevents any timeouts when sending.
-
-```php
-$clockwork = new Clockwork( $API_KEY );
-$messages = array( 
-    array( 'to' => '441234567891', 'message' => 'This is a test!' ),
-    array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
-);
-$results = $clockwork->send( $messages );
-```
-
-### Handling the response
-
-The responses come back as arrays, these contain the unique Clockwork message ID, whether the message worked (`success`), and the original SMS so you can update your database.
-
-    Array
-    (
-        [id] => VE_164732148
-        [success] => 1
-        [sms] => Array
-            (
-                [to] => 441234567891
-                [message] => This is a test!
-            )
-
-    )
-
-If you send multiple SMS messages in a single send, you'll get back an array of results, one per SMS.
-
-The result will look something like this:
-
-    Array
-    (
-        [0] => Array
-            (
-                [id] => VI_143228951
-                [success] => 1
-                [sms] => Array
-                    (
-                        [to] => 441234567891
-                        [message] => This is a test!
-                    )
-
-            )
-
-        [1] => Array
-            (
-                [id] => VI_143228952
-                [success] => 1
-                [sms] => Array
-                    (
-                        [to] => 441234567892
-                        [message] => This is a test 2!
-                    )
-
-            )
-
-    )
-
-If a message fails, the reason for failure will be set in `error_code` and `error_message`.  
-
-For example, if you send to invalid phone number "abc":
-
-    Array
-    (
-        [error_code] => 10
-        [error_message] => Invalid 'To' Parameter
-        [success] => 0
-        [sms] => Array
-            (
-                [to] => abc
-                [message] => This is a test!
-            )
-
-    )
-
-### Checking your balance
-
-Check your available SMS balance:
-
-```php
-$clockwork = new Clockwork( $API_KEY );
-$clockwork->checkBalance();
-```    
-
-This will return:
-
-    Array 
-    (
-        [symbol] => £
-        [balance] => 351.91
-        [code] => GBP
-    )
-    
-### Handling Errors
-
-The Clockwork wrapper will throw a `ClockworkException` if the entire call failed.
-
-```php
-try 
-{
-    $clockwork = new Clockwork( 'invalid_key' );
-    $message = array( 'to' => 'abc', 'message' => 'This is a test!' );
-    $result = $clockwork->send( $message );
-}
-catch( ClockworkException $e )
-{
-    print $e->getMessage();
-    // Invalid API Key
-}
-```    
-
-### Advanced Usage
-
-This class has a few additional features that some users may find useful, if these are not set your account defaults will be used.
-
-### Optional Parameters
-
-See the [Clockwork Documentation](http://www.clockworksms.com/doc/clever-stuff/xml-interface/send-sms/) for full details on these options.
-
-*   $from [string]
-
-    The from address displayed on a phone when they receive a message
-
-*   $long [boolean]  
-
-    Enable long SMS. A standard text can contain 160 characters, a long SMS supports up to 459.
-
-*   $truncate [nullable boolean]  
-
-    Truncate the message payload if it is too long, if this is set to false, the message will fail if it is too long.
-
-*	$invalid_char_action [string]
-
-	What to do if the message contains an invalid character. Possible values are
-	* error			 - Fail the message
-	* remove		 - Remove the invalid characters then send
-	* replace		 - Replace some common invalid characters such as replacing curved quotes with straight quotes
-
-*   $ssl [boolean, default: true]
-  
-    Use SSL when making an HTTP request to the Clockwork API
-
-
-### Setting Options
-
-#### Global Options
-
-Options set on the API object will apply to all SMS messages unless specifically overridden.
-
-In this example both messages will be sent from Clockwork:
-
-```php
-$options = array( 'from' => 'Clockwork' );
-$clockwork = new Clockwork( $API_KEY, $options );
-$messages = array( 
-    array( 'to' => '441234567891', 'message' => 'This is a test!' ),
-    array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
-);
-$results = $clockwork->send( $messages );
-```
-
-#### Per-message Options
-
-Set option values individually on each message.
-
-In this example, one message will be from Clockwork and the other from 84433:
-
-```php
-$clockwork = new Clockwork( $API_KEY, $options );
-$messages = array( 
-    array( 'to' => '441234567891', 'message' => 'This is a test!', 'from' => 'Clockwork' ),
-    array( 'to' => '441234567892', 'message' => 'This is a test 2!', 'from' => '84433' )
-);
-$results = $clockwork->send( $messages );
-```
-
-### SSL Errors
-
-Due to the huge variety of PHP setups out there a small proportion of users may get PHP errors when making API calls due to their SSL configuration.
-
-The errors will generally look something like this:
-
-```
-Fatal error: 
-Uncaught exception 'Exception' with message 'HTTP Error calling Clockwork API
-HTTP Status: 0
-cURL Erorr: SSL certificate problem, verify that the CA cert is OK. 
-Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed'
-```
-
-If you're seeing this error there are two fixes available, the first is easy, simply disable SSL on Clockwork calls. Alternatively you can setup your PHP install with the correct root certificates.
-
-#### Disable SSL on Clockwork calls
-
-```php
-$options = array( 'ssl' => false );
-$clockwork = new Clockwork( $API_KEY, $options );
-```
-
-#### Setup SSL root certificates on your server
-
-This is much more complicated as it depends on your setup, however there are many guides available online. 
-Try a search term like "windows php curl root certificates" or "ubuntu update root certificates".
-
-
-# License
-
-This project is licensed under the ISC open-source license.
-
-A copy of this license can be found in license.txt.
-
-# Contributing
-
-If you have any feedback on this wrapper drop us an email to [hello@clockworksms.com][1].
-
-The project is hosted on GitHub at [https://github.com/mediaburst/clockwork-php][3].
-If you would like to contribute a bug fix or improvement please fork the project 
-and submit a pull request.
-
-[1]: mailto:hello@clockworksms.com
-[2]: http://www.clockworksms.com/
-[3]: https://github.com/mediaburst/clockwork-php

plugin/clockworksms/uninstall.php

@@ -1,10 +1,13 @@
 <?php
+/* For licensing terms, see /vendor/license.txt */
 
 /**
  * This script is included by main/admin/settings.lib.php when unselecting a plugin
  * and is meant to remove things installed by the install.php script in both
  * the global database and the courses tables
+ *
  * @package chamilo.plugin.clockworksms
+ * @author  Imanol Losada <imanol.losada@beeznest.com>
  */
 /**
  * Queries

plugin/clockworksms/vendor/license.txt

@@ -0,0 +1,14 @@
+Copyright (c) 2011 - 2012, Mediaburst Ltd <hello@mediaburst.co.uk>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+