[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * This file is part of the phpBB Forum Software package.
   5  *
   6  * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7  * @license GNU General Public License, version 2 (GPL-2.0)
   8  *
   9  * For full copyright and license information, please see
  10  * the docs/CREDITS.txt file.
  11  *
  12  */
  13  
  14  namespace phpbb\auth\provider;
  15  
  16  /**
  17  * The interface authentication provider classes have to implement.
  18  */
  19  interface provider_interface
  20  {
  21      /**
  22       * Checks whether the user is currently identified to the authentication
  23       * provider.
  24       * Called in acp_board while setting authentication plugins.
  25       * Changing to an authentication provider will not be permitted in acp_board
  26       * if there is an error.
  27       *
  28       * @return     boolean|string     False if the user is identified, otherwise an
  29       *                            error message, or null if not implemented.
  30       */
  31  	public function init();
  32  
  33      /**
  34       * Performs login.
  35       *
  36       * @param    string    $username     The name of the user being authenticated.
  37       * @param    string    $password    The password of the user.
  38       * @return    array    An associative array of the format:
  39       *                        array(
  40       *                            'status' => status constant
  41       *                            'error_msg' => string
  42       *                            'user_row' => array
  43       *                        )
  44       *                    A fourth key of the array may be present:
  45       *                    'redirect_data'    This key is only used when 'status' is
  46       *                    equal to LOGIN_SUCCESS_LINK_PROFILE and its value is an
  47       *                    associative array that is turned into GET variables on
  48       *                    the redirect url.
  49       */
  50  	public function login($username, $password);
  51  
  52      /**
  53       * Autologin function
  54       *
  55       * @return     array|null    containing the user row, empty if no auto login
  56       *                         should take place, or null if not implemented.
  57       */
  58  	public function autologin();
  59  
  60      /**
  61       * This function is used to output any required fields in the authentication
  62       * admin panel. It also defines any required configuration table fields.
  63       *
  64       * @return    array|null    Returns null if not implemented or an array of the
  65       *                        configuration fields of the provider.
  66       */
  67  	public function acp();
  68  
  69      /**
  70       * This function updates the template with variables related to the acp
  71       * options with whatever configuration values are passed to it as an array.
  72       * It then returns the name of the acp file related to this authentication
  73       * provider.
  74       *
  75       * @param \phpbb\config\config    $new_config    Contains the new configuration values
  76       *                                             that have been set in acp_board.
  77       * @return array|null        Returns null if not implemented or an array with
  78       *                            the template file name and an array of the vars
  79       *                            that the template needs that must conform to the
  80       *                            following example:
  81       *                            array(
  82       *                                'TEMPLATE_FILE'    => string,
  83       *                                'TEMPLATE_VARS'    => array(...),
  84       *                            )
  85       *                            An optional third element may be added to this
  86       *                            array: 'BLOCK_VAR_NAME'. If this is present,
  87       *                            then its value should be a string that is used
  88       *                            to designate the name of the loop used in the
  89       *                            ACP template file. When this is present, an
  90       *                            additional key named 'BLOCK_VARS' is required.
  91       *                            This must be an array containing at least one
  92       *                            array of variables that will be assigned during
  93       *                            the loop in the template. An example of this is
  94       *                            presented below:
  95       *                            array(
  96       *                                'BLOCK_VAR_NAME'    => string,
  97       *                                'BLOCK_VARS'        => array(
  98       *                                    'KEY IS UNIMPORTANT' => array(...),
  99       *                                ),
 100       *                                'TEMPLATE_FILE'    => string,
 101       *                                'TEMPLATE_VARS'    => array(...),
 102       *                            )
 103       */
 104  	public function get_acp_template($new_config);
 105  
 106      /**
 107      * Returns an array of data necessary to build custom elements on the login
 108      * form.
 109      *
 110      * @return    array|null    If this function is not implemented on an auth
 111      *                        provider then it returns null. If it is implemented
 112      *                        it will return an array of up to four elements of
 113      *                        which only 'TEMPLATE_FILE'. If 'BLOCK_VAR_NAME' is
 114      *                        present then 'BLOCK_VARS' must also be present in
 115      *                        the array. The fourth element 'VARS' is also
 116      *                        optional. The array, with all four elements present
 117      *                        looks like the following:
 118      *                        array(
 119      *                            'TEMPLATE_FILE'        => string,
 120      *                            'BLOCK_VAR_NAME'    => string,
 121      *                            'BLOCK_VARS'        => array(...),
 122      *                            'VARS'                => array(...),
 123      *                        )
 124      */
 125  	public function get_login_data();
 126  
 127      /**
 128       * Performs additional actions during logout.
 129       *
 130       * @param     array    $data            An array corresponding to
 131       *                                    \phpbb\session::data
 132       * @param     boolean    $new_session    True for a new session, false for no new
 133       *                                    session.
 134       */
 135  	public function logout($data, $new_session);
 136  
 137      /**
 138       * The session validation function checks whether the user is still logged
 139       * into phpBB.
 140       *
 141       * @param     array     $user
 142       * @return     boolean    true if the given user is authenticated, false if the
 143       *                     session should be closed, or null if not implemented.
 144       */
 145  	public function validate_session($user);
 146  
 147      /**
 148      * Checks to see if $login_link_data contains all information except for the
 149      * user_id of an account needed to successfully link an external account to
 150      * a forum account.
 151      *
 152      * @param    array    $login_link_data    Any data needed to link a phpBB account to
 153      *                                an external account.
 154      * @return    string|null    Returns a string with a language constant if there
 155      *                        is data missing or null if there is no error.
 156      */
 157  	public function login_link_has_necessary_data(array $login_link_data);
 158  
 159      /**
 160      * Links an external account to a phpBB account.
 161      *
 162      * @param    array    $link_data    Any data needed to link a phpBB account to
 163      *                                an external account.
 164      */
 165  	public function link_account(array $link_data);
 166  
 167      /**
 168      * Returns an array of data necessary to build the ucp_auth_link page
 169      *
 170      * @param int $user_id User ID for whom the data should be retrieved.
 171      *                        defaults to 0, which is not a valid ID. The method
 172      *                        should fall back to the current user's ID in this
 173      *                        case.
 174      * @return    array|null    If this function is not implemented on an auth
 175      *                        provider then it returns null. If it is implemented
 176      *                        it will return an array of up to four elements of
 177      *                        which only 'TEMPLATE_FILE'. If 'BLOCK_VAR_NAME' is
 178      *                        present then 'BLOCK_VARS' must also be present in
 179      *                        the array. The fourth element 'VARS' is also
 180      *                        optional. The array, with all four elements present
 181      *                        looks like the following:
 182      *                        array(
 183      *                            'TEMPLATE_FILE'        => string,
 184      *                            'BLOCK_VAR_NAME'    => string,
 185      *                            'BLOCK_VARS'        => array(...),
 186      *                            'VARS'                => array(...),
 187      *                        )
 188      */
 189  	public function get_auth_link_data($user_id = 0);
 190  
 191      /**
 192      * Unlinks an external account from a phpBB account.
 193      *
 194      * @param    array    $link_data    Any data needed to unlink a phpBB account
 195      *                                from a phpbb account.
 196      */
 197  	public function unlink_account(array $link_data);
 198  }