Clean up some exceptions, phpdoc

Lib/Exception/AuthenticationException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace BSR\Lib\Exception;
+
+/**
+ * This exception should be raised when an error
+ * related to the authentication mechanism arise.
+ *
+ * @package BSR\Lib\Exception
+ */
+class AuthenticationException extends WebException {
+    const USER_NOT_FOUND = 200;
+    const BAD_LOGIN = 201;
+    const AUTHENTICATION_FAILED = 202;
+}

Lib/Exception/BookNotFoundException.php

@@ -2,8 +2,14 @@
 
 namespace BSR\Lib\Exception;
 
+/**
+ * This exception should be raised when trying to access or
+ * manipulate a non-existing book.
+ *
+ * @package BSR\Lib\Exception
+ */
 class BookNotFoundException extends WebException {
     public function __construct($code) {
-        parent::__construct('BookNotFound', "The book with code $code was not found", -404);
+        parent::__construct('BookNotFound', "The book with code $code was not found.", 404);
     }
 }

Lib/Exception/UsageException.php

@@ -2,4 +2,18 @@
 
 namespace BSR\Lib\Exception;
 
-class UsageException extends WebException {}
+/**
+ * This exception should be raised by the WebService engine when
+ * there is an error preventing the correct calling of a method.
+ *
+ * @package BSR\Lib\Exception
+ */
+class UsageException extends WebException {
+    const NO_ARGS = 100;
+
+    const MISSING_METHOD = 101;
+    const BAD_METHOD = 102;
+
+    const TOO_FEW_ARGS = 103;
+    const TOO_MANY_ARGS = 104;
+}

Lib/WebService.php

@@ -74,18 +74,18 @@ abstract class WebService
 
         $params = empty($_GET) ? $_POST : $_GET;
         if (empty($params)) {
-            throw new UsageException("CallArgument", "arguments error", -1);
+            throw new UsageException("NoArguments", "No arguments specified.", UsageException::NO_ARGS);
         }
 
         if (!array_key_exists("func", $params)) {
-            throw new UsageException("CallArgFunction", "no 'func' specified", -2);
+            throw new UsageException("MissingMethod", "No method specified.", UsageException::MISSING_METHOD);
         }
 
         $this->func = $params["func"];
         unset($params['func']);
 
         if (!is_callable(array($this, $this->func))) {
-            throw new UsageException("CallFunction", "'func' method not available", -3);
+            throw new UsageException("BadMethod", "Method {$this->func} does not exists.", UsageException::BAD_METHOD);
         }
 
         $rm = new \ReflectionMethod($this, $this->func);
@@ -95,10 +95,10 @@ abstract class WebService
 
         /* Check the number of arguments. */
         if ($nbParams < $nbArgsFix) {
-            throw new UsageException("CallArgNumber", "you must provide at least " . $nbArgsFix . " arguments", 4);
+            throw new UsageException("TooManyArgs", "You must provide at least $nbArgsFix arguments.", UsageException::TOO_MANY_ARGS);
         }
         if ($nbParams > $nbArgs) {
-            throw new UsageException("CallArgNumber", "you must provide at most " . $nbArgs . " arguments", 4);
+            throw new UsageException("TooFewArgs", "You must provide at most $nbArgs arguments.", UsageException::TOO_FEW_ARGS);
         }
 
         $this->log("Calling '".$this->func."'");

NetBiblio.php

@@ -6,6 +6,7 @@ use BSR\Lib\Configuration;
 use BSR\Lib\db\AudioBook;
 use BSR\Lib\db\Connection;
 use BSR\Lib\db\User;
+use BSR\Lib\Exception\AuthenticationException;
 use BSR\Lib\Exception\WebException;
 use BSR\Lib\Search\BookSearch;
 use BSR\Lib\WebService;
@@ -15,44 +16,53 @@ class NetBiblio extends WebService
     private $login = '';
     private $client = 'website';
 
