merge master

4 files changed, 207 insertions, 83 deletions

diff --git a/www/api/httpauth.inc.php b/www/api/httpauth.inc.php
index 0e3a66d..ee5c7f2 100644
--- a/www/api/httpauth.inc.php
+++ b/www/api/httpauth.inc.php
@@ -1,10 +1,29 @@
 <?php
+/**
+ * Checks if the user is logged on and sends a HTTP basic auth
+ * request to the browser if not. In that case the script ends.
+ * If username and password are available, the user service's
+ * login method is used to log the user in.
+ *
+ * SemanticScuttle - your social bookmark manager.
+ *
+ * PHP version 5.
+ *
+ * @category Bookmarking
+ * @package  SemanticScuttle
+ * @author   Benjamin Huynh-Kim-Bang <mensonge@users.sourceforge.net>
+ * @author   Christian Weiske <cweiske@cweiske.de>
+ * @author   Eric Dane <ericdane@users.sourceforge.net>
+ * @license  GPL http://www.gnu.org/licenses/gpl.html
+ * @link     http://sourceforge.net/projects/semanticscuttle
+ */
 require_once '../www-header.php';
 
-// Provides HTTP Basic authentication of a user
-// and logs the user in if necessary
-
-function authenticate() {
+/**
+ * Sends HTTP auth headers to the browser
+ */
+function authenticate()
+{
 	header('WWW-Authenticate: Basic realm="SemanticScuttle API"');
 	header('HTTP/1.0 401 Unauthorized');
 
@@ -26,7 +45,9 @@ if (!$userservice->isLoggedOn()) {
     if (!isset($_SERVER['PHP_AUTH_USER'])) {
         authenticate();
     } else {
-        $login = $userservice->login($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']);
+        $login = $userservice->login(
+            $_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']
+        );
         if ($login) {
             $currentUser = $userservice->getCurrentObjectUser();
         } else {
diff --git a/www/api/posts_add.php b/www/api/posts_add.php
index 59f7dce..7f9dc59 100644
--- a/www/api/posts_add.php
+++ b/www/api/posts_add.php
@@ -1,67 +1,105 @@
 <?php
-// Implements the del.icio.us API request to add a new post.
-// http://delicious.com/help/api#posts_add
-
-// del.icio.us behavior:
-// - tags can't have spaces
-// - address and description are mandatory
-
-// Scuttle behavior:
-// - Additional 'status' variable for privacy
-// - No support for 'replace' variable
+/**
+ * API for adding a new bookmark.
+ *
+ * The following POST and GET parameters are accepted:
+ * @param string  $url         URL of the bookmark (required)
+ * @param string  $description Bookmark title (required)
+ * @param string  $extended    Extended bookmark description (optional)
+ * @param string  $tags        Space-separated list of tags (optional)
+ * @param string  $dt          Date and time of bookmark creation (optional)
+ *                             Must be of format YYYY-MM-DDTHH:II:SSZ
+ * @param integer $status      Visibility status (optional):
+ *                             - 2 or 'private': Bookmark is totally private
+ *                             - 1 or 'shared': People on the user's watchlist
+ *                                              can see it
+ *                             - 0 or 'public': Everyone can see the bookmark
+ * @param string  $shared      "no" or "yes": Switches between private and
+ *                             public (optional)
+ * @param string  $replace     "yes" or "no" - replaces a bookmark with the
+ *                             same URL (optional)
+ *
+ * Notes:
+ * - tags cannot have spaces
+ * - URL and description (title) are mandatory
+ * - delicious "description" is the "title" in SemanticScuttle
+ * - delicious "extended" is the "description" in SemanticScuttle
+ * - "status" is a SemanticScuttle addition to this API method
+ *
+ * SemanticScuttle - your social bookmark manager.
+ *
+ * PHP version 5.
+ *
+ * @category Bookmarking
+ * @package  SemanticScuttle
+ * @author   Benjamin Huynh-Kim-Bang <mensonge@users.sourceforge.net>
+ * @author   Christian Weiske <cweiske@cweiske.de>
+ * @author   Eric Dane <ericdane@users.sourceforge.net>
+ * @license  GPL http://www.gnu.org/licenses/gpl.html
+ * @link     http://sourceforge.net/projects/semanticscuttle
+ * @link     http://www.delicious.com/help/api
+ */
 
 // Force HTTP authentication
 $httpContentType = 'text/xml';
 require_once 'httpauth.inc.php';
 
-/* Service creation: only useful services are created */
-$bookmarkservice =SemanticScuttle_Service_Factory::get('Bookmark');
+$bs = SemanticScuttle_Service_Factory::get('Bookmark');
 
 // Get all the bookmark's passed-in information
-if (isset($_REQUEST['url']) && (trim($_REQUEST['url']) != ''))
+if (isset($_REQUEST['url']) && (trim($_REQUEST['url']) != '')) {
     $url = trim(urldecode($_REQUEST['url']));
-else
-    $url = NULL;
+} else {
+    $url = null;
+}
 
-if (isset($_REQUEST['description']) && (trim($_REQUEST['description']) != ''))
+if (isset($_REQUEST['description']) && (trim($_REQUEST['description']) != '')) {
     $description = trim($_REQUEST['description']);
-else
-    $description = NULL;
+} else {
+    $description = null;
+}
 
-if (isset($_REQUEST['extended']) && (trim($_REQUEST['extended']) != ""))
+if (isset($_REQUEST['extended']) && (trim($_REQUEST['extended']) != '')) {
     $extended = trim($_REQUEST['extended']);
-else
-    $extended = NULL;
+} else {
+    $extended = null;
+}
 
-if (isset($_REQUEST['tags']) && (trim($_REQUEST['tags']) != '') && (trim($_REQUEST['tags']) != ','))
+if (isset($_REQUEST['tags']) && (trim($_REQUEST['tags']) != '')
+    && (trim($_REQUEST['tags']) != ',')
+) {
     $tags = trim($_REQUEST['tags']);
-else
-    $tags = NULL;
+} else {
+    $tags = null;
+}
 
-if (isset($_REQUEST['dt']) && (trim($_REQUEST['dt']) != ''))
+if (isset($_REQUEST['dt']) && (trim($_REQUEST['dt']) != '')) {
     $dt = trim($_REQUEST['dt']);
-else
-    $dt = NULL;
+} else {
+    $dt = null;
+}
+
+$replace = isset($_REQUEST['replace']) && ($_REQUEST['replace'] == 'yes');
 
 $status = 0;
 if (isset($_REQUEST['status'])) {
     $status_str = trim($_REQUEST['status']);
     if (is_numeric($status_str)) {
         $status = intval($status_str);
-        if($status < 0 || $status > 2) {
+        if ($status < 0 || $status > 2) {
             $status = 0;
         }
     } else {
         switch ($status_str) {
-            case 'private':
-                $status = 2;
-                break;
-            case 'shared':
-                $status = 1;
-                break;
-            default:
-                $status = 0;
-                break;
+        case 'private':
+            $status = 2;
+            break;
+        case 'shared':
+            $status = 1;
+            break;
+        default:
+            $status = 0;
+            break;
         }
     }
 }
@@ -71,17 +109,38 @@ if (isset($_REQUEST['shared']) && (trim($_REQUEST['shared']) == 'no')) {
 }
 
 // Error out if there's no address or description
-if (is_null($url) || is_null($description)) {
-    $added = false;
+if (is_null($url)) {
+    header('HTTP/1.0 400 Bad Request');
+    $msg = 'URL missing';
+} else if (is_null($description)) {
+    header('HTTP/1.0 400 Bad Request');
+    $msg = 'Description missing';
 } else {
-// We're good with info; now insert it!
-    if ($bookmarkservice->bookmarkExists($url, $userservice->getCurrentUserId()))
-        $added = false;
-    else
-        $added = $bookmarkservice->addBookmark($url, $description, $extended, '', $status, $tags, null, $dt, true);
+    // We're good with info; now insert it!
+    $exists = $bs->bookmarkExists($url, $userservice->getCurrentUserId());
+    if ($exists) {
+        if (!$replace) {
+            header('HTTP/1.0 409 Conflict');
+            $msg = 'bookmark does already exist';
+        } else {
+            //delete it before we re-add it
+            $bookmark = $bs->getBookmarkByAddress($url, false);
+            $bId      = $bookmark['bId'];
+            $bs->deleteBookmark($bId);
+
+            $exists = false;
+        }
+    }
+
+    if (!$exists) {
+        $added = $bs->addBookmark(
+            $url, $description, $extended, '', $status, $tags, null, $dt, true
+        );
+        $msg = 'done';
+    }
 }
 
 // Set up the XML file and output the result.
-echo '<?xml version="1.0" standalone="yes" ?'.">\r\n";
-echo '<result code="'. ($added ? 'done' : 'something went wrong') .'" />';
+echo '<?xml version="1.0" standalone="yes" ?' . ">\r\n";
+echo '<result code="' . $msg .'" />';
 ?>
\ No newline at end of file
diff --git a/www/api/posts_delete.php b/www/api/posts_delete.php
index a63cc62..69b2429 100644
--- a/www/api/posts_delete.php
+++ b/www/api/posts_delete.php
@@ -1,33 +1,57 @@
 <?php
-// Implements the del.icio.us API request to delete a post.
-
-// del.icio.us behavior:
-// - returns "done" even if the bookmark doesn't exist;
-// - does NOT allow the hash for the url parameter;
-// - doesn't set the Content-Type to text/xml (we do).
+/**
+ * API for deleting a bookmark.
+ * The delicious API is implemented here.
+ *
+ * The delicious API behaves like that:
+ * - does NOT allow the hash for the url parameter
+ * - doesn't set the Content-Type to text/xml
+ *   - we do it correctly, too
+ *
+ * SemanticScuttle - your social bookmark manager.
+ *
+ * PHP version 5.
+ *
+ * @category Bookmarking
+ * @package  SemanticScuttle
+ * @author   Benjamin Huynh-Kim-Bang <mensonge@users.sourceforge.net>
+ * @author   Christian Weiske <cweiske@cweiske.de>
+ * @author   Eric Dane <ericdane@users.sourceforge.net>
+ * @license  GPL http://www.gnu.org/licenses/gpl.html
+ * @link     http://sourceforge.net/projects/semanticscuttle
+ * @link     http://www.delicious.com/help/api
+ */
 
 // Force HTTP authentication first!
 $httpContentType = 'text/xml';
 require_once 'httpauth.inc.php';
 
-/* Service creation: only useful services are created */
-$bookmarkservice =SemanticScuttle_Service_Factory::get('Bookmark');
-
+$bs  = SemanticScuttle_Service_Factory::get('Bookmark');
+$uId = $userservice->getCurrentUserId();
 
-// Note that del.icio.us only errors out if no URL was passed in; there's no error on attempting
-// to delete a bookmark you don't have.
 
 // Error out if there's no address
-if (is_null($_REQUEST['url'])) {
-    $deleted = false;
+if (!isset($_REQUEST['url'])
+    || $_REQUEST['url'] == ''
+) {
+    $msg = 'something went wrong';
+} else if (!$bs->bookmarkExists($_REQUEST['url'], $uId)) {
+    //the user does not have such a bookmark
+    header('HTTP/1.0 404 Not Found');
+    $msg = 'item not found';
 } else {
-    $bookmark = $bookmarkservice->getBookmarkByAddress($_REQUEST['url']);
-    $bid = $bookmark['bId'];
-    $delete = $bookmarkservice->deleteBookmark($bid);
-    $deleted = true;
+    $bookmark = $bs->getBookmarkByAddress($_REQUEST['url'], false);
+    $bId      = $bookmark['bId'];
+    $deleted  = $bs->deleteBookmark($bId);
+    $msg      = 'done';
+    if (!$deleted) {
+        //something really went wrong
+        header('HTTP/1.0 500 Internal Server Error');
+        $msg = 'something really went wrong';
+    }
 }
 
 // Set up the XML file and output the result.
-echo '<?xml version="1.0" standalone="yes" ?'.">\r\n";
-echo '<result code="'. ($deleted ? 'done' : 'something went wrong') .'" />';
+echo '<?xml version="1.0" standalone="yes" ?' . ">\r\n";
+echo '<result code="' . $msg . '" />';
 ?>
\ No newline at end of file
diff --git a/www/api/posts_update.php b/www/api/posts_update.php
index 4aeedc3..4b080e2 100644
--- a/www/api/posts_update.php
+++ b/www/api/posts_update.php
@@ -1,24 +1,44 @@
 <?php
-// Implements the del.icio.us API request for a user's last update time and date.
-
-// del.icio.us behavior:
-// - doesn't set the Content-Type to text/xml (we do).
+/**
+ * API for retrieving a user's last update time.
+ * That is the time the user changed a bookmark lastly.
+ * The delicious API is implemented here.
+ *
+ * Delicious also returns "the number of new items in
+ *  the user's inbox since it was last visited." - we do
+ * that too, so we are as close at the API as possible,
+ * not breaking delicious clients.
+ *
+ * SemanticScuttle - your social bookmark manager.
+ *
+ * PHP version 5.
+ *
+ * @category Bookmarking
+ * @package  SemanticScuttle
+ * @author   Benjamin Huynh-Kim-Bang <mensonge@users.sourceforge.net>
+ * @author   Christian Weiske <cweiske@cweiske.de>
+ * @author   Eric Dane <ericdane@users.sourceforge.net>
+ * @license  GPL http://www.gnu.org/licenses/gpl.html
+ * @link     http://sourceforge.net/projects/semanticscuttle
+ * @link     http://www.delicious.com/help/api
+ */
 
 // Force HTTP authentication first!
 $httpContentType = 'text/xml';
 require_once 'httpauth.inc.php';
 
-/* Service creation: only useful services are created */
-$bookmarkservice =SemanticScuttle_Service_Factory::get('Bookmark');
-
-
-// Get the posts relevant to the passed-in variables.
-$bookmarks =& $bookmarkservice->getBookmarks(0, 1, $userservice->getCurrentUserId());
+$bs = SemanticScuttle_Service_Factory::get('Bookmark');
 
+$bookmarks = $bs->getBookmarks(0, 1, $userservice->getCurrentUserId());
 
 // Set up the XML file and output all the tags.
-echo '<?xml version="1.0" standalone="yes" ?'.">\r\n";
-foreach($bookmarks['bookmarks'] as $row) {
-    echo '<update time="'. gmdate('Y-m-d\TH:i:s\Z', strtotime($row['bDatetime'])) .'" />';
+echo '<?xml version="1.0" standalone="yes" ?' . ">\r\n";
+//foreach is used in case there are no bookmarks
+foreach ($bookmarks['bookmarks'] as $row) {
+    echo '<update time="'
+        . gmdate('Y-m-d\TH:i:s\Z', strtotime($row['bDatetime']))
+        . '"'
+        . ' inboxnew="0"'
+        . ' />';
 }
 ?>
\ No newline at end of file