merge master

5 files changed, 192 insertions, 44 deletions

diff --git a/src/SemanticScuttle/Service/Bookmark.php b/src/SemanticScuttle/Service/Bookmark.php
index 6f8a172..a30ad5f 100644
--- a/src/SemanticScuttle/Service/Bookmark.php
+++ b/src/SemanticScuttle/Service/Bookmark.php
@@ -734,7 +734,8 @@ class SemanticScuttle_Service_Bookmark extends SemanticScuttle_DbService
         if (SQL_LAYER == 'mysql4') {
             $query_1 .= 'SQL_CALC_FOUND_ROWS ';
         }
-        $query_1 .= 'B.*, U.'. $userservice->getFieldName('username');
+        $query_1 .= 'B.*, U.'. $userservice->getFieldName('username')
+            . ', U.name';
 
         $query_2 = ' FROM '. $userservice->getTableName() .' AS U'
             . ', '. $this->getTableName() .' AS B';
diff --git a/src/SemanticScuttle/Service/Bookmark2Tag.php b/src/SemanticScuttle/Service/Bookmark2Tag.php
index 4d2c969..a10cb61 100644
--- a/src/SemanticScuttle/Service/Bookmark2Tag.php
+++ b/src/SemanticScuttle/Service/Bookmark2Tag.php
@@ -454,58 +454,155 @@ class SemanticScuttle_Service_Bookmark2Tag extends SemanticScuttle_DbService
         return $output;
     }
 
