From 9c0c9863d532942b99184f14e923fc3c050f8177 Mon Sep 17 00:00:00 2001
From: Evan Prodromou <evan@status.net>
Date: Sat, 24 Apr 2010 14:20:28 -0400
Subject: [PATCH] documentation and whitespace on UrlShortenerPlugin

---
 plugins/UrlShortener/UrlShortenerPlugin.php | 108 +++++++++++++++-----
 1 file changed, 84 insertions(+), 24 deletions(-)

diff --git a/plugins/UrlShortener/UrlShortenerPlugin.php b/plugins/UrlShortener/UrlShortenerPlugin.php
index 027624b7ae..8acfac26f4 100644
--- 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;
     }
 }