1	<?php
2
3	namespace UserFrosting;
4
5	/** These define the interfaces for the database object interface.  Any other implementations you write for the model MUST implement these interfaces. */
6
7	/**
8	* DatabaseInterface Interface
9	*
10	* Represents a generic static class for connecting to a database.
11	*
12	* @package UserFrosting
13	* @author Alex Weissman
14	* @link http://alexanderweissman.com
15	*/
16	interface DatabaseInterface {
17	public static function connection();
18	public static function getInfo();
19	public static function getCreatedTables();
20	public static function install();
21	public static function testConnection();
22	}
23
24	interface DatabaseTableInterface {
25
26	}
27
28	/**
29	* ObjectLoaderInterface Interface
30	*
31	* Represents a generic static class for loading an object from the database.
32	*
33	* @package UserFrosting
34	* @author Alex Weissman
35	* @link http://alexanderweissman.com
36	*/
37	interface ObjectLoaderInterface {
38
39	/**
40	* Set table and columns for this class.  Kinda hacky but I don't see any other way to do it.
41	*
42	* @param DatabaseTable $table The table information object.
43	*/
44	public static function init($table);
45
46	/**
47	* Determine whether or not a record exists in the table for the given value.
48	*
49	* @param string $value The value to look up in the table for this type of object.
50	* @param string $name The column to use when looking up $value.  Defaults to `id`.
51	* @return boolean True if the record exists, false otherwise.
52	*/
53	public static function exists($value, $name = "id");
54
55	/**
56	* Fetch a single record from a table into the corresponding object.
57	*
58	* @param string $value The value to look up in the table for this type of object.
59	* @param string $name The column to use when looking up $value.  Defaults to `id`.
60	* @return DatabaseObjectInterface|false The object, or false if it doesn't exist.
61	*/
62	public static function fetch($value, $name = "id");
63
64	/**
65	* Fetch a set of records from a table into an array of the corresponding object.
66	*
67	* @param string $value[optional] The value to look up in the table for this type of object.
68	* @param string $name[optional] The column to use when looking up $value.  Defaults to `id`.
69	* @return DatabaseObjectInterface[] An array of objects that match the criteria.  Returns empty array if no matching objects were found.
70	*/
71	public static function fetchAll($value = null, $name = null);
72	}
73
74	interface DatabaseObjectInterface {
75	public function table();
76	public function __isset($name);
77	public function __get($name);
78	public function __set($name, $value);
79	public function fresh();
80	public function export();
81	public function store();
82	}
83
84	interface UserLoaderInterface {
85
86	public static function generateActivationToken($gen = null);
87	}
88
89	interface GroupLoaderInterface {
90
91	}
92	interface GroupUserLoaderInterface {
93
94	}
95	interface GroupObjectInterface {
96	public function getUsers();
97	}
98
99	/**
100	* UserObjectInterface Interface
101	*
102	* Represents a User object as stored in the database.
103	*
104	* @package UserFrosting
105	* @author Alex Weissman
106	* @link http://alexanderweissman.com
107	*
108	* @property string user_name
109	* @property string display_name
110	* @property string email
111	* @property string password
112	* @property string title
113	* @property int activation_token
114	* @property datetime last_activation_request
115	* @property int lost_password_request
116	* @property datetime lost_password_timestamp
117	* @property int active
118	* @property datetime sign_up_stamp
119	* @property datetime last_sign_in_stamp
120	* @property int enabled
121	* @property int primary_group_id
122	* @property string locale
123	*/
124	interface UserObjectInterface {
125
126	/**
127	* Determine whether or not this User object is a guest user or an authenticated user.
128	*
129	* @return boolean True if the user is a guest, false otherwise.
130	*/
131	public function isGuest();
132
133	/**
134	* Get an array containing all groups to which this user belongs.
135	*
136	* This method caches the data after the first time loading from the database.  To force a refresh, use the `fresh` method.
137	* @return GroupObjectInterface[] An array of Group objects, indexed by the group id.
138	*/
139	public function getGroups();
140
141	/**
142	* Adds this user to a specified group, skipping if this user is already a member of the group.  Call `store` to persist to database.
143	*
144	* @param int $group_id The id of the group to add the user to.
145	* @throws Exception The specified group does not exist.
146	* @return UserObjectInterface this User object.
147	*/
148	public function addGroup($group_id);
149
150	/**
151	* Remove this user from a specified group, skipping if this user is not a member of the group.  Call `store` to persist to database.
152	*
153	* @param int $group_id The id of the group to remove the user from.
154	* @return UserObjectInterface this User object.
155	*/
156	public function removeGroup($group_id);
157
158	/**
159	* Get the theme for this user.
160	*
161	* The theme for the root user is always 'root'.  The theme for guest users is 'default'.  Any other users will have their themes determined by their primary group.
162	* @return GroupObjectInterface[] An array of Group objects, indexed by the group id.
163	*/
164	public function getTheme();
165
166	/**
167	* Get this user's primary group.
168	*
169	* This method caches the data after the first time loading from the database.  To force a refresh, use the `fresh` method.
170	* @return GroupObjectInterface the Group object representing the user's primary group.
171	*/
172	public function getPrimaryGroup();
173
174	/**
175	* Checks whether or not this user has access for a particular authorization hook.
176	*
177	* @param string $hook The authorization hook to check for access.
178	* @param array $params[optional] An array of field names => values, specifying any additional data to provide the authorization module
179	* when determining whether or not this user has access.
180	* @return boolean True if the user has access, false otherwise.
181	*/
182	public function checkAccess($hook, $params);
183
184	/**
185	* Verify a plaintext password against the user's hashed password.
186	*
187	* @param string $password The plaintext password to verify.
188	* @return boolean True if the password matches, false otherwise.
189	*/
190	public function verifyPassword($password);
191
192	/**
193	* Log this user in.  This basically updates the user's sign-in time, and updates any old password hashes.
194	*
195	* You should set this user object to $_SESSION["userfrosting"]["user"] after calling login, so that it will persist in the session.
196	*/
197	public function login();
198	}
199
200	/**
201	* SiteSettingsInterface Interface
202	*
203	* A interface for site settings database classes.
204	*
205	* @package UserFrosting
206	* @author Alex Weissman
207	* @link http://alexanderweissman.com
208	*
209	* @property string site_title The title of the site.  By default, displayed in the title tag, as well as the upper left corner of every user page.
210	* @property string site_location The nation or state in which legal jurisdiction for this site falls.
211	* @property string admin_email The administrative email for the site.  Automated emails, such as activation emails and password reset links, will come from this address.
212	* @property int email_login 0|1 Specify whether users can login via email address or username instead of just username.
213	* @property int can_register 0|1 Specify whether public registration of new accounts is enabled.
214	* Enable if you have a service that users can sign up for, disable if you only want accounts to be created by you or an admin.
215	* @property int enable_captcha 0|1 Specify whether new users must complete a captcha code when registering for an account.
216	* @property int show_terms_on_register 0|1 Specify whether or not to show terms and conditions when registering.
217	* @property int require_activation 0|1 Specify whether email activation is required for newly registered accounts.  Accounts created on the admin side never need to be activated.
218	* @property int resend_activation_threshold The time, in seconds, that a user must wait before requesting that the activation email be resent.
219	* @property int reset_password_timeout The time, in seconds, before a user's password reminder email expires.
220	* @property string default_locale The default language for newly registered users.
221	* @property int minify_css 0|1 Specify whether to use concatenated, minified CSS (production) or raw CSS includes (dev).
222	* @property int minify_js 0|1 Specify whether to use concatenated, minified JS (production) or raw JS includes (dev).
223	* @property string version The current version of UserFrosting.
224	* @property string author The author of the site.  Will be used in the site's author meta tag.
225	*/
226	interface SiteSettingsInterface {
227
228	/**
229	* Determine whether or not all settings defined in this object are present in the database.
230	*
231	* @return boolean true if the table exists and all keys (core userfrosting and plugins) are defined in the table, false otherwise.
232	*/
233	public function isConsistent();
234
235	/**
236	* Fetch the settings from the database.
237	*
238	* @return array An array of site settings, containing the name and description for each setting.
239	*/
240	public function fetchSettings();
241
242	/**
243	* Magic isset to determine if a particular setting is defined in the environment or core userfrosting settings.
244	* This does not check plugin settings or descriptions.
245	*
246	* @param string $name The name of the setting.
247	* @return boolean true if $name is defined, false otherwise.
248	*/
249	public function __isset($name);
250
251	/**
252	* Magic setter to set the value of a core userfrosting setting.
253	* This does not allow you to set the setting description.  To do that, you must use `set`.
254	*
255	* @param string $name The name of the setting.
256	* @param string $value The value to assign the setting.
257	*/
258	public function __set($name, $value);
259
260	/**
261	* Magic getter to get the value of an environment or core userfrosting setting.  This does not get plugin settings.  For that, you must use `get`.
262	* This will first check if an environment setting of the specified $name exists and return it.  If not, it will then check if a DB setting of that name exists.
263	*
264	* @param string $name The name of the setting.
265	* @return string the value of the setting.
266	* @throws Exception The value does not exist in the environment or core settings.
267	*/
268	public function __get($name);
269
270	/**
271	* Create/update a setting value.  If it exists, update, otherwise, create.  If updating, then a value or description set to null tells it to remain the same.  If creating, a value or description of null sets the field to an empty string.
272	*
273	* @param string $plugin The name of the plugin to associate this setting with.
274	* @param string $name The name of the setting.
275	*/
276	public function set($plugin, $name, $value = null, $description = null);
277
278	/**
279	* Get a persistent setting value for a particular plugin.  Throws an exception if the plugin or value does not exist.
280	*
281	* @param string $name The name of the setting.
282	* @param string $plugin The plugin scope of this setting.  Defaults to "userfrosting".
283	* @throws Exception The value does not exist for this plugin.
284	*/
285	public function get($name, $plugin = "userfrosting");
286
287	/**
288	* Get the description persistent setting value for a particular plugin.  Throws an exception if the plugin or description does not exist.
289	*
290	* @param string $name The name of the setting.
291	* @param string $plugin The plugin scope of this setting.  Defaults to "userfrosting".
292	* @throws Exception The description does not exist for this value of the specified plugin.
293	*/
294	public function getDescription($name, $plugin = "userfrosting");
295
296	/**
297	* Get a site environment (non-persistent) variable.  Throws an exception if the variable does not exist.
298	*
299	* @param string $name The name of the site environment variable.
300	* @throws Exception The specified environment variable does not exist.
301	*/
302	public function getEnvironment($name);
303
304	/**
305	* Register a setting to appear on the site settings page.
306	*
307	* @param string $plugin The name of the plugin that this setting is associated with.
308	* @param string $name The name of the site setting.
309	* @param string $label The label to display next to the site setting field.
310	* @param string $type "text"|"readonly"|"toggle"|"select" The type of field - plain text, readonly, toggle switch, or dropdown select.
311	* @param array $options If this field is a switch or dropdown, an associative array of values => labels to be presented.  Switches should have values "0" and "1".
312	* @throws Exception The specified plugin or site setting does not exist.
313	*/
314	public function register($plugin, $name, $label, $type = "text", $options = []);
315
316	/**
317	* Get an array of site settings that have been registered for display on the site settings page.
318	*
319	* The result is a multidimensional array indexed first by plugin name, then by setting name.  Each setting name will then have an array containing values for "value", "label", "type", "options", and "description".
320	* For example, $settings['userfrosting']['site_title']['value'] = "UserFrosting".
321	* @return array The array of site settings.
322	*/
323	public function getRegisteredSettings();
324
325	/**
326	* Get an array of available locales for UserFrosting by scanning the path specified in $app->config('locales.path').
327	*
328	* @return array An array containing the names of all available locales (e.g. "en_EN", "es_ES", etc.)
329	*/
330	public function getLocales();
331
332	/**
333	* Get an array of available themes for UserFrosting by scanning the path specified in $app->config('themes.path').
334	*
335	* @return array An array containing the names of all available themes (e.g. "default", "root", etc.)
336	*/
337	public function getThemes();
338
339	/**
340	* Get an array of installed plugins by scanning the path specified in $app->config('plugins.path').
341	*
342	* @return array An array containing the names of all available themes (e.g. "oauth", "datatables", etc.)
343	*/
344	public function getPlugins();
345
346	/**
347	* Get an array of system information for UserFrosting.
348	*
349	* @return array An array containing a list of information, such as software version, application path, etc.
350	*/
351	public function getSystemInfo();
352
353	/**
354	* Get the PHP error log as an array of lines.
355	*
356	* @param int $lines the number of lines to display.  Set to `null` to display all lines.
357	* @return array An array containing 'path', which is the path of the PHP error log, and 'messages', which is an array of error messages sorted with the newest messages first.
358	*/
359	public function getLog($lines = null);
360
361	/**
362	* Store the site settings from this object to the database, inserting new records when necessary and updating existing records otherwise.
363	*/
364	public function store();
365	}