documentation and whitespace on UrlShortenerPlugin

[quix0rs-gnu-social.git] / plugins / UrlShortener / UrlShortenerPlugin.php

diff --git a/plugins/UrlShortener/UrlShortenerPlugin.php b/plugins/UrlShortener/UrlShortenerPlugin.php
index 027624b7ae1ca1c439d0731fc3dce8b252f7ccb1..8acfac26f4f96b0da940daced6071f94a04e17a1 100644 (file)
--- a/plugins/UrlShortener/UrlShortenerPlugin.php
+++ b/plugins/UrlShortener/UrlShortenerPlugin.php
@@ -19,11 +19,11 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
- * @category  Plugin
- * @package   StatusNet
- * @author    Craig Andrews <candrews@integralblue.com>
- * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
- * @link      http://status.net/
+ * @category Plugin
+ * @package  StatusNet
+ * @author   Craig Andrews <candrews@integralblue.com>
+ * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
+ * @link     http://status.net/
  */
 
 if (!defined('STATUSNET') && !defined('LACONICA')) {
@@ -43,53 +43,113 @@ if (!defined('STATUSNET') && !defined('LACONICA')) {
 abstract class UrlShortenerPlugin extends Plugin
 {
     public $shortenerName;
-    public $freeService=false;
-    //------------Url Shortener plugin should implement some (or all) of these methods------------\\
+    public $freeService = false;
+
+    // Url Shortener plugins should implement some (or all)
+    // of these methods
 
     /**
-    * Short a URL
-    * @param url
-    * @return string shortened version of the url, or null if URL shortening failed
-    */
+     * Make an URL shorter.
+     *
+     * @param string $url URL to shorten
+     *
+     * @return string shortened version of the url, or null on failure
+     */
+
     protected abstract function shorten($url);
 
-    //------------These methods may help you implement your plugin------------\\
+    /**
+     * Utility to get the data at an URL
+     *
+     * @param string $url URL to fetch
+     *
+     * @return string response body
+     *
+     * @todo rename to code-standard camelCase httpGet()
+     */
+
     protected function http_get($url)
     {
-        $request = HTTPClient::start();
+        $request  = HTTPClient::start();
         $response = $request->get($url);
         return $response->getBody();
     }
 
-    protected function http_post($url,$data)
+    /**
+     * Utility to post a request and get a response URL
+     *
+     * @param string $url  URL to fetch
+     * @param array  $data post parameters
+     *
+     * @return string response body
+     *
+     * @todo rename to code-standard httpPost()
+     */
+
+    protected function http_post($url, $data)
     {
-        $request = HTTPClient::start();
+        $request  = HTTPClient::start();
         $response = $request->post($url, null, $data);
         return $response->getBody();
     }
 
-    //------------Below are the methods that connect StatusNet to the implementing Url Shortener plugin------------\\
+    // Hook handlers
 
-    function onInitializePlugin(){
-        if(!isset($this->shortenerName)){
+    /**
+     * Called when all plugins have been initialized
+     *
+     * @return boolean hook value
+     */
+
+    function onInitializePlugin()
+    {
+        if (!isset($this->shortenerName)) {
             throw new Exception("must specify a shortenerName");
         }
+        return true;
     }
 
+    /**
+     * Called when a showing the URL shortener drop-down box
+     *
+     * Properties of the shortening service currently only
+     * include whether it's a free service.
+     *
+     * @param array &$shorteners array mapping shortener name to properties
+     *
+     * @return boolean hook value
+     */
+
     function onGetUrlShorteners(&$shorteners)
     {
-        $shorteners[$this->shortenerName]=array('freeService'=>$this->freeService);
+        $shorteners[$this->shortenerName] =
+          array('freeService' => $this->freeService);
+        return true;
     }
 
-    function onStartShortenUrl($url,$shortenerName,&$shortenedUrl)
+    /**
+     * Called to shorten an URL
+     *
+     * @param string $url           URL to shorten
+     * @param string $shortenerName Shortening service. Don't handle if it's
+     *                              not you!
+     * @param string &$shortenedUrl URL after shortening; out param.
+     *
+     * @return boolean hook value
+     */
+
+    function onStartShortenUrl($url, $shortenerName, &$shortenedUrl)
     {
-        if($shortenerName == $this->shortenerName && strlen($url) >= common_config('site', 'shorturllength')){
+        if ($shortenerName == $this->shortenerName) {
             $result = $this->shorten($url);
-            if(isset($result) && $result != null && $result !== false){
-                $shortenedUrl=$result;
-                common_log(LOG_INFO, __CLASS__ . ": $this->shortenerName shortened $url to $shortenedUrl");
+            if (isset($result) && $result != null && $result !== false) {
+                $shortenedUrl = $result;
+                common_log(LOG_INFO,
+                           __CLASS__ . ": $this->shortenerName ".
+                           "shortened $url to $shortenedUrl");
                 return false;
             }
         }
+        return true;
     }
 }