fix errors in restapi code (and adjust phpdoc as well), fixes #1227

Closes #1227

Merge request studip/studip!739

lib/classes/restapi/ConsumerPermissions.php

@@ -17,7 +17,7 @@ class ConsumerPermissions
      * Permissions object will be cached for each consumer.
      *
      * @param mixed $consumer_id Id of consumer (optional, defaults to global)
-     * @return Permissions Returns permissions object
+     * @return ConsumerPermissions Returns permissions object
      */
     public static function get($consumer_id = null)
     {
@@ -88,7 +88,7 @@ class ConsumerPermissions
     /**
      * Convenience method for activating all routes in a route map.
      *
-     * @param  RESTAPI\RouteMap $routemap RouteMap to activate
+     * @param  \RESTAPI\RouteMap $routemap RouteMap to activate
      */
     public function activateRouteMap(RouteMap $routemap)
     {
@@ -126,7 +126,7 @@ class ConsumerPermissions
     /**
      * Convenience method for deactivating all routes in a route map.
      *
-     * @param RESTAPIRouteMap $routemap RouteMap to activate
+     * @param \RESTAPI\RouteMap $routemap RouteMap to activate
      */
     public function deactivateRouteMap(RouteMap $routemap)
     {
@@ -144,7 +144,7 @@ class ConsumerPermissions
      *
      * @param String $consumer_id Id of the consumer in question
      * @param bool   $overwrite May values be overwritten
-     * @return Permissions Returns instance of self to allow chaining
+     * @return ConsumerPermissions Returns instance of self to allow chaining
      */
     protected function loadPermissions($consumer_id, $overwrite = false)
     {

lib/classes/restapi/Response.php

@@ -41,9 +41,9 @@ class Response implements \ArrayAccess
     /**
      * Finishes the response with the given response renderer.
      *
-     * @param RESTAPI\Renderer\DefaultRenderer $content_renderer Used response
-     *                                         renderer, only applied if body
-     *                                         is not a callable closure
+     * @param Renderer\DefaultRenderer $content_renderer Used response renderer,
+     *                                                   only applied if body is
+     *                                                   not a callable closure
      */
     public function finish($content_renderer)
     {

lib/classes/restapi/RouteMap.php

@@ -242,7 +242,7 @@ abstract class RouteMap
      * @param mixed  $offset
      * @param mixed  $limit
      *
-     * @return RESTAPI\Routemap Returns instance of self to allow chaining
+     * @return Routemap Returns instance of self to allow chaining
      */
     public function paginate($uri_format, $total, $offset = null, $limit = null)
     {
@@ -266,15 +266,15 @@ abstract class RouteMap
      * Be aware that the passed data has to be already sliced according to
      * the pagination information.
      *
-     * @param Array $data Actual dataset
-     * @return Array Collection "object"
+     * @param array $data Actual dataset
+     * @return array Collection "object"
      */
     public function collect($data)
     {
         $collection = [
             'collection' => $data
         ];
-        if ($this->pagination) {
+        if (is_array($this->pagination)) {
             extract($this->pagination);
 
             $offset = $offset - $offset % $limit;
@@ -1020,9 +1020,9 @@ abstract class RouteMap
      * Extracts defined conditions from a given docblock.
      *
      * @param Docblock $docblock   DocBlock to examine
-     * @param Array    $conditions Optional array of already defined
+     * @param array    $conditions Optional array of already defined
      *                             conditions to extend
-     * @return Array of all extracted conditions with the variable name
+     * @return array of all extracted conditions with the variable name
      *         as key and pattern to match as value
      */
     protected function extractConditions($docblock, $conditions = [])

lib/classes/restapi/Router.php

@@ -5,7 +5,7 @@
  * die für die RESTful Web Services von Stud.IP benötigt werden.
  */
 namespace RESTAPI;
-use BadMethodCallException;
+use RESTAPI\Renderer\DefaultRenderer;
 
 /**
  * Die Aufgabe des Routers ist das Anlegen und Auswerten eines
@@ -145,7 +145,7 @@ class Router
      *                                  Defaults to false.
      *
      * @return Router  returns itself to allow chaining
-     * @throws Exception  if passed HTTP request method is not supported
+     * @throws \Exception  if passed HTTP request method is not supported
      */
     public function register($request_method, $uri_template, $handler, $conditions = [], $source = 'unknown', $allow_nobody = false)
     {
@@ -305,7 +305,7 @@ class Router
      *                              consumer is authorized to,
      *                              defaults to `true`
      *
-     * @return Array list of registered routes
+     * @return array list of registered routes
      */
     public function getRoutes($describe = false, $check_access = true)
     {
@@ -364,7 +364,7 @@ class Router
 
         $content_renderer = $this->negotiateContent($uri);
 
-        list($route, $parameters, $allow_nobody) = $this->matchRoute($uri, $method, $content_renderer);
+        [$route, $parameters, $allow_nobody] = $this->matchRoute($uri, $method, $content_renderer);
         if (!$route) {
             //No route found for the combination of URI and method.
             //We return the allowed methods for the route in the HTTP header:
@@ -472,7 +472,7 @@ class Router
         $handler = $route['handler'];
 
         if (!is_object($handler[0])) {
-            throw new RuntimeException("Handler is not a method.");
+            throw new \RuntimeException("Handler is not a method.");
         }
 
         $handler[0]->init($this, $route);
@@ -502,7 +502,7 @@ class Router
     /**
      * Registers a content renderer.
      *
-     * @param ContentRenderer $renderer    instance of a content renderer
+     * @param DefaultRenderer $renderer    instance of a content renderer
      * @param boolean         $is_default  (optional) set this
      *                                     renderer as default?;
      *                                     defaults to `false`
@@ -560,12 +560,12 @@ class Router
      *
      * @param String $uri     the URI to match
      * @param String $method  the HTTP request method to match
-     * @param ContentRenderer $content_renderer the used
+     * @param DefaultRenderer $content_renderer the used
      *                                          ContentRenderer which
      *                                          is needed to remove
      *                                          a file extension
      *
-     * @return Array  an array containing the matched route and the
+     * @return array  an array containing the matched route and the
      *                found parameters
      */
     protected function matchRoute($uri, $method, $content_renderer)

lib/classes/restapi/RouterHalt.php

@@ -11,6 +11,7 @@ class RouterHalt extends \Exception
 {
     public function __construct($response)
     {
+        parent::__construct();
         $this->response = $response;
     }
 }

lib/classes/restapi/UserPermissions.php

@@ -17,7 +17,7 @@ class UserPermissions
      * Permissions object will be cached for each user.
      *
      * @param mixed $user_id Id of user (optional, defaults to global)
-     * @return Permissions Returns permissions object
+     * @return UserPermissions Returns permissions object
      */
     public static function get($user_id = null)
     {
@@ -48,14 +48,12 @@ class UserPermissions
     }
 
     /**
-     * Defines whether access if allowed for the current user to the
+     * Defines whether access is allowed for the current user to the
      * passed route via the passed method.
      *
-     * @param String $route_id Route template (hash)
-     * @param String $method   HTTP method
+     * @param String $user_id Id of the user
      * @param mixed  $granted  Granted state (PHP'ish boolean)
-     * @param bool   $overwrite May values be overwritten
-     * @return bool Indicates if value could be changed.
+     * @return UserPermissions Returns instance of self to allow chaining
      */
     public function set($user_id, $granted = true)
     {
@@ -130,7 +128,7 @@ class UserPermissions
     /**
      * Get a list of all consumer the user has granted acces to.
      *
-     * @return Array List of consumer objects
+     * @return array List of consumer objects
      */
     public function getConsumers()
     {

lib/classes/restapi/consumer/Base.php

@@ -75,9 +75,9 @@ abstract class Base extends \SimpleORMap
      * object of the associated type.
      *
      * @param String $id Id of the consumer
-     * @return RESTAPI\Consumer\Base Associated consumer object (derived
+     * @return \RESTAPI\Consumer\Base Associated consumer object (derived
      *                               from consumer base type)
-     * @throws Exception if either consumer id or consumer type is invalid
+     * @throws \Exception if either consumer id or consumer type is invalid
      */
     public static function find($id)
     {
@@ -99,7 +99,7 @@ abstract class Base extends \SimpleORMap
     /**
      * Returns a list of all known consumers.
      *
-     * @return Array List of all known consumers (as specialized consumer
+     * @return array List of all known consumers (as specialized consumer
      *               objects)
      */
     public static function findAll()
@@ -115,14 +115,14 @@ abstract class Base extends \SimpleORMap
      * Creates a new consumer of the given type.
      *
      * @param String $type Name of the type
-     * @return RESTAPI\Consumer\Base Consumer object of the given (derived
+     * @return \RESTAPI\Consumer\Base Consumer object of the given (derived
      *                               from consumer base type)
-     * @throws Exception if type is invalid
+     * @throws \Exception if type is invalid
      */
     public static function create($type)
     {
         if (!isset(self::$known_types[$type])) {
-            throw new Exception('Consumer is of unknown type "' . $type . '"');
+            throw new \Exception('Consumer is of unknown type "' . $type . '"');
         }
 
         return new self::$known_types[$type];
@@ -136,7 +136,7 @@ abstract class Base extends \SimpleORMap
      * @param mixed $request_type Type of request (optional; defaults to any)
      * @return mixed Either the detected consumer or false if no consumer
      *               was detected
-     * @throws Exception if type is invalid
+     * @throws \Exception if type is invalid
      */
     public static function detectConsumer($type = null, $request_type = null)
     {
@@ -145,7 +145,7 @@ abstract class Base extends \SimpleORMap
                  : [$type];
         foreach ($needles as $needle) {
             if (!isset(self::$known_types)) {
-                throw new Exception('Trying to detect consumer of unkown type "' . $needle . '"');
+                throw new \Exception('Trying to detect consumer of unkown type "' . $needle . '"');
             }
             $consumer_class = self::$known_types[$needle];
             if ($consumer = $consumer_class::detect($request_type)) {
@@ -180,11 +180,11 @@ abstract class Base extends \SimpleORMap
     /**
      * Retrieve the api permissions associated with this consumer.
      *
-     * @return RESTAPI\ConsumerPermissions Permission object for this consumer
+     * @return \RESTAPI\ConsumerPermissions Permission object for this consumer
      */
     public function getPermissions()
     {
-        return new RESTAPI\ConsumerPermissions($this->id);
+        return \RESTAPI\ConsumerPermissions::get($this->id);
     }
 
     /**
@@ -192,7 +192,7 @@ abstract class Base extends \SimpleORMap
      * "having a user authenticated by this consumer".
      *
      * @param mixed $user Either a user object or a user id
-     * @return RESTAPI\Consumer\Base Returns instance of self to allow
+     * @return \RESTAPI\Consumer\Base Returns instance of self to allow
      *                               chaining
      */
     public function setUser($user)