Added documentation, some indention fixes

diff --git a/include/api.php b/include/api.php
index 4cc9826c463af7dab0a744fdcea69e0842ab7570..256d0431c6692a869e11484b96972ea1cd4aed5f 100644 (file)
--- a/include/api.php
+++ b/include/api.php
@@ -1615,18 +1615,18 @@ function api_search($type)
 
        $start = $page * $count;
 
-        $condition = ["`verb` = ? AND `item`.`id` > ?
+       $condition = ["`verb` = ? AND `item`.`id` > ?
                AND (`item`.`uid` = 0 OR (`item`.`uid` = ? AND NOT `item`.`global`))
                AND `item`.`body` LIKE CONCAT('%',?,'%')",
                ACTIVITY_POST, $since_id, api_user(), $_REQUEST['q']];
 
-        if ($max_id > 0) {
-                $condition[0] .= " AND `item`.`id` <= ?";
-                $condition[] = $max_id;
-        }
+       if ($max_id > 0) {
+               $condition[0] .= " AND `item`.`id` <= ?";
+               $condition[] = $max_id;
+       }
 
        $params = ['order' => ['id' => true], 'limit' => [$start, $count]];
-        $statuses = Item::select(api_user(), [], $condition, $params);
+       $statuses = Item::select(api_user(), [], $condition, $params);
 
        $data['status'] = api_format_items(dba::inArray($statuses), $user_info);
 
@@ -1762,30 +1762,30 @@ function api_statuses_public_timeline($type)
                $condition = ["`verb` = ? AND `iid` > ? AND NOT `private` AND `wall` AND NOT `user`.`hidewall`",
                        ACTIVITY_POST, $since_id];
 
-               if ($max_id > 0) {
-                       $condition[0] .= " AND `thread`.`iid` <= ?";
-                       $condition[] = $max_id;
-               }
+               if ($max_id > 0) {
+                       $condition[0] .= " AND `thread`.`iid` <= ?";
+                       $condition[] = $max_id;
+               }
 
-               $params = ['order' => ['iid' => true], 'limit' => [$start, $count]];
-               $statuses = Item::selectThread(api_user(), [], $condition, $params);
+               $params = ['order' => ['iid' => true], 'limit' => [$start, $count]];
+               $statuses = Item::selectThread(api_user(), [], $condition, $params);
 
                $r = dba::inArray($statuses);
        } else {
                $condition = ["`uid` = ? AND `verb` = ? AND `id` > ? AND NOT `user`.`hidewall` AND `item`.`origin`",
                        api_user(), ACTIVITY_POST, $since_id];
 
-               if ($max_id > 0) {
-                       $condition[0] .= " AND `item`.`id` <= ?";
-                       $condition[] = $max_id;
-               }
-               if ($conversation_id > 0) {
-                       $condition[0] .= " AND `item`.`parent` = ?";
-                       $condition[] = $conversation_id;
-               }
+               if ($max_id > 0) {
+                       $condition[0] .= " AND `item`.`id` <= ?";
+                       $condition[] = $max_id;
+               }
+               if ($conversation_id > 0) {
+                       $condition[0] .= " AND `item`.`parent` = ?";
+                       $condition[] = $conversation_id;
+               }
 
-               $params = ['order' => ['id' => true], 'limit' => [$start, $count]];
-               $statuses = Item::select(api_user(), [], $condition, $params);
+               $params = ['order' => ['id' => true], 'limit' => [$start, $count]];
+               $statuses = Item::select(api_user(), [], $condition, $params);
 
                $r = dba::inArray($statuses);
        }
@@ -1838,13 +1838,13 @@ function api_statuses_networkpublic_timeline($type)
        $condition = ["`uid` = 0 AND `verb` = ? AND `thread`.`iid` > ? AND NOT `private`",
                ACTIVITY_POST, $since_id];
 
-        if ($max_id > 0) {
-                $condition[0] .= " AND `thread`.`iid` <= ?";
-                $condition[] = $max_id;
-        }
+       if ($max_id > 0) {
+               $condition[0] .= " AND `thread`.`iid` <= ?";
+               $condition[] = $max_id;
+       }
 
-        $params = ['order' => ['iid' => true], 'limit' => [$start, $count]];
-        $statuses = Item::selectThread(api_user(), [], $condition, $params);
+       $params = ['order' => ['iid' => true], 'limit' => [$start, $count]];
+       $statuses = Item::selectThread(api_user(), [], $condition, $params);
 
        $ret = api_format_items(dba::inArray($statuses), $user_info, false, $type);
 
@@ -2298,7 +2298,7 @@ function api_favorites_create_destroy($type)
                $itemid = intval($_REQUEST['id']);
        }
 
