Merge pull request #9226 from piwik/9208

New API to create custom SMS providers in Piwik plugins

6 files changed, 157 insertions, 74 deletions

diff --git a/plugins/MobileMessaging/API.php b/plugins/MobileMessaging/API.php
index aaf30e6a64..345c633b15 100644
--- a/plugins/MobileMessaging/API.php
+++ b/plugins/MobileMessaging/API.php
@@ -8,7 +8,6 @@
  */
 namespace Piwik\Plugins\MobileMessaging;
 
-use Piwik\Common;
 use Piwik\Option;
 use Piwik\Piwik;
 use Piwik\Plugins\MobileMessaging\SMSProvider;
@@ -27,15 +26,6 @@ class API extends \Piwik\Plugin\API
     const SMS_FROM = 'Piwik';
 
     /**
-     * @param string $provider
-     * @return SMSProvider
-     */
-    private static function getSMSProviderInstance($provider)
-    {
-        return SMSProvider::factory($provider);
-    }
-
-    /**
      * determine if SMS API credential are available for the current user
      *
      * @return bool true if SMS API credential are available for the current user
@@ -83,7 +73,7 @@ class API extends \Piwik\Plugin\API
     {
         $this->checkCredentialManagementRights();
 
-        $smsProviderInstance = self::getSMSProviderInstance($provider);
+        $smsProviderInstance = SMSProvider::factory($provider);
         $smsProviderInstance->verifyCredential($apiKey);
 
         $settings = $this->getCredentialManagerSettings();
@@ -160,7 +150,7 @@ class API extends \Piwik\Plugin\API
         Piwik::checkUserIsNotAnonymous();
 
         $credential = $this->getSMSAPICredential();
-        $SMSProvider = self::getSMSProviderInstance($credential[MobileMessaging::PROVIDER_OPTION]);
+        $SMSProvider = SMSProvider::factory($credential[MobileMessaging::PROVIDER_OPTION]);
         $SMSProvider->sendSMS(
             $credential[MobileMessaging::API_KEY_OPTION],
             $content,
@@ -183,7 +173,7 @@ class API extends \Piwik\Plugin\API
         $this->checkCredentialManagementRights();
 
         $credential = $this->getSMSAPICredential();
-        $SMSProvider = self::getSMSProviderInstance($credential[MobileMessaging::PROVIDER_OPTION]);
+        $SMSProvider = SMSProvider::factory($credential[MobileMessaging::PROVIDER_OPTION]);
         return $SMSProvider->getCreditLeft(
             $credential[MobileMessaging::API_KEY_OPTION]
         );
diff --git a/plugins/MobileMessaging/Controller.php b/plugins/MobileMessaging/Controller.php
index 2bb6f8d5f5..7ba976c67e 100644
--- a/plugins/MobileMessaging/Controller.php
+++ b/plugins/MobileMessaging/Controller.php
@@ -94,7 +94,12 @@ class Controller extends ControllerAdmin
             $view->creditLeft = $mobileMessagingAPI->getCreditLeft();
         }
 
-        $view->smsProviders = SMSProvider::getAvailableSMSProviders();
+        $providers = array();
+        foreach (SMSProvider::findAvailableSmsProviders() as $provider) {
+            $providers[$provider->getId()] = $provider->getDescription();
+        }
+
+        $view->smsProviders = $providers;
 
         // construct the list of countries from the lang files
         $countries = array();
diff --git a/plugins/MobileMessaging/SMSProvider.php b/plugins/MobileMessaging/SMSProvider.php
index 1711bfafed..14aec1bb24 100644
--- a/plugins/MobileMessaging/SMSProvider.php
+++ b/plugins/MobileMessaging/SMSProvider.php
@@ -8,63 +8,120 @@
  */
 namespace Piwik\Plugins\MobileMessaging;
 
-use Exception;
-use Piwik\Development;
+use Piwik\Container\StaticContainer;
+use Piwik\Plugin;
 use Piwik\Piwik;
-use Piwik\BaseFactory;
 
 /**
- * The SMSProvider abstract class is used as a base class for SMS provider implementations.
+ * The SMSProvider abstract class is used as a base class for SMS provider implementations. To create your own custom
+ * SMSProvider extend this class and implement the methods to send text messages. The class needs to be placed in a
+ * `SMSProvider` directory of your plugin.
  *
+ * @api
  */
