add docs, rewrite part of the notification api

list notifications and set note as seen functionalities are now
splitted in two functions, with correct http method requirement.

Fixed returned value from `notification/seen`

include/NotificationsManager.php

@@ -1,6 +1,13 @@
 <?php
+/**
+ * @file include/NotificationsManager.php
+ */
 require_once("include/datetime.php");
+require_once("include/bbcode.php");
 
+/**
+ * @brief Read and write notifications from/to database
+ */
 class NotificationsManager {
     private $a;
     
@@ -8,12 +15,27 @@ class NotificationsManager {
         $this->a = get_app();
     }
     
+	/**
+	 * @brief set some extra note properties
+	 *
+	 * @param array $notes array of note arrays from db
+	 * @return array Copy of input array with added properties
+	 * 
+	 * Set some extra properties to note array from db:
+	 *  - timestamp as int in default TZ
+	 *  - date_rel : relative date string
+	 *  - msg_html: message as html string
+	 *  - msg_plain: message as plain text string
+	 */
     private function _set_extra($notes) {
         $rets = array();
         foreach($notes as $n) {
             $local_time = datetime_convert('UTC',date_default_timezone_get(),$n['date']);
             $n['timestamp'] = strtotime($local_time);
             $n['date_rel'] = relative_date($n['date']);
+			$n['msg_html'] = bbcode($n['msg'], false, false, false, false);
+			$n['msg_plain'] = explode("\n",trim(html2plain($n['msg_html'], 0)))[0];
+			
             $rets[] = $n;
         }
         return $rets;
@@ -57,7 +79,7 @@ class NotificationsManager {
         
         if ($limit!="") $limit = " LIMIT ".$limit;
         
-		$r = q("SELECT * from notify where uid = %d $filter_sql order by $order_sql $limit",
+		$r = q("SELECT * FROM notify WHERE uid = %d $filter_sql ORDER BY $order_sql $limit",
 			intval(local_user())
 		);
         if ($r!==false && count($r)>0) return $this->_set_extra($r);
@@ -71,7 +93,7 @@ class NotificationsManager {
      * @return array note values or null if not found
      */
     public function getByID($id) {
-        $r = q("select * from notify where id = %d and uid = %d limit 1",
+        $r = q("SELECT * FROM notify WHERE id = %d AND uid = %d LIMIT 1",
                 intval($id),
                 intval(local_user())
         );
@@ -89,7 +111,7 @@ class NotificationsManager {
      * @return bool true on success, false on errors
      */
     public function setSeen($note, $seen = true) {
-        return q("update notify set seen = %d where ( link = '%s' or ( parent != 0 and parent = %d and otype = '%s' )) and uid = %d",
+        return q("UPDATE notify SET seen = %d WHERE ( link = '%s' OR ( parent != 0 AND parent = %d AND otype = '%s' )) AND uid = %d",
             intval($seen),
             dbesc($note['link']),
             intval($note['parent']),
@@ -105,7 +127,7 @@ class NotificationsManager {
      * @return bool true on success, false on error
      */
     public function setAllSeen($seen = true) {
-    	return q("update notify set seen = %d where uid = %d",
+    	return q("UPDATE notify SET seen = %d WHERE uid = %d",
             intval($seen),
 			intval(local_user())
 		);

include/api.php

@@ -690,6 +690,11 @@
 	function api_array_to_xml($data, $ename="") {
 		$attrs="";
 		$childs="";
+		if (count($data)==1 && !is_array($data[0])) {
+			$ename = array_keys($data)[0];
+			$v = $data[$ename];
+			return "<$ename>$v</$ename>";
+		}
 		foreach($data as $k=>$v) {
 			$k=trim($k,'$');
 			if (!is_array($v)) {
@@ -3415,42 +3420,63 @@
 	api_register_func('api/friendica/activity/unattendmaybe', 'api_friendica_activity', true, API_METHOD_POST);
 
 	/**
-	 * returns notifications
+	 * @brief Returns notifications
-	 * if called with note id set note seen and returns associated item (if possible)
+	 *
-	 */
+	 * @param App $a
+	 * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
+	 * @return string
+	*/
 	function api_friendica_notification(&$a, $type) {
 		if (api_user()===false) throw new ForbiddenException();
-		
+		if ($a->argc!==3) throw new BadRequestException("Invalid argument count");
 		$nm = new NotificationsManager();
 		
-		if ($a->argc==3) {
+		$notes = $nm->getAll(array(), "+seen -date", 50);
-			$notes = $nm->getAll(array(), "+seen -date", 50);
+		return api_apply_template("<auto>", $type, array('$notes' => $notes));
-			return api_apply_template("<auto>", $type, array('$notes' => $notes));
+	}
-		}
+	
-		if ($a->argc==4) {
+	/**
-			$note = $nm->getByID(intval($a->argv[3]));
+	 * @brief Set notification as seen and returns associated item (if possible)
-			if (is_null($note)) throw new BadRequestException("Invalid argument");
+	 *
-			$nm->setSeen($note);
+	 * POST request with 'id' param as notification id
-			if ($note['otype']=='item') {
+	 * 
-				// would be really better with a ItemsManager and $im->getByID() :-P
+	 * @param App $a
-				$r = q("SELECT * FROM item WHERE id=%d AND uid=%d",
+	 * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
-					intval($note['iid']),
+	 * @return string
-					intval(local_user())
+	 */
-				);
+	function api_friendica_notification_seen(&$a, $type){
-				if ($r===false) throw new NotFoundException();
+		if (api_user()===false) throw new ForbiddenException();
+		if ($a->argc!==4) throw new BadRequestException("Invalid argument count");
+		
+		$id = (x($_REQUEST, 'id') ? intval($_REQUEST['id']) : 0);
+		
+		$nm = new NotificationsManager();		
+		$note = $nm->getByID($id);
+		if (is_null($note)) throw new BadRequestException("Invalid argument");
+		
+		$nm->setSeen($note);
+		if ($note['otype']=='item') {
+			// would be really better with an ItemsManager and $im->getByID() :-P
+			$r = q("SELECT * FROM item WHERE id=%d AND uid=%d",
+				intval($note['iid']),
+				intval(local_user())
+			);
+			if ($r!==false) {
+				// we found the item, return it to the user
 				$user_info = api_get_user($a);
 				$ret = api_format_items($r,$user_info);
 				$data = array('$statuses' => $ret);
 				return api_apply_template("timeline", $type, $data);
-			} else {
-				return api_apply_template('test', $type, array('ok' => $ok));
 			}
-			
+			// the item can't be found, but we set the note as seen, so we count this as a success
 		} 
-		throw new BadRequestException("Invalid argument count");
+		return api_apply_template('<auto>', $type, array('status' => "success"));
 	}
+	
+	api_register_func('api/friendica/notification/seen', 'api_friendica_notification_seen', true, API_METHOD_POST);
 	api_register_func('api/friendica/notification', 'api_friendica_notification', true, API_METHOD_GET);
 	
+
 /*
 To.Do:
     [pagename] => api/1.1/statuses/lookup.json