MDL-58631 auth: Clarify documentation of changes in loginpage_idp_list()

This should clarify the new 'iconurl' key returned by the auth plugin's
loginpage_idp_list() method.

auth/mnet/auth.php

@@ -1064,19 +1064,10 @@ function trim_logline ($logline) {
     }
 
     /**
-     * Returns a list of potential IdPs that this authentication plugin supports.
-     * This is used to provide links on the login page.
+     * Returns a list of MNet IdPs that the user can roam from.
      *
-     * @param string $wantsurl the relative url fragment the user wants to get to.  You can use this to compose a returnurl, for example
-     *
-     * @return array like:
-     *              array(
-     *                  array(
-     *                      'url' => 'http://someurl',
-     *                      'icon' => new pix_icon(...),
-     *                      'name' => get_string('somename', 'auth_yourplugin'),
-     *                 ),
-     *             )
+     * @param string $wantsurl The relative url fragment the user wants to get to.
+     * @return array List of arrays with keys url, icon and name.
      */
     function loginpage_idp_list($wantsurl) {
         global $DB, $CFG;

auth/oauth2/classes/auth.php

@@ -179,7 +179,7 @@ private function is_ready_for_login_page(\core\oauth2\issuer $issuer) {
      * Return a list of identity providers to display on the login page.
      *
      * @param string|moodle_url $wantsurl The requested URL.
-     * @return array (containing url, iconurl and name).
+     * @return array List of arrays with keys url, iconurl and name.
      */
     public function loginpage_idp_list($wantsurl) {
         $providers = \core\oauth2\api::get_all_issuers();

auth/upgrade.txt

@@ -7,6 +7,8 @@ information provided here is intended especially for developers.
   Plugins should use a settings.php file to manage configurations rather than using the config.html files.
 * The function 'print_auth_lock_options' has been replaced by 'display_auth_lock_options' which uses the admin settings API.
   See auth_manual as an exmple of how it can be used.  More information can be found in MDL-12689.
+* The list of supported identity providers (SSO IdP) returned by the 'loginpage_idp_list' method (used to render the
+  login page and login block links) now supports a new key 'iconurl' which should be used instead of the legacy 'icon'.
 
 === 3.2 ===
 

lib/authlib.php

@@ -561,18 +561,25 @@ function can_be_manually_set() {
 
     /**
      * Returns a list of potential IdPs that this authentication plugin supports.
-     * This is used to provide links on the login page.
      *
-     * @param string $wantsurl the relative url fragment the user wants to get to.  You can use this to compose a returnurl, for example
+     * This is used to provide links on the login page and the login block.
      *
-     * @return array like:
-     *              array(
-     *                  array(
-     *                      'url' => 'http://someurl',
-     *                      'icon' => new pix_icon(...),
-     *                      'name' => get_string('somename', 'auth_yourplugin'),
-     *                 ),
-     *             )
+     * The parameter $wantsurl is typically used by the plugin to implement a
+     * return-url feature.
+     *
+     * The returned value is expected to be a list of associative arrays with
+     * string keys:
+     *
+     * - url => (moodle_url|string) URL of the page to send the user to for authentication
+     * - name => (string) Human readable name of the IdP
+     * - iconurl => (moodle_url|string) URL of the icon representing the IdP (since Moodle 3.3)
+     *
+     * For legacy reasons, pre-3.3 plugins can provide the icon via the key:
+     *
+     * - icon => (pix_icon) Icon representing the IdP
+     *
+     * @param string $wantsurl The relative url fragment the user wants to get to.
+     * @return array List of associative arrays with keys url, name, iconurl|icon
      */
     function loginpage_idp_list($wantsurl) {
         return array();
@@ -614,10 +621,12 @@ public function postlogout_hook($user) {
     /**
      * Return the list of enabled identity providers.
      *
-     * Each identity provider data contains the keys 'url' (string), 'name' (string) and 'icon' (pix_icon).
+     * Each identity provider data contains the keys url, name and iconurl (or
+     * icon). See the documentation of {@link auth_plugin_base::loginpage_idp_list()}
+     * for detailed description of the returned structure.
      *
      * @param array $authsequence site's auth sequence (list of auth plugins ordered)
-     * @return array an array of enabled identity providers
+     * @return array List of arrays describing the identity providers
      */
     public static function get_identity_providers($authsequence) {
         global $SESSION;
@@ -634,16 +643,18 @@ public static function get_identity_providers($authsequence) {
     /**
      * Prepare a list of identity providers for output.
      *
-     * @param array $identityproviders
+     * @param array $identityproviders as returned by {@link self::get_identity_providers()}
      * @param renderer_base $output
      * @return array the identity providers ready for output
      */
     public static function prepare_identity_providers_for_output($identityproviders, renderer_base $output) {
         $data = [];
         foreach ($identityproviders as $idp) {
             if (!empty($idp['icon'])) {
+                // Pre-3.3 auth plugins provide icon as a pix_icon instance.
                 $idp['iconurl'] = $output->image_url($idp['icon']->key, $idp['icon']->component);
             } else if ($idp['iconurl'] instanceof moodle_url) {
+                // New auth plugins (since 3.3) provide iconurl.
                 $idp['iconurl'] = $idp['iconurl']->out(false);
             }
             unset($idp['icon']);

lib/upgrade.txt

@@ -1,8 +1,8 @@
 This files describes API changes in core libraries and APIs,
 information provided here is intended especially for developers.
+
 === 3.3 ===
-* The information returned by the idp list has changed. This is usually only rendered by the login page and login block.
-  The icon attribute is removed and an iconurl attribute has been added.
+
 * Support added for a new type of external file: FILE_CONTROLLED_LINK. This is an external file that Moodle can control
   the permissions. Moodle makes files read-only but can grant temporary write access.
     When accessing a URL, the info from file_browser::get_file_info will be checked to determine if the user has write access,