-abstract class SMSProvider extends BaseFactory
+abstract class SMSProvider
 {
     const MAX_GSM_CHARS_IN_ONE_UNIQUE_SMS = 160;
     const MAX_GSM_CHARS_IN_ONE_CONCATENATED_SMS = 153;
     const MAX_UCS2_CHARS_IN_ONE_UNIQUE_SMS = 70;
     const MAX_UCS2_CHARS_IN_ONE_CONCATENATED_SMS = 67;
 
-    protected static $availableSMSProviders = array(
-        'Clockwork' => 'You can use <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/platforms/piwik/"><img src="plugins/MobileMessaging/images/Clockwork.png"/></a> to send SMS Reports from Piwik.<br/>
-			<ul>
-			<li> First, <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/platforms/piwik/">get an API Key from Clockwork</a> (Signup is free!)
-			</li><li> Enter your Clockwork API Key on this page. </li>
-			</ul>
-			<br/><em>About Clockwork: </em><ul>
-			<li>Clockwork gives you fast, reliable high quality worldwide SMS delivery, over 450 networks in every corner of the globe.
-			</li><li>Cost per SMS message is around ~0.08USD (0.06EUR).
-			</li><li>Most countries and networks are supported but we suggest you check the latest position on their coverage map <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/sms-coverage/">here</a>.
-			</li>
-			</ul>
-			',
-    );
-
-    protected static function getClassNameFromClassId($id)
+    /**
+     * Get the ID of the SMS Provider. Eg 'Clockwork' or 'FreeMobile'
+     * @return string
+     */
+    abstract public function getId();
+
+    /**
+     * Get a description about the SMS Provider. For example who the SMS Provider is, instructions how the API Key
+     * needs to be set, and more. You may return HTML here for better formatting.
+     *
+     * @return string
+     */
+    abstract public function getDescription();
+
+    /**
+     * Verify the SMS API credential.
+     *
+     * @param string $apiKey API Key
+     * @return bool true if SMS API Key is valid, false otherwise
+     */
+    abstract public function verifyCredential($apiKey);
+
+    /**
+     * Get the amount of remaining credits.
+     *
+     * @param string $apiKey API Key
+     * @return string remaining credits
+     */
+    abstract public function getCreditLeft($apiKey);
+
+    /**
+     * Actually send the given text message. This method should only send the text message, it should not trigger
+     * any notifications etc.
+     *
+     * @param string $apiKey
+     * @param string $smsText
+     * @param string $phoneNumber
+     * @param string $from
+     * @return bool true
+     */
+    abstract public function sendSMS($apiKey, $smsText, $phoneNumber, $from);
+
+    /**
+     * Defines whether the SMS Provider is available. If a certain provider should be used only be a limited
+     * range of users you can restrict the provider here. For example there is a Development SMS Provider that is only
+     * available when the development is actually enabled. You could also create a SMS Provider that is only available
+     * to Super Users etc. Usually this method does not have to be implemented by a SMS Provider.
+     *
+     * @return bool
+     */
+    public function isAvailable()
     {
-        return __NAMESPACE__ . '\\SMSProvider\\' . $id;
+        return true;
     }
 
-    protected static function getInvalidClassIdExceptionMessage($id)
+    /**
+     * @param string $provider The name of the string
+     * @return SMSProvider
+     * @throws \Exception
+     * @ignore
+     */
+    public static function factory($provider)
     {
-        return Piwik::translate('MobileMessaging_Exception_UnknownProvider',
-            array($id, implode(', ', array_keys(self::getAvailableSMSProviders())))
-        );
+        $providers = self::findAvailableSmsProviders();
+
+        if (!array_key_exists($provider, $providers)) {
+            throw new \Exception(Piwik::translate('MobileMessaging_Exception_UnknownProvider',
+                array($provider, implode(', ', array_keys($providers)))
+            ));
+        }
+
+        return $providers[$provider];
     }
 
     /**
      * Returns all available SMS Providers
-     * 
-     * @return array
+     *
+     * @return SMSProvider[]
+     * @ignore
      */
-    public static function getAvailableSMSProviders()
+    public static function findAvailableSmsProviders()
     {
-        $smsProviders = self::$availableSMSProviders;
+        /** @var SMSProvider[] $smsProviders */
+        $smsProviders = Plugin\Manager::getInstance()->findMultipleComponents('SMSProvider', 'Piwik\Plugins\MobileMessaging\SMSProvider');
+
+        $providers = array();
 
-        if (Development::isEnabled()) {
-            $smsProviders['Development'] = 'Development SMS Provider<br />All sent SMS will be displayed as Notification';
+        foreach ($smsProviders as $provider) {
+            /** @var SMSProvider $provider */
+            $provider = StaticContainer::get($provider);
+            if ($provider->isAvailable()) {
+                $providers[$provider->getId()] = $provider;
+            }
         }
 
-        return $smsProviders;
+        return $providers;
     }
 
     /**
@@ -72,6 +129,7 @@ abstract class SMSProvider extends BaseFactory
      *
      * @param string $string
      * @return bool true if $string contains UCS2 characters
+     * @ignore
      */
     public static function containsUCS2Characters($string)
     {
@@ -94,6 +152,7 @@ abstract class SMSProvider extends BaseFactory
      * @param int $maximumNumberOfConcatenatedSMS
      * @param string $appendedString
      * @return string original $string or truncated $string appended with $appendedString
+     * @ignore
      */
     public static function truncate($string, $maximumNumberOfConcatenatedSMS, $appendedString = 'MobileMessaging_SMS_Content_Too_Long')
     {
@@ -150,30 +209,4 @@ abstract class SMSProvider extends BaseFactory
             $maxCharsInOneConcatenatedSMS * $maximumNumberOfConcatenatedSMS;
     }
 
-    /**
-     * verify the SMS API credential
-     *
-     * @param string $apiKey API Key
-     * @return bool true if SMS API credential are valid, false otherwise
-     */
-    abstract public function verifyCredential($apiKey);
-
-    /**
-     * get remaining credits
-     *
-     * @param string $apiKey API Key
-     * @return string remaining credits
-     */
-    abstract public function getCreditLeft($apiKey);
-
-    /**
-     * send SMS
-     *
-     * @param string $apiKey
-     * @param string $smsText
-     * @param string $phoneNumber
-     * @param string $from
-     * @return bool true
-     */
-    abstract public function sendSMS($apiKey, $smsText, $phoneNumber, $from);
 }
diff --git a/plugins/MobileMessaging/SMSProvider/Clockwork.php b/plugins/MobileMessaging/SMSProvider/Clockwork.php
index 2ae8e95da4..50a7f0e50b 100644
--- a/plugins/MobileMessaging/SMSProvider/Clockwork.php
+++ b/plugins/MobileMessaging/SMSProvider/Clockwork.php
@@ -15,8 +15,9 @@ use Piwik\Plugins\MobileMessaging\APIException;
 use Piwik\Plugins\MobileMessaging\SMSProvider;
 
 require_once PIWIK_INCLUDE_PATH . "/plugins/MobileMessaging/APIException.php";
+
 /**
- *
+ * @ignore
  */
 class Clockwork extends SMSProvider
 {
@@ -31,6 +32,27 @@ class Clockwork extends SMSProvider
     const MAXIMUM_FROM_LENGTH = 11;
     const MAXIMUM_CONCATENATED_SMS = 3;
 
+    public function getId()
+    {
+        return 'Clockwork';
+    }
+
+    public function getDescription()
+    {
+        return 'You can use <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/platforms/piwik/"><img src="plugins/MobileMessaging/images/Clockwork.png"/></a> to send SMS Reports from Piwik.<br/>
+			<ul>
+			<li> First, <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/platforms/piwik/">get an API Key from Clockwork</a> (Signup is free!)
+			</li><li> Enter your Clockwork API Key on this page. </li>
+			</ul>
+			<br/><em>About Clockwork: </em><ul>
+			<li>Clockwork gives you fast, reliable high quality worldwide SMS delivery, over 450 networks in every corner of the globe.
+			</li><li>Cost per SMS message is around ~0.08USD (0.06EUR).
+			</li><li>Most countries and networks are supported but we suggest you check the latest position on their coverage map <a target="_blank" href="?module=Proxy&action=redirect&url=http://www.clockworksms.com/sms-coverage/">here</a>.
+			</li>
+			</ul>
+			';
+    }
+
     public function verifyCredential($apiKey)
     {
         $this->getCreditLeft($apiKey);
diff --git a/plugins/MobileMessaging/SMSProvider/Development.php b/plugins/MobileMessaging/SMSProvider/Development.php
index ef6cbe951d..18cc57809a 100644
--- a/plugins/MobileMessaging/SMSProvider/Development.php
+++ b/plugins/MobileMessaging/SMSProvider/Development.php
@@ -10,14 +10,31 @@ namespace Piwik\Plugins\MobileMessaging\SMSProvider;
 
 use Piwik\Notification;
 use Piwik\Plugins\MobileMessaging\SMSProvider;
+use Piwik\Development as PiwikDevelopment;
 
 /**
  * Used for development only
  *
+ * @ignore
  */
 class Development extends SMSProvider
 {
 
+    public function getId()
+    {
+        return 'Development';
+    }
+
+    public function getDescription()
+    {
+        return 'Development SMS Provider<br />All sent SMS will be displayed as Notification';
+    }
+
+    public function isAvailable()
+    {
+        return PiwikDevelopment::isEnabled();
+    }
+
     public function verifyCredential($apiKey)
     {
         return true;
diff --git a/plugins/MobileMessaging/SMSProvider/StubbedProvider.php b/plugins/MobileMessaging/SMSProvider/StubbedProvider.php
index b9527a3b8d..8bda726a3e 100644
--- a/plugins/MobileMessaging/SMSProvider/StubbedProvider.php
+++ b/plugins/MobileMessaging/SMSProvider/StubbedProvider.php
@@ -13,10 +13,26 @@ use Piwik\Plugins\MobileMessaging\SMSProvider;
 /**
  * Used for testing
  *
+ * @ignore
  */
 class StubbedProvider extends SMSProvider
 {
 
+    public function getId()
+    {
+        return 'StubbedProvider';
+    }
+
+    public function getDescription()
+    {
+        return 'Only during testing available';
+    }
+
+    public function isAvailable()
+    {
+        return defined('PIWIK_TEST_MODE') && PIWIK_TEST_MODE;
+    }
+
     public function verifyCredential($apiKey)
     {
         return true;