diff options
-rw-r--r-- | CHANGELOG.md | 4 | ||||
-rw-r--r-- | plugins/MobileMessaging/API.php | 16 | ||||
-rw-r--r-- | plugins/MobileMessaging/Controller.php | 7 | ||||
-rw-r--r-- | plugins/MobileMessaging/SMSProvider.php | 151 | ||||
-rw-r--r-- | plugins/MobileMessaging/SMSProvider/Clockwork.php | 24 | ||||
-rw-r--r-- | plugins/MobileMessaging/SMSProvider/Development.php | 17 | ||||
-rw-r--r-- | plugins/MobileMessaging/SMSProvider/StubbedProvider.php | 16 |
7 files changed, 160 insertions, 75 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 13e95ce368..077ece7ace 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,9 @@ This is a changelog for Piwik platform developers. All changes for our HTTP API' ### Internal change * When generating a new plugin skeleton via `generate:plugin` command, plugin name must now contain only letters and numbers. * JavaScript Tracker tests no longer require `SQLite`. The existing MySQL configuration for tests is used now. In order to run the tests make sure Piwik is installed and `[database_tests]` is configured in `config/config.ini.php`. - + +### New APIs + * Add your own SMS/Text provider by creating a new class in the `SMSProvider` directory of your plugin. The class has to extend `Piwik\Plugins\MobileMessaging\SMSProvider` and implement the required methods. ## Piwik 2.15.0 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; |