Merge remote-tracking branch 'origin/master' into questionobject_prot…

…otype1

application/Psr4AutoloaderClass.php

@@ -99,7 +99,7 @@ public function addNamespace($prefix, $base_dir, $prepend = false)
      * Loads the class file for a given class name.
      *
      * @param string $class The fully-qualified class name.
-     * @return mixed The mapped file name on success, or boolean false on
+     * @return string|false The mapped file name on success, or boolean false on
      * failure.
      */
     public function loadClass($class)
@@ -138,7 +138,7 @@ public function loadClass($class)
      * 
      * @param string $prefix The namespace prefix.
      * @param string $relative_class The relative class name.
-     * @return mixed Boolean false if no mapped file can be loaded, or the
+     * @return false|string Boolean false if no mapped file can be loaded, or the
      * name of the mapped file that was loaded.
      */
     protected function loadMappedFile($prefix, $relative_class)

application/controllers/AdminController.php

@@ -89,7 +89,7 @@ public function error($message, $sURL = array())
 
         $this->_getAdminFooter('http://manual.limesurvey.org', gT('LimeSurvey online manual'));
 
-        die;
+        Yii::app()->end();
     }
     /**
     * Load and set session vars

application/controllers/InstallerController.php

@@ -41,7 +41,7 @@ class InstallerController extends CController {
     *
     * @access public
     * @param string $action
-    * @return bool
+    * @return boolean|null
     */
     public function run($action = 'index')
     {
@@ -734,7 +734,6 @@ public function loadHelper($helper)
     * Loads a library
     *
     * @access public
-    * @param string $helper
     * @return void
     */
     public function loadLibrary($library)
@@ -745,7 +744,6 @@ public function loadLibrary($library)
     /**
     * check requirements
     *
-    * @param array $data return theme variables
     * @return bool requirements met
     */
     private function _check_requirements(&$aData)
@@ -772,6 +770,9 @@ function check_HTML_image($result)
         }
 
 