-        $item = Item::selectFirst(api_user(), [], ['id' => $itemid, 'uid' => api_user()]);
+       $item = Item::selectFirst(api_user(), [], ['id' => $itemid, 'uid' => api_user()]);
 
        if (!DBM::is_result($item)) {
                throw new BadRequestException("Invalid item.");
@@ -3180,20 +3180,20 @@ function api_lists_statuses($type)
 
        $start = $page * $count;
 
-        $condition = ["`uid` = ? AND `verb` = ? AND `id` > ? AND `group_member`.`gid` = ?",
+       $condition = ["`uid` = ? AND `verb` = ? AND `id` > ? AND `group_member`.`gid` = ?",
                api_user(), ACTIVITY_POST, $since_id, $_REQUEST['list_id']];
 
-        if ($max_id > 0) {
-                $condition[0] .= " AND `item`.`id` <= ?";
-                $condition[] = $max_id;
-        }
-        if ($exclude_replies > 0) {
-                $condition[0] .= ' AND `item`.`parent` = `item`.`id`';
-        }
-        if ($conversation_id > 0) {
-                $condition[0] .= " AND `item`.`parent` = ?";
-                $condition[] = $conversation_id;
-        }
+       if ($max_id > 0) {
+               $condition[0] .= " AND `item`.`id` <= ?";
+               $condition[] = $max_id;
+       }
+       if ($exclude_replies > 0) {
+               $condition[0] .= ' AND `item`.`parent` = `item`.`id`';
+       }
+       if ($conversation_id > 0) {
+               $condition[0] .= " AND `item`.`parent` = ?";
+               $condition[] = $conversation_id;
+       }
 
        $params = ['order' => ['id' => true], 'limit' => [$start, $count]];
        $statuses = Item::select(api_user(), [], $condition, $params);

diff --git a/src/Model/Item.php b/src/Model/Item.php
index 1a468bfa118d1b6571db73885cb2eaa3316adf3c..e79f3704d3a989205d4eca1d73236c4e2d391c6b 100644 (file)
--- a/src/Model/Item.php
+++ b/src/Model/Item.php
@@ -33,6 +33,17 @@ require_once 'include/text.php';
 
 class Item extends BaseObject
 {
+       /**
+        * Retrieve a single record from the item table and returns it in an associative array
+        *
+        * @brief Retrieve a single record from a table
+        * @param integer $uid User ID
+        * @param array  $fields
+        * @param array  $condition
+        * @param array  $params
+        * @return bool|array
+        * @see dba::select
+        */
        public static function selectFirst($uid, array $fields = [], array $condition = [], $params = [])
        {
                $params['limit'] = 1;
@@ -47,6 +58,16 @@ class Item extends BaseObject
                }
        }
 
+       /**
+        * @brief Select rows from the item table
+        *
+        * @param integer $uid User ID
+        * @param array  $fields    Array of selected fields, empty for all
+        * @param array  $condition Array of fields for condition
+        * @param array  $params    Array of several parameters
+        *
+        * @return boolean|object
+        */
        public static function select($uid, array $selected = [], array $condition = [], $params = [])
        {
                $fields = self::fieldlist();
@@ -57,7 +78,7 @@ class Item extends BaseObject
 
                $condition_string = self::addTablesToFields($condition_string, $fields);
 
-               $condition_string = $condition_string . ' AND ' . self::condition();
+               $condition_string = $condition_string . ' AND ' . self::condition(false);
 
                $param_string = self::addTablesToFields(dba::buildParameter($params), $fields);
 
@@ -68,6 +89,17 @@ class Item extends BaseObject
                return dba::p($sql, $condition);
        }
 
+       /**
+        * Retrieve a single record from the starting post in the item table and returns it in an associative array
+        *
+        * @brief Retrieve a single record from a table
+        * @param integer $uid User ID
+        * @param array  $fields
+        * @param array  $condition
+        * @param array  $params
+        * @return bool|array
+        * @see dba::select
+        */
        public static function selectFirstThread($uid, array $fields = [], array $condition = [], $params = [])
        {
                $params['limit'] = 1;
@@ -82,6 +114,16 @@ class Item extends BaseObject
                }
        }
 
+       /**
+        * @brief Select rows from the starting post in the item table
+        *
+        * @param integer $uid User ID
+        * @param array  $fields    Array of selected fields, empty for all
+        * @param array  $condition Array of fields for condition
+        * @param array  $params    Array of several parameters
+        *
+        * @return boolean|object
+        */
        public static function selectThread($uid, array $selected = [], array $condition = [], $params = [])
        {
                $fields = self::fieldlist();
@@ -98,7 +140,7 @@ class Item extends BaseObject
                $condition_string = self::addTablesToFields($condition_string, $threadfields);
                $condition_string = self::addTablesToFields($condition_string, $fields);
 
-               $condition_string = $condition_string . ' AND ' . self::condition();
+               $condition_string = $condition_string . ' AND ' . self::condition(true);
 
                $param_string = dba::buildParameter($params);
                $param_string = self::addTablesToFields($param_string, $threadfields);
@@ -111,6 +153,11 @@ class Item extends BaseObject
                return dba::p($sql, $condition);
        }
 
+       /**
+        * @brief Returns a list of fields that are associated with the item table
+        *
+        * @return array field list
+        */
        private static function fieldlist()
        {
                $item_fields = ['author-id', 'owner-id', 'contact-id', 'uid', 'id', 'parent',
@@ -137,11 +184,32 @@ class Item extends BaseObject
                        'contact' => $contact_fields, 'event' => $event_fields];
        }
 
-       private static function condition()
+       /**
+        * @brief Returns SQL condition for the "select" functions
+        *
+        * @param boolean $thread_mode Called for the items (false) or for the threads (true)
+        *
+        * @return string SQL condition
+        */
+       private static function condition($thread_mode)
        {
-               return "`item`.`visible` AND NOT `item`.`deleted` AND NOT `item`.`moderated` AND (`user-item`.`hidden` IS NULL OR NOT `user-item`.`hidden`) ";
+               if ($thread_mode) {
+                       $master_table = "`thread`";
+               } else {
+                       $master_table = "`item`";
+               }
+               return "$master_table.`visible` AND NOT $master_table.`deleted` AND NOT $master_table.`moderated` AND (`user-item`.`hidden` IS NULL OR NOT `user-item`.`hidden`) ";
        }
 
+       /**
+        * @brief Returns all needed "JOIN" commands for the "select" functions
+        *
+        * @param integer $uid User ID
+        * @param string $sql_commands The parts of the built SQL commands in the "select" functions
+        * @param boolean $thread_mode Called for the items (false) or for the threads (true)
+        *
+        * @return string The SQL joins for the "select" functions
+        */
        private static function constructJoins($uid, $sql_commands, $thread_mode)
        {
                if ($thread_mode) {
@@ -155,13 +223,13 @@ class Item extends BaseObject
                }
 
                $joins .= sprintf("STRAIGHT_JOIN `contact` ON `contact`.`id` = $master_table.`contact-id`
-                       AND NOT `contact`.`blocked`
-                       AND ((NOT `contact`.`readonly` AND NOT `contact`.`pending` AND (`contact`.`rel` IN (%s, %s)))
-                       OR `contact`.`self` OR (`item`.`id` != `item`.`parent`) OR `contact`.`uid` = 0)
-                       STRAIGHT_JOIN `contact` AS `author` ON `author`.`id` = $master_table.`author-id` AND NOT `author`.`blocked`
-                       STRAIGHT_JOIN `contact` AS `owner` ON `owner`.`id` = $master_table.`owner-id` AND NOT `owner`.`blocked`
-                       LEFT JOIN `user-item` ON `user-item`.`iid` = $master_table_key AND `user-item`.`uid` = %d",
-                       CONTACT_IS_SHARING, CONTACT_IS_FRIEND, intval($uid));
+                       AND NOT `contact`.`blocked`
+                       AND ((NOT `contact`.`readonly` AND NOT `contact`.`pending` AND (`contact`.`rel` IN (%s, %s)))
+                       OR `contact`.`self` OR (`item`.`id` != `item`.`parent`) OR `contact`.`uid` = 0)
+                       STRAIGHT_JOIN `contact` AS `author` ON `author`.`id` = $master_table.`author-id` AND NOT `author`.`blocked`
+                       STRAIGHT_JOIN `contact` AS `owner` ON `owner`.`id` = $master_table.`owner-id` AND NOT `owner`.`blocked`
+                       LEFT JOIN `user-item` ON `user-item`.`iid` = $master_table_key AND `user-item`.`uid` = %d",
+                       CONTACT_IS_SHARING, CONTACT_IS_FRIEND, intval($uid));
 
                if (strpos($sql_commands, "`group_member`.") !== false) {
                        $joins .= " STRAIGHT_JOIN `group_member` ON `group_member`.`contact-id` = $master_table.`contact-id`";
@@ -178,6 +246,14 @@ class Item extends BaseObject
                return $joins;
        }
 
+       /**
+        * @brief Add the field list for the "select" functions
+        *
+        * @param array $fields The field definition array
+        * @param array $selected The array with the selected fields from the "select" functions
+        *
+        * @return string The field list
+        */
        private static function constructSelectFields($fields, $selected)
        {
                $selection = [];
@@ -195,6 +271,14 @@ class Item extends BaseObject
                return implode(", ", $selection);
        }
 
+       /**
+        * @brief add table definition to fields in an SQL query
+        *
+        * @param string $query SQL query
+        * @param array $fields The field definition array
+        *
+        * @return string the changed SQL query
+        */
        private static function addTablesToFields($query, $fields)
        {
                foreach ($fields as $table => $table_fields) {