MDL-58090 oauth2: Coding style

Part of MDL-58220

admin/tool/oauth2/classes/form/endpoint.php

@@ -37,8 +37,10 @@ use core\form\persistent;
  */
 class endpoint extends persistent {
 
+    /** @var string $persistentclass */
     protected static $persistentclass = 'core\\oauth2\\endpoint';
 
+    /** @var array $fieldstoremove */
     protected static $fieldstoremove = array('submitbutton', 'action');
 
     /**

admin/tool/oauth2/classes/form/issuer.php

@@ -37,8 +37,10 @@ use core\form\persistent;
  */
 class issuer extends persistent {
 
+    /** @var string $persistentclass */
     protected static $persistentclass = 'core\\oauth2\\issuer';
 
+    /** @var array $fieldstoremove */
     protected static $fieldstoremove = array('submitbutton', 'action');
 
     /**

admin/tool/oauth2/classes/form/user_field_mapping.php

@@ -37,8 +37,10 @@ use core\form\persistent;
  */
 class user_field_mapping extends persistent {
 
+    /** @var string $persistentclass */
     protected static $persistentclass = 'core\\oauth2\\user_field_mapping';
 
+    /** @var array $fieldstoremove */
     protected static $fieldstoremove = array('submitbutton', 'action');
 
     /**

admin/tool/oauth2/classes/output/renderer.php

@@ -142,7 +142,8 @@ class renderer extends plugin_renderer_base {
             $links .= ' ' . $editendpointlink;
 
             // User field mapping.
-            $edituserfieldmappingsurl = new moodle_url('/admin/tool/oauth2/userfieldmappings.php', ['issuerid' => $issuer->get('id')]);
+            $params = ['issuerid' => $issuer->get('id')];
+            $edituserfieldmappingsurl = new moodle_url('/admin/tool/oauth2/userfieldmappings.php', $params);
             $str = get_string('edituserfieldmappings', 'tool_oauth2');
             $edituserfieldmappinglink = html_writer::link($edituserfieldmappingsurl, $OUTPUT->pix_icon('t/user', $str));
             $links .= ' ' . $edituserfieldmappinglink;
@@ -188,6 +189,7 @@ class renderer extends plugin_renderer_base {
      * This function will render one beautiful table with all the endpoints.
      *
      * @param \core\oauth2\endpoint[] $endpoints - list of all endpoints.
+     * @param int $issuerid
      * @return string HTML to output.
      */
     public function endpoints_table($endpoints, $issuerid) {
@@ -210,7 +212,7 @@ class renderer extends plugin_renderer_base {
             $namecell = new html_table_cell(s($name));
             $namecell->header = true;
 
-            // Url
+            // Url.
             $url = $endpoint->get('url');
             $urlcell = new html_table_cell(s($url));
 
@@ -246,6 +248,7 @@ class renderer extends plugin_renderer_base {
      * This function will render one beautiful table with all the user_field_mappings.
      *
      * @param \core\oauth2\user_field_mapping[] $userfieldmappings - list of all user_field_mappings.
+     * @param int $issuerid
      * @return string HTML to output.
      */
     public function user_field_mappings_table($userfieldmappings, $issuerid) {
@@ -263,11 +266,11 @@ class renderer extends plugin_renderer_base {
         $index = 0;
 
         foreach ($userfieldmappings as $userfieldmapping) {
-            // External field
+            // External field.
             $externalfield = $userfieldmapping->get('externalfield');
             $externalfieldcell = new html_table_cell(s($externalfield));
 
-            // Internal field
+            // Internal field.
             $internalfield = $userfieldmapping->get('internalfield');
             $internalfieldcell = new html_table_cell(s($internalfield));
 

admin/tool/oauth2/settings.php

@@ -25,5 +25,6 @@
 defined('MOODLE_INTERNAL') || die;
 
 if ($hassiteconfig) {
-    $ADMIN->add('server', new admin_externalpage('oauth2', new lang_string('pluginname','tool_oauth2'), "$CFG->wwwroot/$CFG->admin/tool/oauth2/issuers.php"));
+    $ADMIN->add('server', new admin_externalpage('oauth2', new lang_string('pluginname','tool_oauth2'),
+         "$CFG->wwwroot/$CFG->admin/tool/oauth2/issuers.php"));
 }

admin/tool/oauth2/version.php

@@ -24,7 +24,7 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version   = 2016120500; // The current plugin version (Date: YYYYMMDDXX)
-$plugin->requires  = 2016112900; // Requires this Moodle version
-$plugin->component = 'tool_oauth2'; // Full name of the plugin (used for diagnostics)
+$plugin->version   = 2016120500; // The current plugin version (Date: YYYYMMDDXX).
+$plugin->requires  = 2016112900; // Requires this Moodle version.
+$plugin->component = 'tool_oauth2'; // Full name of the plugin (used for diagnostics).
 

auth/oauth2/auth.php

@@ -27,8 +27,7 @@ defined('MOODLE_INTERNAL') || die();
 require_once($CFG->libdir.'/authlib.php');
 
 /**
- * Plugin for oauth2 authentication. This is a way to use namespaces even though
- * moodle expects a non-namespaced file here.
+ * Plugin for oauth2 authentication. 
  *
  * @package auth_oauth2
  * @copyright 2017 Damyon Wiese

auth/oauth2/classes/auth.php

@@ -153,7 +153,7 @@ class auth extends \auth_plugin_base {
      *
      * @param stdClass $config
      * @param string $err
-     * @param array userfields
+     * @param array $userfields
      */
     public function config_form($config, $err, $userfields) {
         echo get_string('plugindescription', 'auth_oauth2');
@@ -170,6 +170,7 @@ class auth extends \auth_plugin_base {
     /**
      * Return the userinfo from the oauth handshake. Will only be valid
      * for the logged in user.
+     * @param $string username
      */
     public function get_userinfo($username) {
         $cached = $this->get_static_user_info();
@@ -181,7 +182,7 @@ class auth extends \auth_plugin_base {
 
     /**
      * Do some checks on the identity provider before showing it on the login page.
-     * @param core\oauth2\issuer
+     * @param core\oauth2\issuer $issuer
      * @return boolean
      */
     private function is_ready_for_login_page(\core\oauth2\issuer $issuer) {
@@ -248,6 +249,7 @@ class auth extends \auth_plugin_base {
 
     /**
      * If this user has no picture - but we got one from oauth - set it.
+     * @param stdClass $user
      * @return boolean True if the image was updated.
      */
     private function update_picture($user) {

lib/classes/oauth2/api.php

@@ -17,12 +17,14 @@
 /**
  * Class for loading/storing oauth2 endpoints from the DB.
  *
- * @package    core_oauth2
+ * @package    core
  * @copyright  2017 Damyon Wiese
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 namespace core\oauth2;
 
+defined('MOODLE_INTERNAL') || die();
+
 require_once($CFG->libdir . '/filelib.php');
 
 use context_system;
@@ -31,7 +33,6 @@ use stdClass;
 use moodle_exception;
 use moodle_url;
 
-defined('MOODLE_INTERNAL') || die();
 
 /**
  * Static list of api methods for system oauth2 configuration.
@@ -181,6 +182,11 @@ class api {
         return $issuer;
     }
 
+    /**
+     * Create one of the standard issuers.
+     * @param string $type One of google, facebook, microsoft
+     * @return \core\oauth2\issuer
+     */
     public static function create_standard_issuer($type) {
         require_capability('moodle/site:config', context_system::instance());
         if ($type == 'google') {
@@ -236,8 +242,8 @@ class api {
      * Get the system account for an installed OAuth service.
      * Never ever ever expose this to a webservice because it contains the refresh token which grants API access.
      *
-     * @param int $id
-     * @return core\oauth2\user_field_mapping
+     * @param \core\oauth2\issuer $id
+     * @return \core\oauth2\client
      */
     public static function get_system_account(issuer $issuer) {
         return system_account::get_record(['issuerid' => $issuer->get('id')]);
@@ -247,7 +253,7 @@ class api {
      * Get the full list of system scopes required by an oauth issuer.
      * This includes the list required for login as well as any scopes injected by the oauth2_system_scopes callback in plugins.
      *
-     * @param core\oauth2\issuer $issuer
+     * @param \core\oauth2\issuer $issuer
      * @return string
      */
     public static function get_system_scopes_for_issuer($issuer) {
@@ -308,7 +314,7 @@ class api {
      * This call does the redirect dance back to the current page after authentication.
      *
      * @param core\oauth2\issuer $issuer The desired OAuth issuer
-     * @param moodle_url $url The url to the current page.
+     * @param moodle_url $currenturl The url to the current page.
      * @param string $additionalscopes The additional scopes required for authorization.
      * @return core\oauth2\client
      */
@@ -715,7 +721,7 @@ class api {
         $record = new stdClass();
         $record->issuerid = $issuer->get('id');
         $record->refreshtoken = $refreshtoken;
-        $record->grantedscopes = $scopesrequired;
+        $record->grantedscopes = $scopes;
 
         $systemaccount = new system_account(0, $record);
 

lib/classes/oauth2/client.php

@@ -169,6 +169,7 @@ class client extends \oauth2_client {
     /**
      * Upgrade a refresh token from oauth 2.0 to an access token
      *
+     * @param \core\oauth2\system_account $systemaccount
      * @return boolean true if token is upgraded succesfully
      */
     public function upgrade_refresh_token(system_account $systemaccount) {

lib/classes/oauth2/endpoint.php

@@ -36,6 +36,7 @@ use lang_string;
  */
 class endpoint extends persistent {
 
+    /** @const TABLE */
     const TABLE = 'oauth2_endpoint';
 
     /**
@@ -61,8 +62,8 @@ class endpoint extends persistent {
      * Custom validator for end point URLs.
      * Because we send Bearer tokens we must ensure SSL.
      *
-     * @param $value The value to check.
-     * @return boolean
+     * @param string $value The value to check.
+     * @return lang_string|boolean
      */
     protected function validate_url($value) {
         if (strpos($value, 'https://') !== 0) {

lib/classes/oauth2/issuer.php

@@ -35,6 +35,7 @@ use core\persistent;
  */
 class issuer extends persistent {
 
+    /** @const TABLE */
     const TABLE = 'oauth2_issuer';
 
     /**

lib/classes/oauth2/system_account.php

@@ -37,6 +37,7 @@ use core\persistent;
  */
 class system_account extends persistent {
 
+    /** @const TABLE */
     const TABLE = 'oauth2_system_account';
 
     /**

lib/classes/oauth2/user_field_mapping.php

@@ -35,8 +35,10 @@ use core\persistent;
  */
 class user_field_mapping extends persistent {
 
+    /** @const TABLE */
     const TABLE = 'oauth2_user_field_mapping';
 
+    /** @var array $userfields - List of standard Moodle userfields. */
     private static $userfields = [
         'firstname',
         'middlename',

lib/filelib.php

@@ -3267,6 +3267,11 @@ class curl {
         $this->responsefinished = false;
     }
 
+    /**
+     * For use only in unit tests - we can pre-set the next curl response.
+     * This is useful for unit testing APIs that call external systems.
+     * @param string $response
+     */
     public static function mock_response($response) {
         if ((defined('PHPUNIT_TEST') && PHPUNIT_TEST)) {
             array_push(self::$mockresponses, $response);