+        /**
+         * @param string $sDirectory
+         */
         function is_writable_recursive($sDirectory)
         {
             $sFolder = opendir($sDirectory);
@@ -806,9 +807,9 @@ function check_PHPFunction($sFunctionName, &$sImage)
         *
         * @param string $path file or directory to check
         * @param int $type 0:undefined (invalid), 1:file, 2:directory
-        * @param string $data to manipulate
         * @param string $base key for data manipulation
         * @param string $keyError key for error data
+        * @param string $aData
         * @return bool result of check (that it is writeable which implies existance)
         */
         function check_PathWriteable($path, $type, &$aData, $base, $keyError, $bRecursive=false)
@@ -942,7 +943,7 @@ function check_DirectoryWriteable($directory, &$data, $base, $keyError, $bRecurs
     /**
     * Installer::_setup_tables()
     * Function that actually modify the database. Read $sqlfile and execute it.
-    * @param string $sqlfile
+    * @param string $sFileName
     * @return  Empty string if everything was okay - otherwise the error messages
     */
     function _setup_tables($sFileName, $aDbConfig = array(), $sDatabasePrefix = '')
@@ -1178,6 +1179,7 @@ function _getRandomString()
     *
     * @param string $sDatabaseType
     * @param string $sDatabasePort
+    * @return string
     */
     function _getDsn($sDatabaseType, $sDatabaseLocation, $sDatabasePort, $sDatabaseName, $sDatabaseUser, $sDatabasePwd)
     {

application/controllers/admin/PluginHelper.php

@@ -38,38 +38,81 @@ public function sidebody($surveyId, $plugin, $method)
     }
 
     /**
-     * Get HTML content for side-body
-     *
-     * @param string $plugin Name of the plugin class
-     * @param string $method Name of the plugin method
-     * @return string
+     * Helper function to let a plugin put content
+     * into the full page wrapper easily.
+     * @param string $plugin
+     * @param string $method
+     * @return void
      */
-    protected function getContent($surveyId, $plugin, $method)
+    public function fullpagewrapper($plugin, $method)
+    {
+        $aData = array();
+
+        $content = $this->getContent(null, $plugin, $method);
+
+        $aData['content'] = $content;
+        $this->_renderWrappedTemplate(null, 'super/dummy', $aData);
+    }
+
+    /**
+     * At ajax, just echo content
+     * @param string $plugin
+     * @param string $method
+     */
+    public function ajax($plugin, $method)
+    {
+        list($pluginInstance, $refMethod) = $this->getPluginInstanceAndMethod($plugin, $method);
+        $request = Yii::app()->request;
+        echo $refMethod->invoke($pluginInstance, $request);
+    }
+
+    /**
+     * 
+     * @param string $pluginName
+     * @param string $methodName
+     * @return array
+     */
+    protected function getPluginInstanceAndMethod($pluginName, $methodName)
     {
         // Get plugin class, abort if not found
-        try
-        {
-            $refClass = new ReflectionClass($plugin);
+        try {
+            $refClass = new ReflectionClass($pluginName);
+        }
+        catch (ReflectionException $ex) {
+            throw new \CException("Can't find a plugin with class name $pluginName");
         }
-        catch (ReflectionException $ex)
-        {
-            throw new \CException("Can't find a plugin with class name $plugin");
+
+        $record = Plugin::model()->findByAttributes(array('name' => $pluginName, 'active' => 1));
+        if (empty($record)) {
+            throw new Exception('Plugin with name ' . $pluginName . ' is not active or can\' be found');
         }
 
         $pluginManager = App()->getPluginManager();
-        $pluginInstance = $refClass->newInstance($pluginManager, 0);
+        $pluginInstance = $refClass->newInstance($pluginManager, $record->id);
+
+        Yii::app()->setPlugin($pluginInstance);
 
         // Get plugin method, abort if not found
-        try
-        {
-            $refMethod = $refClass->getMethod($method);
+        try {
+            $refMethod = $refClass->getMethod($methodName);
         }
-        catch (ReflectionException $ex)
-        {
-            throw new \CException("Plugin $plugin has no method $method");
+        catch (ReflectionException $ex) {
+            throw new \CException("Plugin $pluginName has no method $methodName");
         }
 
-        return $refMethod->invoke($pluginInstance, $surveyId);
+        return array($pluginInstance, $refMethod);
+    }
 
+    /**
+     * Get HTML content for side-body
+     *
+     * @param string $plugin Name of the plugin class
+     * @param string $method Name of the plugin method
+     * @return string
+     */
+    protected function getContent($surveyId, $plugin, $method)
+    {
+        list($pluginInstance, $refMethod) = $this->getPluginInstanceAndMethod($plugin, $method);
+        return $refMethod->invoke($pluginInstance, $surveyId);
     }
 }

application/controllers/admin/authentication.php

@@ -31,10 +31,11 @@ class Authentication extends Survey_Common_Action
     /**
      * Show login screen and parse login data
      * Will redirect or echo json depending on ajax call
-     * @return void
+     * This function is called while accessing the login page: index.php/admin/authentication/sa/login
      */
     public function index()
     {
+        // The page should be shown only for non logged in users
         $this->_redirectIfLoggedIn();
 
         // Result can be success, fail or data for template
@@ -77,59 +78,65 @@ public function index()
 
     /**
      * Prepare login and return result
+     * It checks if the authdb plugin is registered and active
      * @return array Either success, failure or plugin data (used in login form)
      */
     public static function prepareLogin()
     {
         $aData = array();
 
-        // Make sure after first run / update the authdb plugin is registered and active
-        // it can not be deactivated
-        if (!class_exists('Authdb', false)) {
-            $plugin = Plugin::model()->findByAttributes(array('name'=>'Authdb'));
-            if (!$plugin) {
-                $plugin = new Plugin();
-                $plugin->name = 'Authdb';
-                $plugin->active = 1;
-                $plugin->save();
-                App()->getPluginManager()->loadPlugin('Authdb', $plugin->id);
-            } else {
-                $plugin->active = 1;
-                $plugin->save();
-            }
-        }
-
+        // In Authdb, the plugin event "beforeLogin" checks if the url param "onepass" is set
+        // if yes, it will call  AuthPluginBase::setAuthPlugin to set to true the plugin private parameter "_stop", so the form will not be displayed
+        // @see: application/core/plugins/Authdb/Authdb.php: function beforeLogin()
         $beforeLogin = new PluginEvent('beforeLogin');
         $beforeLogin->set('identity', new LSUserIdentity('', ''));
-
         App()->getPluginManager()->dispatchEvent($beforeLogin);
+
         /* @var $identity LSUserIdentity */
-        $identity = $beforeLogin->get('identity');
+        $identity = $beforeLogin->get('identity');                              // Why here?
 
+        // If the plugin private parameter "_stop" is false and the login form has not been submitted: render the login form
         if (!$beforeLogin->isStopped() && is_null(App()->getRequest()->getPost('login_submit')) )
         {
+            // First step: set the value of $aData['defaultAuth']
+            // This variable will be used to select the default value of the Authentication method selector
+            // which is shown only if there is more than one plugin auth on...
+            // @see application/views/admin/authentication/login.php
+
+            // First it checks if the current plugin force the authentication default value...
+            // NB: A plugin SHOULD NOT be able to over pass the configuration file
+            // @see: http://img.memecdn.com/knees-weak-arms-are-heavy_c_3011277.jpg
             if (!is_null($beforeLogin->get('default'))) {
                 $aData['defaultAuth'] = $beforeLogin->get('default');
             }
             else {
+                // THen, it checks if the the user set a different default plugin auth in application/config/config.php
+                // eg: 'config'=>array()'debug'=>2,'debugsql'=>0, 'default_displayed_auth_method'=>'muh_auth_method')
                 if (App()->getPluginManager()->isPluginActive(Yii::app()->getConfig('default_displayed_auth_method'))) {
                         $aData['defaultAuth'] = Yii::app()->getConfig('default_displayed_auth_method');
-                    }
-                    else {
+                    }else {
                         $aData['defaultAuth'] = 'Authdb';
                     }
             }
+
+            // Call the plugin method newLoginForm
+            // For Authdb:  @see: application/core/plugins/Authdb/Authdb.php: function newLoginForm()
             $newLoginForm = new PluginEvent('newLoginForm');
-            App()->getPluginManager()->dispatchEvent($newLoginForm);
+            App()->getPluginManager()->dispatchEvent($newLoginForm);            // inject the HTML of the form inside the private varibale "_content" of the plugin
             $aData['summary'] = self::getSummary('logout');
-            $aData['pluginContent'] = $newLoginForm->getAllContent();
+            $aData['pluginContent'] = $newLoginForm->getAllContent();           // Retreives the private varibale "_content" , and parse it to $aData['pluginContent'], which will be  rendered in application/views/admin/authentication/login.php
         }
         else
         {
+            // The form has been submited, or the plugin has been stoped (so normally, the value of login/password are available)
+
              // Handle getting the post and populating the identity there
-            $authMethod = App()->getRequest()->getPost('authMethod', $identity->plugin);
+            $authMethod = App()->getRequest()->getPost('authMethod', $identity->plugin);      // If form has been submitted, $_POST['authMethod'] is set, else  $identity->plugin should be set, ELSE: TODO error
             $identity->plugin = $authMethod;
 
+            // Call the function afterLoginFormSubmit of the plugin.
+            // For Authdb, it calls AuthPluginBase::afterLoginFormSubmit()
+            // which set the plugin's private variables _username and _password with the POST informations if it's a POST request else it does nothing
             $event = new PluginEvent('afterLoginFormSubmit');
             $event->set('identity', $identity);
             App()->getPluginManager()->dispatchEvent($event, array($authMethod));
@@ -342,7 +349,7 @@ private static function doRedirect()
      * Renders template(s) wrapped in header and footer
      *
      * @param string $sAction Current action, the folder to fetch views from
-     * @param string|array $aViewUrls View url(s)
+     * @param string $aViewUrls View url(s)
      * @param array $aData Data to be passed on. Optional.
      * @return void
      */

application/controllers/admin/checkintegrity.php

@@ -848,7 +848,7 @@ protected function _checkintegrity()
      * Renders template(s) wrapped in header and footer
      *
      * @param string $sAction Current action, the folder to fetch views from
-     * @param string|array $aViewUrls View url(s)
+     * @param string $aViewUrls View url(s)
      * @param array $aData Data to be passed on. Optional.
      */
     public function _renderWrappedTemplate($sAction = 'checkintegrity', $aViewUrls = array(), $aData = array())

application/controllers/admin/conditionsaction.php

@@ -1639,7 +1639,7 @@ protected function getCopyForm($qid, $gid, array $conditionsList, array $pquesti
     /**
      * Get html for add/edit condition form
      * @param array $args
-     * @return void
+     * @return string
      */
     protected function getEditConditionForm(array $args)
     {
@@ -2006,7 +2006,7 @@ protected function getJavascriptForMatching(array $canswers, array $cquestions,
     }
 
     /**
-     * @param array $extractedTokenAttr
+     * @param string[] $extractedTokenAttr
      * @return string
      */
     protected function getAttributeName($extractedTokenAttr)

application/controllers/admin/export.php

@@ -922,6 +922,9 @@ public function exportMultipleArchiveSurveys()
     }
 
 
+    /**
+     * @param string $sExportType
+     */
     public function exportMultipleSurveys($sSurveys, $sExportType)
     {
         $aSurveys = json_decode($sSurveys);
@@ -1161,7 +1164,7 @@ private function _surveyexport($action, $iSurveyID)
      * Return a list of queXML settings
      *
      * @access private
-     * @return array queXML settings
+     * @return string[] queXML settings
      */
     private function _quexmlsettings()
     {

application/controllers/admin/globalsettings.php

@@ -314,7 +314,7 @@ private function _checkSettings()
     * Renders template(s) wrapped in header and footer
     *
     * @param string $sAction Current action, the folder to fetch views from
-    * @param string|array $aViewUrls View url(s)
+    * @param string $aViewUrls View url(s)
     * @param array $aData Data to be passed on. Optional.
     */
     public function _renderWrappedTemplate($sAction = '', $aViewUrls = array(), $aData = array())

application/controllers/admin/labels.php

@@ -170,7 +170,6 @@ public function import()
     * Function to load new/edit labelset screen.
     *
     * @access public
-    * @param mixed $action
     * @param integer $lid
     * @return
     */

application/controllers/admin/limereplacementfields.php

@@ -53,6 +53,10 @@ public function index()
         $this->getController()->render('/admin/limeReplacementFields_view', $data);
     }
 
+    /**
+     * @param integer $gid
+     * @param integer $qid
+     */
     private function _getQuestionList($action, $gid, $qid, array $fieldmap, $questionType, $surveyformat)
     {
         $previousQuestion = null;
@@ -179,6 +183,9 @@ private function _getChildQuestions(array $questions)
         return $cquestions;
     }
 
+    /**
+     * @param integer $surveyid
+     */
     private function _getReplacementFields($fieldtype, $surveyid)
     {