[CLEANUP] Add and fix the PhpDoc for the REST API V2

This makes the code easier to follow in IDEs, and also easier to
read and understand.

Also fix some static/non-static mismatches and add public visibility
where it is missing.

Author: Oliver Klee

plugins/restapi2/call.php

@@ -61,12 +61,15 @@
 }
 
 // Get necessary objects from container
+/** @var \Rapi\Call $call */
 $call = $container->get( 'Call' );
+/** @var \Rapi\Response $response */
 $response = $container->get( 'Response' );
 
 // Check if you are calling loginHandler, if you aren't, it checks for a token to see if you are logged in
 if($_GET['className'] !== "loginHandler"){
 
+    /** @var \Rapi\Admin $admin */
     $admin = $container->get( 'Admin' );
 
     if(isset($_POST['token'])){

plugins/restapi2/lib/Admin.php

@@ -6,32 +6,35 @@
  * Class for account related commands
  */
 class Admin {
-
-    // Response object
+    /**
+     * @var Response
+     */
     protected $response;
     /**
-     * @var AdminModel
+     * @var \phpListAdminAuthentication
      */
     private $admin;
 
     /**
      * Admin constructor.
      * @param Response $response
-     * @param AdminModel $adminModel
+     * @param \phpListAdminAuthentication $admin
      */
-    public function __construct(Response $response, \phpList\Admin $admin )
+    public function __construct(Response $response, \phpListAdminAuthentication $admin)
     {
         $this->response = $response;
         $this->admin = $admin;
     }
 
     /**
      * Function to call for login.
+     *
      * @todo: Finish implementing this method
-     * [*login] {string} loginname as an admin to phpList
-     * [*password] {string} the password
-     * @return boolean
-     * @throws \Exception
+     *
+     * @param string $password login name as an admin to phpList
+     * @param string $username the password
+     *
+     * @return bool
      */
     public function login( $password, $username )
     {
@@ -41,10 +44,13 @@ public function login( $password, $username )
             $this->admin->setLoginToken($data['admin']->id);
             return $this->admin->getLoginToken($data['admin']->id);
         }
+
+        return false;
     }
 
     /**
-     * @param $token string
+     * @param string $token
+     *
      * @return bool
      */
     public function isLoggedIn( $token ){
@@ -55,7 +61,6 @@ public function isLoggedIn( $token ){
      * Processes the Message Queue in phpList.
      * @todo: Finish implementing this method
      * @note: Perhaps this is done via CRON or manually through the admin interface?
-     * [*login] {string} loginname as an admin to phpList
      */
     public function processQueue()
     {

plugins/restapi2/lib/Call.php

@@ -2,6 +2,11 @@
 
 namespace Rapi;
 
+use phpList\Entity\SubscriberEntity;
+use Rapi\Handler\ListHandler;
+use Rapi\Handler\LoginHandler;
+use Rapi\Handler\SubscriberHandler;
+
 /**
  * Class to handle API call functionality and execution
  * @note This class is ignorant of call output and forwards it transparently --
@@ -11,24 +16,30 @@ class Call {
 
     /**
      * Constructor requires all classes that may handle calls as arguments
+     *
      * @note To add support for an API call, add it's parent class to arguments
-     * @param Lists             $lists
-     * @param SubscriberHandler $subscriberHandler
+     * @param Handler\ListHandler $listHandler
+     * @param Handler\SubscriberHandler|SubscriberHandler $subscriberHandler
+     * @param Handler\LoginHandler $loginHandler
+     * @internal param Lists $lists
      */
     public function __construct(
-        \Rapi\Handler\ListHandler $listHandler
-        , \Rapi\Handler\SubscriberHandler $subscriberHandler
-        , \Rapi\Handler\LoginHandler $loginHandler
+        ListHandler $listHandler,
+        SubscriberHandler $subscriberHandler,
+        LoginHandler $loginHandler
     )
     {
         $this->listHandler = $listHandler;
         $this->subscriberHandler = $subscriberHandler;
         $this->loginHandler = $loginHandler;
     }
+
     /**
      * Validate a requested call by checking characters and syntax
+     *
      * @param string $className Name of class to validate
      * @param string $method Name of method to validate
+     *
      * @return bool $result
      */
     public function validateCall( $className, $method )
@@ -55,7 +66,10 @@ public function validateCall( $className, $method )
 
     /**
      * Get API call configuraiton whitelist
+     *
      * @param string $whitelistPath Path to whitelist configuration file
+     *
+     * @return mixed
      */
     public function getWhitelistConfig( $whitelistPath = NULL )
     {
@@ -83,7 +97,11 @@ public function getWhitelistConfig( $whitelistPath = NULL )
 
     /**
      * Check if the supplied class name is permitted by the whitelist
+     *
      * @param string $className Class name to check
+     * @param string $method
+     *
+     * @return bool
      */
     public function isCallWhitelisted( $className, $method )
     {
@@ -107,10 +125,12 @@ public function isCallWhitelisted( $className, $method )
 
     /**
      * Validate an API call and execute the requested method on handler object
+     *
      * @param string $className to execute method on
      * @param string $method name of method to execute
      * @param array $argumentsArray arguments to pass to method
-     * @return \phpList\Entity\SubscriberEntity Data object
+     *
+     * @return SubscriberEntity Data object
      */
     public function doCall( $className, $method, array $argumentsArray )
     {
@@ -143,7 +163,10 @@ public function doCall( $className, $method, array $argumentsArray )
 
     /**
      * Format raw user-privded API call parameters for passing to handler object
+     *
      * @param array $argumentsArray user-supplied API call parameters
+     *
+     * @return array
      */
     public function formatParams( array $argumentsArray ) {
 
@@ -159,7 +182,10 @@ public function formatParams( array $argumentsArray ) {
 
     /**
      * Convert any var type to an array suitable for passing to a response
+     *
      * @param mixed $callResult Returned value of an executed API call
+     *
+     * @return array|mixed
      */
     public function callResultToArray( $callResult )
     {
@@ -191,10 +217,12 @@ public function callResultToArray( $callResult )
     * This function converts an object into an associative array by iterating
     * over its public properties. Because this function uses the foreach
     * construct, Iterators are respected. It also works on arrays of objects.
+     *
     * @param object $object The object to be converted
+     *
     * @return array $result Converted object
     */
-    function objectToArray( $object )
+    public function objectToArray( $object )
     {
         $result = array();
         $references = array();

plugins/restapi2/lib/Campaigns.php

@@ -10,14 +10,17 @@
  */
 class Messages
 {
+    /**
+     * @param int $id
+     */
     public static function messageGet($id = 0)
     {
         if ($id == 0) {
             $id = $_REQUEST['id'];
         }
         Common::select('Message', 'SELECT * FROM '.$GLOBALS['table_prefix'].'message WHERE id='.$id.';', true);
     }
-    
+
     public static function messagesCount()
     {
         Common::select('Messages', 'SELECT count(id) as total FROM '.$GLOBALS['table_prefix'].'message',true);
@@ -31,7 +34,7 @@ public static function messagesGet()
 
     /**
      * Add a new campaign.
-     * 
+     *
      * <p><strong>Parameters:</strong><br/>
      * [*subject] {string} <br/>
      * [*fromfield] {string} <br/>
@@ -80,7 +83,7 @@ public static function messageAdd()
 
     /**
      * Update existing message/campaign.
-     * 
+     *
      * <p><strong>Parameters:</strong><br/>
      * [*id] {integer} <br/>
      * [*subject] {string} <br/>
@@ -99,6 +102,8 @@ public static function messageAdd()
      * <p><strong>Returns:</strong><br/>
      * The message added.
      * </p>
+     *
+     * @param int $id
      */
     public static function messageUpdate($id = 0)
     {

plugins/restapi2/lib/Common.php

@@ -3,18 +3,30 @@
 namespace Rapi;
 
 class Common {
-
-    // Extended pdo object
+    /**
+     * @var PdoEx
+     */
     protected $pdoEx;
 
+    /**
+     * Common constructor.
+     *
+     * @param PdoEx $pdoEx
+     * @param Response $response
+     */
     public function __construct( PdoEx $pdoEx, Response $response )
     {
         $this->pdoEx = $pdoEx;
     }
 
     /**
      * Generate a URL for executing API calls
-     * @param [type] $website [description]
+     *
+     * @param string $website
+     * @param string $pageRoot
+     * @param string $adminDir
+     *
+     * @return string
      */
     public function apiUrl( $website, $pageRoot, $adminDir )
     {

plugins/restapi2/lib/Handler/ListHandler.php

@@ -2,6 +2,10 @@
 
 namespace Rapi\Handler;
 
+use phpList\Entity\ListEntity;
+use phpList\Entity\SubscriberEntity;
+use phpList\ListManager;
+
 /**
 * Class to handle API calls to ListManager{}
 */
@@ -13,16 +17,22 @@ class ListHandler
     * @param ListManager $listManager
     */
     public function __construct(
-        \phpList\Entity\ListEntity $listEntity
-        , \phpList\ListManager $listManager
-        , \phpList\Entity\SubscriberEntity $scrEntity
+        ListEntity $listEntity,
+        ListManager $listManager,
+        SubscriberEntity $scrEntity
     )
     {
         $this->listEntity = $listEntity;
         $this->listManager = $listManager;
         $this->scrEntity = $scrEntity;
     }
 
+    /**
+     * @param int $listId
+     * @param int $scrId
+     *
+     * @return \PDOStatement|null
+     */
     public function addSubscriber( $listId, $scrId )
     {
         // Save the id to the subscriber entity

plugins/restapi2/lib/Handler/LoginHandler.php

@@ -2,6 +2,7 @@
 
 namespace Rapi\Handler;
 use phpList\helper\Logger;
+use Rapi\Admin;
 
 /**
  * Class LoginHandler
@@ -12,14 +13,21 @@ class LoginHandler
 
     /**
      * LoginHandler constructor.
-     * @param \Rapi\Admin $admin
+     *
+     * @param Admin $admin
+     * @param Logger $logger
      */
-    public function __construct( \Rapi\Admin $admin, Logger $logger)
+    public function __construct( Admin $admin, Logger $logger)
     {
         $this->admin = $admin;
         $logger->debug('LoginHandler was called');
     }
 
+    /**
+     * @param string $username
+     * @param string $password
+     * @return array
+     */
     public function login($username, $password){
         $data = $this->admin->login($username, $password);
         if($data){