-    function &getAdminTags($limit = 30, $logged_on_user = NULL, $days = NULL) {
+
+
+    /**
+     * Returns the tags used by admin users
+     *
+     * @param integer $limit          Number of tags to return
+     * @param integer $logged_on_user ID of the user that's currently logged in.
+     *                                If the logged in user equals the $user to find
+     *                                tags for, tags of private bookmarks are
+     *                                returned.
+     * @param integer $days           Bookmarks have to be changed in the last X days
+     *                                if their tags shall count
+     * @param string  $beginsWith     The tag name shall begin with that string
+     *
+     * @return array Array of found tags. Each tag entry is an array with two keys,
+     *               'tag' (tag name) and 'bCount'.
+     *
+     * @see getPopularTags()
+     */
+    public function getAdminTags(
+        $limit = 30, $logged_on_user = null, $days = null, $beginsWith = null
+    ) {
         // look for admin ids
-        $userservice = SemanticScuttle_Service_Factory :: get('User');
-        $adminIds = $userservice->getAdminIds();
+        $userservice = SemanticScuttle_Service_Factory::get('User');
+        $adminIds    = $userservice->getAdminIds();
 
         // ask for their tags
-        return $this->getPopularTags($adminIds, $limit, $logged_on_user, $days);
+        return $this->getPopularTags(
+            $adminIds, $limit, $logged_on_user, $days, $beginsWith
+        );
     }
 
-    function &getContactTags($user, $limit = 30, $logged_on_user = NULL, $days = NULL) {
+
+
+
+    /**
+     * Returns the tags used by users that are part of the user's watchlist,
+     * and the current user's own tags.
+     *
+     * @param integer $user           ID of the user to get the watchlist from
+     * @param integer $limit          Number of tags to return
+     * @param integer $logged_on_user ID of the user that's currently logged in.
+     *                                If set, that user is added to the list of
+     *                                people to get the tags from
+     * @param integer $days           Bookmarks have to be changed in the last X days
+     *                                if their tags shall count
+     * @param string  $beginsWith     The tag name shall begin with that string
+     *
+     * @return array Array of found tags. Each tag entry is an array with two keys,
+     *               'tag' (tag name) and 'bCount'.
+     *
+     * @see getPopularTags()
+     */
+    public function getContactTags(
+        $user, $limit = 30, $logged_on_user = null, $days = null,
+        $beginsWith = null
+    ) {
         // look for contact ids
-        $userservice = SemanticScuttle_Service_Factory :: get('User');
+        $userservice = SemanticScuttle_Service_Factory::get('User');
         $contacts = $userservice->getWatchlist($user);
 
-        // add the user (to show him/her also his/her tags)
-        if(!is_null($logged_on_user)) {
+        // add the user (to show him also his own tags)
+        if (!is_null($logged_on_user)) {
             $contacts[] = $logged_on_user;
         }
 
         // ask for their tags
-        return $this->getPopularTags($contacts, $limit, $logged_on_user, $days);
+        return $this->getPopularTags(
+            $contacts, $limit, $logged_on_user, $days, $beginsWith
+        );
     }
 
-    // $users can be {NULL, an id, an array of id}
-    function &getPopularTags($user = NULL, $limit = 30, $logged_on_user = NULL, $days = NULL) {
+
+
+    /**
+     * The the most popular tags and their usage count
+     *
+     * @param mixed   $user           Integer user ID or array of user IDs to limit tag
+     *                                finding to
+     * @param integer $limit          Number of tags to return
+     * @param integer $logged_on_user ID of the user that's currently logged in.
+     *                                If the logged in user equals the $user to find
+     *                                tags for, tags of private bookmarks are
+     *                                returned.
+     * @param integer $days           Bookmarks have to be changed in the last X days
+     *                                if their tags shall count
+     * @param string  $beginsWith     The tag name shall begin with that string
+     *
+     * @return array Array of found tags. Each tag entry is an array with two keys,
+     *               'tag' (tag name) and 'bCount'.
+     *
+     * @see getAdminTags()
+     * @see getContactTags()
+     */
+    public function getPopularTags(
+        $user = null, $limit = 30, $logged_on_user = null, $days = null,
+        $beginsWith = null
+    ) {
         // Only count the tags that are visible to the current user.
-        if (($user != $logged_on_user) || is_null($user) || ($user === false))
-        $privacy = ' AND B.bStatus = 0';
-        else
-        $privacy = '';
+        if (($user != $logged_on_user) || is_null($user) || ($user === false)) {
+            $privacy = ' AND B.bStatus = 0';
+        } else {
+            $privacy = '';
+        }
 
-        if (is_null($days) || !is_int($days))
-        $span = '';
-        else
-        $span = ' AND B.bDatetime > "'. date('Y-m-d H:i:s', time() - (86400 * $days)) .'"';
+        $query = 'SELECT'
+            . ' T.tag, COUNT(T.bId) AS bCount'
+            . ' FROM '
+            . $this->getTableName() . ' AS T'
+            . ', ' . $GLOBALS['tableprefix'] . 'bookmarks AS B'
+            . ' WHERE';
 
-        $query = 'SELECT T.tag, COUNT(T.bId) AS bCount FROM '. $this->getTableName() .' AS T, '. $GLOBALS['tableprefix'] .'bookmarks AS B WHERE ';
         if (is_null($user) || ($user === false)) {
-            $query .= 'B.bId = T.bId AND B.bStatus = 0';
-        } elseif(is_array($user)) {
+            $query .= ' B.bId = T.bId AND B.bStatus = 0';
+        } else if (is_array($user)) {
             $query .= ' (1 = 0';  //tricks
-            foreach($user as $u) {
-                $query .= ' OR B.uId = '. $this->db->sql_escape($u) .' AND B.bId = T.bId';
+            foreach ($user as $u) {
+                if (is_numeric($u)) {
+                    $query .= ' OR B.uId = ' . $this->db->sql_escape($u)
+                        . ' AND B.bId = T.bId';
+                }
             }
-            $query .= ' )';
+            $query .= ' )' . $privacy;
         } else {
-            $query .= 'B.uId = '. $this->db->sql_escape($user) .' AND B.bId = T.bId'. $privacy;
+            $query .= ' B.uId = ' . $this->db->sql_escape($user)
+                . ' AND B.bId = T.bId' . $privacy;
         }
-        $query .= $span .' AND LEFT(T.tag, 7) <> "system:" GROUP BY T.tag ORDER BY bCount DESC, tag';
 
-        if (!($dbresult =& $this->db->sql_query_limit($query, $limit))) {
-            message_die(GENERAL_ERROR, 'Could not get popular tags', '', __LINE__, __FILE__, $query, $this->db);
+        if (is_int($days)) {
+            $query .= ' AND B.bDatetime > "'
+                . date('Y-m-d H:i:s', time() - (86400 * $days))
+                . '"';
+        }
+
+        if (!is_null($beginsWith)) {
+            $query .= ' AND T.tag LIKE \''
+                . $this->db->sql_escape($beginsWith)
+                . '%\'';
+        }
+
+        $query .= ' AND LEFT(T.tag, 7) <> "system:"'
+            . ' GROUP BY T.tag'
+            . ' ORDER BY bCount DESC, tag';
+
+        if (!($dbresult = $this->db->sql_query_limit($query, $limit))) {
+            message_die(
+                GENERAL_ERROR, 'Could not get popular tags',
+                '', __LINE__, __FILE__, $query, $this->db
+            );
             return false;
         }
 
@@ -514,6 +611,8 @@ class SemanticScuttle_Service_Bookmark2Tag extends SemanticScuttle_DbService
         return $output;
     }
 
+
+
     function hasTag($bookmarkid, $tag) {
         $query = 'SELECT COUNT(*) AS tCount FROM '. $this->getTableName() .' WHERE bId = '. intval($bookmarkid) .' AND tag ="'. $this->db->sql_escape($tag) .'"';
 
@@ -592,7 +691,15 @@ class SemanticScuttle_Service_Bookmark2Tag extends SemanticScuttle_DbService
         return $output;
     }
 
-    function deleteAll() {
+
+
+    /**
+     * Deletes all tags in bookmarks2tags
+     *
+     * @return void
+     */
+    public function deleteAll()
+    {
         $query = 'TRUNCATE TABLE `'. $this->getTableName() .'`';
         $this->db->sql_query($query);
     }
diff --git a/src/SemanticScuttle/Service/Factory.php b/src/SemanticScuttle/Service/Factory.php
index d7ff1d4..b661cdb 100644
--- a/src/SemanticScuttle/Service/Factory.php
+++ b/src/SemanticScuttle/Service/Factory.php
@@ -107,6 +107,7 @@ class SemanticScuttle_Service_Factory
 
     /**
      * Loads self::$db if it is not loaded already.
+     * Dies if the connection could not be established.
      *
      * @return void
      */
@@ -141,7 +142,7 @@ class SemanticScuttle_Service_Factory
     /**
      * Returns sql database object
      *
-     * @return void
+     * @return sql_db Database instance
      */
     public static function getDb()
     {
diff --git a/src/SemanticScuttle/Service/Tag2Tag.php b/src/SemanticScuttle/Service/Tag2Tag.php
index 8666209..33d211b 100644
--- a/src/SemanticScuttle/Service/Tag2Tag.php
+++ b/src/SemanticScuttle/Service/Tag2Tag.php
@@ -14,7 +14,7 @@
  */
 
 /**
- * SemanticScuttle tag-to-tag service.
+ * SemanticScuttle tag-to-tag service which works with tag relations.
  *
  * @category Bookmarking
  * @package  SemanticScuttle
@@ -102,18 +102,49 @@ class SemanticScuttle_Service_Tag2Tag extends SemanticScuttle_DbService
         return true;
     }
 
-    // Return linked tags just for admin users
-    function getAdminLinkedTags($tag, $relationType, $inverseRelation = false, $stopList = array()) {
+
+
+    /**
+     * Same as getLinkedTags(), but only tags that have been created
+     * by admin users are returned.
+     *
+     * @param string  $tag             Tag to get related tags for
+     * @param string  $relationType    Type of tag-to-tag relation: >, < or =
+     * @param boolean $inverseRelation Reverse relation (parent -> child)
+     * @param array   $stopList        Array of tags that shall not be returned
+     *
+     * @return array Array of tag names
+     *
+     * @see getLinkedTags()
+     */
+    public function getAdminLinkedTags(
+        $tag, $relationType, $inverseRelation = false, $stopList = array()
+    ) {
         // look for admin ids
         $userservice = SemanticScuttle_Service_Factory :: get('User');
-        $adminIds = $userservice->getAdminIds();
+        $adminIds    = $userservice->getAdminIds();
 
         //ask for their linked tags
-        return $this->getLinkedTags($tag, $relationType, $adminIds, $inverseRelation, $stopList);
+        return $this->getLinkedTags(
+            $tag, $relationType, $adminIds, $inverseRelation, $stopList
+        );
     }
 
-    // Return the target linked tags. If inverseRelation is true, return the source linked tags.
-    function getLinkedTags($tag, $relationType, $uId = null, $inverseRelation = false, $stopList = array()) {
+
+
+    /**
+     * Returns an array of tags that are in relation to the given $tag.
+     *
+     * @param string  $tag             Tag to get related tags for
+     * @param string  $relationType    Type of tag-to-tag relation: >, < or =
+     * @param boolean $inverseRelation Reverse relation (parent -> child)
+     * @param array   $stopList        Array of tags that shall not be returned
+     *
+     * @return array Array of tag names
+     */
+    public function getLinkedTags(
+        $tag, $relationType, $uId = null, $inverseRelation = false, $stopList = array()
+    ) {
         // Set up the SQL query.
         if($inverseRelation) {
             $queriedTag = "tag1";
diff --git a/src/SemanticScuttle/Service/User.php b/src/SemanticScuttle/Service/User.php
index 7f0624e..9ef8430 100644
--- a/src/SemanticScuttle/Service/User.php
+++ b/src/SemanticScuttle/Service/User.php
@@ -203,18 +203,26 @@ class SemanticScuttle_Service_User extends SemanticScuttle_DbService
         }
     }
 
-    /* Takes an numerical "id" or a string "username"
-     and returns the numerical "id" if the user exists else returns NULL */
-    function getIdFromUser($user) {
+    /**
+     * Obtains the ID of the given user name.
+     * If a user ID is passed, it is returned.
+     * In case the user does not exist, NULL is returned.
+     *
+     * @param string|integer $user User name or user ID
+     *
+     * @return integer NULL if not found or the user ID
+     */
+    public function getIdFromUser($user)
+    {
         if (is_int($user)) {
             return intval($user);
         } else {
             $objectUser = $this->getObjectUserByUsername($user);
-            if($objectUser != NULL) {
+            if ($objectUser != null) {
                 return $objectUser->getId();
             }
         }
-        return NULL;
+        return null;
     }
 
     /**