-
-    private function CheckSession($login = null, $client = null)
+    /**
+     * Set the current login and client based on information
+     * from the session.
+     */
+    private function CheckSession()
     {
         if (! isset ($_SESSION["user"]["login"])) {
             return;
         }
 
-        if(!$client) {
-            $client = isset($_SESSION["user"]["client"]) ? $_SESSION["user"]["client"] : 'website';
-        }
-
-        if (!$login) {
-            $login = $_SESSION["user"]["login"];
-        } else if ($_SESSION["user"]["login"] !== $login) {
-            throw new WebException ("CheckSessionBadAuth", "bad authentication", -1001);
-        }
-
-        $this->login = $login;
-        $this->client = $client;
+        $this->login = $_SESSION["user"]["login"];
+        $this->client = isset($_SESSION["user"]["client"]) ? $_SESSION["user"]["client"] : 'website';
     }
 
+    /**
+     * Retrieve information about the curent user from the database.
+     * If a username is given, first validate that it is the same
+     * currently in the session.
+     *
+     * @param string|null $login
+     * @return User
+     * @throws AuthenticationException
+     */
     private function getUser($login = null)
     {
-        if (!$login) {
-            $login = $_SESSION["user"]["login"];
+        if(! is_null($login) && $_SESSION["user"]["login"] !== $login) {
+            throw new AuthenticationException("BadLogin", "Login '$login' is invalid.'", AuthenticationException::BAD_LOGIN);
         }
 
-        $this->checkSession($login);
+        $this->checkSession();
+
         $user = User::find($this->login);
 
         if (!$user) {
-            throw new WebException ("UserNotFound", "cannot find account", -130);
+            throw new AuthenticationException("UserNotFound", "No user found for '{$this->login}.", AuthenticationException::USER_NOT_FOUND);
         }
 
         return $user;
     }
 
-
+    /**
+     * Retrive books from Solr based on their code (NoticeNr).
+     *
+     * @param array $codes
+     * @return array Books information
+     * @throws WebException
+     */
     private function GetBooks(array $codes) {
         $bs = new BookSearch();
         $bs->addQuery('code:('.implode(' OR ', $codes).')', null, false);
@@ -60,13 +70,22 @@ class NetBiblio extends WebService
         return $results['books'];
     }
 
-    private function GetFiles(array $ids)
+    /**
+     * Retrieve file information (samples and zip) for a list of books based
+     * on their code (NoticeNr).
+     * This should be called only if those information are not already in Solr
+     * for the given books.
+     *
+     * @param array $ids
+     * @return array File information indexed by book code
+     */
+    private function GetFiles(array $codes)
     {
-        $ids = array_map('intval', $ids);
+        $ids = array_map('intval', $codes);
 
         $uri = sprintf("%s%s",
             Configuration::get('checkfile_url'),
-            http_build_query(array("book" => implode(',', $ids)))
+            http_build_query(array("book" => implode(',', $codes)))
         );
 
         $ch = curl_init($uri);
@@ -78,6 +97,12 @@ class NetBiblio extends WebService
         return json_decode($json, true);
     }
 
+    /**
+     * Save files information (samples and zip) for books into Solr
+     * based on their id (NoticeId).
+     *
+     * @param $files
+     */
     private function SetFiles($files) {
         $json = json_encode(array_values(array_map(function($f) {
             return array(
@@ -106,6 +131,18 @@ class NetBiblio extends WebService
         curl_close($ch);
     }
 
+    /**
+     * Add some information to each books :
+     * 1° File information if not already their (@see GetFiles),
+     *    those information are then saved into Solr (@see SetFiles)
+     * 2° Correctly set hash on zip file to authenticate download
+     * 3° Compatibility fields for mobile apps
+     *
+     * You can pass either a single book or an array of books.
+     *
+     * @param array $books either one or a list of books
+     * @return array either one or a list of books
+     */
     private function AddBookData(array $books)
     {
         if(isset($books['code'])) {
@@ -294,7 +331,7 @@ class NetBiblio extends WebService
         $user = User::authenticate($login, $password);
 
         if (! $user) {
-            throw new WebException ("AuthenticateBad", "authentication failed", -100);
+            throw new AuthenticationException("AuthenticationFailed", "Invalid login or password.", AuthenticationException::AUTHENTICATION_FAILED);
         }
 
         $_SESSION["user"]["login"] = $login;