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	}