roles_helper.php — Appointment Booking Plugin – LatePoint | Calendar & Scheduling for WordPress 5.6.10

latepoint / lib / helpers / roles_helper.php

latepoint / lib / helpers Last commit date

roles_helper.php

597 lines

1	<?php
2	/*
3	* Copyright (c) 2023 LatePoint LLC. All rights reserved.
4	*/
5
6	class OsRolesHelper {
7	public static array $capabilities_for_controllers;
8
9	public static function get_capabilities_for_all_controllers() {
10	if ( isset( self::$capabilities_for_controllers ) ) {
11	return self::$capabilities_for_controllers;
12	}
13	$capabilities = include LATEPOINT_CONFIG_ABSPATH . 'capabilities_for_controllers.php';
14
15	/**
16	* Get array of capabilities for all controllers
17	*
18	* @since 4.7.0
19	* @hook latepoint_capabilities_for_controllers
20	*
21	* @param {array} $capabilities array of controllers with their default and per action capablities
22	* @returns {array} The filtered array of controllers with capability information
23	*/
24	self::$capabilities_for_controllers = apply_filters( 'latepoint_capabilities_for_controllers', $capabilities );
25	return self::$capabilities_for_controllers;
26	}
27
28	public static function build_capability_name_from_model_action( string $model_class, string $action ): string {
29	$capability_names_for_models = [
30	'OsActivityModel' => 'activity',
31	'OsAgentModel' => 'agent',
32	'OsAgentMetaModel' => 'agent',
33	'OsOrderModel' => 'booking',
34	'OsOrderIntentModel' => 'booking',
35	'OsOrderMetaModel' => 'booking',
36	'OsBookingModel' => 'booking',
37	'OsBookingMetaModel' => 'booking',
38	'OsConnectorModel' => 'connection',
39	'OsCustomerModel' => 'customer',
40	'OsCustomerMetaModel' => 'customer',
41	'OsLocationModel' => 'location',
42	'OsLocationCategoryModel' => 'location',
43	'OsServiceModel' => 'service',
44	'OsServiceExtraModel' => 'service',
45	'OsServiceMetaModel' => 'service',
46	'OsBundleModel' => 'bundle',
47	'OsServiceCategoryModel' => 'service',
48	'OsTransactionModel' => 'transaction',
49	'OsInvoiceModel' => 'invoice',
50	'OsProcessJobModel' => 'settings',
51	'OsStepSettingsModel' => 'settings',
52	'OsProcessModel' => 'settings',
53	'OsSettingsModel' => 'settings',
54	'OsWorkPeriodModel' => 'settings',
55	];
56	/**
57	* Get array of key => value connections between model name and capability name
58	*
59	* @since 4.7.0
60	* @hook latepoint_capability_names_for_models
61	*
62	* @param {array} $capability_names_for_models array of key => value pairs of model name => capability name
63	* @returns {array} The filtered array of value pairs
64	*/
65	$capability_names_for_models = apply_filters( 'latepoint_capability_names_for_models', $capability_names_for_models );
66	if ( isset( $capability_names_for_models[ $model_class ] ) ) {
67	$capability = $capability_names_for_models[ $model_class ] . '__' . $action;
68	$all_actions = self::get_all_available_actions_list();
69	if ( in_array( $capability, $all_actions ) ) {
70	return $capability;
71	} else {
72	$capability = $capability_names_for_models[ $model_class ] . '__edit';
73	if ( in_array( $capability, $all_actions ) ) {
74	return $capability;
75	}
76	}
77	}
78	return '';
79	}
80
81	public static function can_user_make_action_on_model_record( OsModel $model, string $action ) {
82	if ( OsAuthHelper::get_current_user()->backend_user_type == LATEPOINT_USER_TYPE_ADMIN ) {
83	return true; // admins are allowed to do everything
84	}
85
86	// check if customer is logged in and tries to edit records that belong to them
87	if ( OsAuthHelper::is_customer_logged_in() ) {
88	// if it's customer - they can edit their customer record and also their bookings
89	if ( $model instanceof OsBookingModel && $model->customer_id == OsAuthHelper::get_logged_in_customer_id() ) {
90	return true;
91	}
92	if ( $model instanceof OsCustomerModel && $model->id == OsAuthHelper::get_logged_in_customer_id() ) {
93	return true;
94	}
95	}
96	// if customer is not logged in or logged in customer doesn't have rights to access this record, check if backend user has
97	if ( self::can_user_perform_model_action( get_class( $model ), $action ) ) {
98	switch ( get_class( $model ) ) {
99	case 'OsBookingModel':
100	if ( OsAuthHelper::get_current_user()->are_all_records_allowed( 'agent' ) ) {
101	return true;
102	}
103	$allowed_ids = OsAuthHelper::get_current_user()->get_allowed_records( 'agent' );
104	if ( $allowed_ids && in_array( $model->agent_id, $allowed_ids ) ) {
105	return true;
106	}
107	break;
108	case 'OsCustomerModel':
109	// check if this customer has any bookings with allowed agents
110	if ( OsAuthHelper::get_current_user()->are_all_records_allowed( 'agent' ) ) {
111	return true;
112	}
113	$allowed_ids = OsAuthHelper::get_current_user()->get_allowed_records( 'agent' );
114	$bookings = new OsBookingModel();
115	if ( $allowed_ids ) {
116	if ( $allowed_ids && in_array( $model->agent_id, $allowed_ids ) ) {
117	return true;
118	}
119	$has_bookings_with_allowed_agents = $bookings->select( 'id' )->where(
120	[
121	'agent_id' => $allowed_ids,
122	'customer_id' => $model->id,
123	]
124	)->set_limit( 1 )->get_results();
125	if ( ! empty( $has_bookings_with_allowed_agents ) ) {
126	return true;
127	}
128	}
129	break;
130	}
131	}
132	return false;
133	}
134
135	public static function can_user_perform_model_action( string $model_class, string $action ): bool {
136	$capability = self::build_capability_name_from_model_action( $model_class, $action );
137	$can = ! empty( $capability ) ? self::can_user( $capability ) : true;
138	return $can;
139	}
140
141	/**
142	*
143	* Get capabilities required to access specific action of the controller
144	*
145	* @param string $controller_name class name of the controller
146	* @param string $action action name
147	* @return array
148	*/
149	public static function get_capabilities_required_for_controller_action( string $controller_name, string $action ): array {
150	$required_capabilities = [ 'settings__edit' ]; // default capabilities, if not set on controller/action level
151
152	$capabilities_for_controllers = self::get_capabilities_for_all_controllers();
153
154	if ( isset( $capabilities_for_controllers[ $controller_name ] ) ) {
155	// try to get capabilities that are specific for action, if not get default for controller
156	if ( isset( $capabilities_for_controllers[ $controller_name ]['per_action'][ $action ] ) ) {
157	$required_capabilities = $capabilities_for_controllers[ $controller_name ]['per_action'][ $action ];
158	} elseif ( isset( $capabilities_for_controllers[ $controller_name ]['default'] ) ) {
159	$required_capabilities = $capabilities_for_controllers[ $controller_name ]['default'];
160	}
161	}
162	/**
163	* Get array of capabilities required to access controller's action
164	*
165	* @since 4.7.0
166	* @hook latepoint_get_capabilities_for_controller_action
167	*
168	* @param {array} $required_capabilities array of required capabilities
169	* @returns {array} The filtered array of required capabilities
170	*/
171	return apply_filters( 'latepoint_get_capabilities_for_controller_action', $required_capabilities, $controller_name, $action );
172	}
173
174	public static function save_capabilities_list_for_agent_role( array $capabilities ) {
175	return OsSettingsHelper::save_setting_by_name( 'agent_role_capabilities', wp_json_encode( $capabilities ) );
176	}
177
178	public static function get_capabilities_list_for_agent_role() {
179	$capabilities = json_decode( OsSettingsHelper::get_settings_value( 'agent_role_capabilities', '' ), true );
180	if ( empty( $capabilities ) ) {
181	$capabilities = self::get_default_capabilities_list_for_agent_role();
182	}
183	/**
184	* Get array of permitted actions for agent role
185	*
186	* @since 4.7.0
187	* @hook latepoint_get_capabilities_list_for_agent_role
188	*
189	* @param {array} $capabilities array of actions permitted to admin user type
190	* @returns {array} The filtered array of permitted actions
191	*/
192	return apply_filters( 'latepoint_get_capabilities_list_for_agent_role', $capabilities );
193	}
194
195
196	public static function get_all_available_actions_list_grouped() {
197	$actions = self::get_all_available_actions_list();
198	$groups = [];
199	foreach ( $actions as $action ) {
200	$object = explode( '__', $action );
201	$groups[ $object[0] ][] = $object[1];
202	}
203
204	// Move single-action system groups to the end so CRUD groups (including add-ons)
205	// stay together near the top of the list.
206	$trailing_groups = [ 'chat', 'resource_schedule', 'settings', 'connection' ];
207	foreach ( $trailing_groups as $group_key ) {
208	if ( isset( $groups[ $group_key ] ) ) {
209	$group_actions = $groups[ $group_key ];
210	unset( $groups[ $group_key ] );
211	$groups[ $group_key ] = $group_actions;
212	}
213	}
214
215	return $groups;
216	}
217
218	public static function save_from_params( array $role_params ) {
219	$role = \LatePoint\Misc\Role::generate_from_params( $role_params );
220	if ( empty( $role->wp_role ) ) {
221	return new WP_Error( 'invalid_wp_role', __( 'WP Role invalid', 'latepoint' ) );
222	}
223	switch ( $role->user_type ) {
224	case LATEPOINT_USER_TYPE_AGENT:
225	if ( self::save_capabilities_list_for_agent_role( $role->get_capabilities() ) ) {
226	return true;
227	} else {
228	return new WP_Error( 'error_saving_role', __( 'WP Agent role can not be saved', 'latepoint' ) );
229	}
230	break;
231	case LATEPOINT_USER_TYPE_CUSTOM:
232	$roles = self::get_custom_roles();
233	$roles[ $role->wp_role ] = $role->as_array_to_save();
234	if ( OsSettingsHelper::save_setting_by_name( 'custom_roles', wp_json_encode( $roles ) ) ) {
235	// register in WP (it's ok to register it on every save, we remove it first and then add, to make sure display name is updated)
236	$role->register_in_wp();
237	return true;
238	} else {
239	return new WP_Error( 'error_saving_role', __( 'WP Role can not be saved', 'latepoint' ) );
240	}
241	break;
242	default:
243	return new WP_Error( 'invalid_role_type', __( 'Invalid role type', 'latepoint' ) );
244	break;
245	}
246	}
247
248	public static function get_wp_roles_list( $remove_admins = true ): array {
249	// this makes sure that the default customer role is created, before showing a list of roles
250	OsSettingsHelper::get_default_wp_role_for_new_customers();
251
252	global $wp_roles;
253
254
255
256	if ( ! isset( $wp_roles ) ) {
257	$wp_roles = new WP_Roles();
258	}
259
260	$roles = $wp_roles->get_names();
261
262	if ( $remove_admins ) {
263	unset( $roles['administrator'] );
264	unset( $roles['editor'] );
265	unset( $roles['shop_manager'] );
266	unset( $roles['sc_shop_manager'] );
267	}
268
269	/**
270	* List of WP roles that you can assign to a new customer
271	*
272	* @since 5.2.0
273	* @hook latepoint_wp_roles_list_for_customer
274	*
275	* @param {array} $roles list of roles in array
276	* @param {array} $remove_admins whether to remove admin roles or not
277	* @returns {array} The filtered list of roles
278	*/
279	return apply_filters( 'latepoint_wp_roles_list_for_customer', $roles, $remove_admins );
280	}
281
282
283	public static function register_customer_role() {
284	// Register Customer Role
285	add_role( LATEPOINT_WP_CUSTOMER_ROLE, apply_filters( 'latepoint_role_display_name', __( 'LatePoint Customer', 'latepoint' ), LATEPOINT_USER_TYPE_CUSTOMER ), array( 'read' => true ) );
286	}
287
288	public static function register_roles_in_wp() {
289	// Register Agent Role
290	$role = \LatePoint\Misc\Role::get_from_wp_role( LATEPOINT_WP_AGENT_ROLE );
291	$role->register_in_wp();
292
293	self::register_customer_role();
294
295
296	// Register Custom Roles
297	$custom_roles = self::get_custom_roles( true );
298	if ( $custom_roles ) {
299	foreach ( $custom_roles as $custom_role ) {
300	$custom_role->register_in_wp();
301	}
302	}
303	}
304
305	public static function get_model_types_for_allowed_records() {
306	return [ 'agent', 'service', 'location' ];
307	}
308
309
310	public static function generate_role_id() {
311	return strtolower( 'role_' . OsUtilHelper::random_text( 'alnum', 8 ) );
312	}
313
314	public static function get_custom_roles( $as_objects = false ): array {
315	$roles = json_decode( \OsSettingsHelper::get_settings_value( 'custom_roles', '' ), true ) ?? [];
316	if ( $as_objects ) {
317	$roles_objects = [];
318	foreach ( $roles as $role_params ) {
319	$roles_objects[ $role_params['wp_role'] ] = \LatePoint\Misc\Role::generate_from_params( $role_params );
320	}
321	return $roles_objects;
322	} else {
323	return $roles;
324	}
325	}
326
327	public static function save_custom_roles( array $roles ) {
328	return \OsSettingsHelper::save_setting_by_name( 'custom_roles', wp_json_encode( $roles ) );
329	}
330
331	public static function delete( string $wp_role ): bool {
332	// can't delete default roles (admin and agent)
333	if ( in_array( $wp_role, [ LATEPOINT_WP_ADMIN_ROLE, LATEPOINT_WP_AGENT_ROLE ] ) ) {
334	return false;
335	}
336	// get all custom roles to make sure the one that needs to be deleted is custom role
337	$custom_roles = self::get_custom_roles();
338	if ( isset( $custom_roles[ $wp_role ] ) ) {
339	unset( $custom_roles[ $wp_role ] );
340	self::save_custom_roles( $custom_roles );
341	remove_role( $wp_role );
342	}
343	return true;
344	}
345
346	public static function get_default_roles(): array {
347	$roles = [];
348
349	$roles[] = new \LatePoint\Misc\Role( LATEPOINT_USER_TYPE_ADMIN );
350	$roles[] = new \LatePoint\Misc\Role( LATEPOINT_USER_TYPE_AGENT );
351
352	return $roles;
353	}
354
355	public static function description_for_action( $action_code ) {
356	$action_descriptions = [
357	'resource_schedule' => __( 'Edit custom schedule of individual agent, location or service.', 'latepoint' ),
358	'settings' => __( 'Access to all settings pages, including general schedule and booking steps.', 'latepoint' ),
359	'connection' => __( 'Ability to connect agents to services and locations.', 'latepoint' ),
360	'chat' => __( 'Ability to send messages to customers (available with chat addon).', 'latepoint' ),
361	];
362
363	/**
364	* List of detailed descriptions for available actions
365	*
366	* @since 4.7.2
367	* @hook latepoint_roles_action_descriptions
368	*
369	* @param {array} $action_descriptions Array of descriptions for available actions
370	* @param {string} $action_code Programmatic code of the action being filtered
371	* @returns {array} The filtered array of action descriptions
372	*/
373	$action_descriptions = apply_filters( 'latepoint_roles_action_descriptions', $action_descriptions, $action_code );
374	return $action_descriptions[ $action_code ] ?? '';
375	}
376
377	public static function name_for_action( $action_code ) {
378	$action_names = [
379	'chat' => __( 'Chat', 'latepoint' ),
380	'activity' => __( 'Activity Logs', 'latepoint' ),
381	'agent' => __( 'Agents', 'latepoint' ),
382	'service' => __( 'Services', 'latepoint' ),
383	'bundle' => __( 'Bundle', 'latepoint' ),
384	'location' => __( 'Locations', 'latepoint' ),
385	'service_extra' => __( 'Service Extras', 'latepoint' ),
386	'asset' => __( 'Assets', 'latepoint' ),
387	'booking' => __( 'Bookings & Orders', 'latepoint' ),
388	'customer' => __( 'Customers', 'latepoint' ),
389	'transaction' => __( 'Payments', 'latepoint' ),
390	'invoice' => __( 'Invoice', 'latepoint' ),
391	'order' => __( 'Order', 'latepoint' ),
392	'resource_schedule' => __( 'Resource Schedules', 'latepoint' ),
393	'settings' => __( 'Settings', 'latepoint' ),
394	'connection' => __( 'Connections', 'latepoint' ),
395	'edit' => __( 'Edit', 'latepoint' ),
396	'delete' => __( 'Delete', 'latepoint' ),
397	'view' => __( 'View', 'latepoint' ),
398	'create' => __( 'Create', 'latepoint' ),
399	];
400
401	/**
402	* List of human-friendly names for available actions
403	*
404	* @since 4.7.2
405	* @hook latepoint_roles_action_names
406	*
407	* @param {array} $action_names Array of names for available actions
408	* @param {string} $action_code Programmatic code of the action being filtered
409	* @returns {array} The filtered array of action names
410	*/
411	$action_names = apply_filters( 'latepoint_roles_action_names', $action_names, $action_code );
412	return $action_names[ $action_code ] ?? $action_code;
413	}
414
415	public static function get_default_capabilities_list_for_agent_role() {
416	$capabilities = [
417	'agent__view',
418	'agent__edit' ,
419	'booking__view',
420	'booking__delete' ,
421	'booking__create',
422	'booking__edit',
423	'customer__view',
424	'customer__delete' ,
425	'customer__create',
426	'customer__edit',
427	'transaction__view',
428	'transaction__delete' ,
429	'transaction__create',
430	'transaction__edit',
431	'invoice__view',
432	'invoice__delete' ,
433	'invoice__create',
434	'invoice__edit',
435	'activity__view',
436	'activity__delete' ,
437	'activity__create',
438	'activity__edit',
439	'chat__edit',
440	'resource_schedule__edit',
441	];
442
443	/**
444	* Default list of permitted actions available for agent user type
445	*
446	* @since 4.7.0
447	* @hook latepoint_roles_get_default_capabilities_list_for_agent_role
448	*
449	* @param {array} $capabilities array of permitted actions available to agent user type by default
450	* @returns {array} The filtered array of permitted actions
451	*/
452	return apply_filters( 'latepoint_roles_get_default_capabilities_list_for_agent_role', $capabilities );
453	}
454
455	public static function get_all_available_actions_list() {
456	$actions = [
457	'agent__view',
458	'agent__delete' ,
459	'agent__create',
460	'agent__edit' ,
461	'service__view',
462	'service__delete' ,
463	'service__create',
464	'service__edit' ,
465	'bundle__view',
466	'bundle__delete' ,
467	'bundle__create',
468	'bundle__edit' ,
469	'location__view',
470	'location__delete' ,
471	'location__create',
472	'location__edit' ,
473	'service_extra__view',
474	'service_extra__delete' ,
475	'service_extra__create',
476	'service_extra__edit' ,
477	'booking__view',
478	'booking__delete' ,
479	'booking__create',
480	'booking__edit' ,
481	'customer__view',
482	'customer__delete' ,
483	'customer__create',
484	'customer__edit' ,
485	'transaction__view',
486	'transaction__delete' ,
487	'transaction__create',
488	'transaction__edit' ,
489	'invoice__view',
490	'invoice__delete' ,
491	'invoice__create',
492	'invoice__edit' ,
493	'activity__view',
494	'activity__delete' ,
495	'activity__create',
496	'activity__edit' ,
497	'chat__edit',
498	'resource_schedule__edit',
499	'settings__edit',
500	'connection__edit',
501	];
502
503	/**
504	* All available actions to be attached to a user role
505	*
506	* @since 4.7.0
507	* @hook latepoint_roles_get_all_available_actions_list
508	*
509	* @param {array} $actions array of actions that can be attached to a user role
510	* @returns {array} The filtered array of actions
511	*/
512	return apply_filters( 'latepoint_roles_get_all_available_actions_list', $actions );
513	}
514
515	/**
516	* @param \LatePoint\Misc\Role $role
517	* @return \LatePoint\Misc\User[]
518	*/
519	public static function get_users_for_role( \LatePoint\Misc\Role $role ): array {
520	$users = [];
521	$wp_users = [];
522	switch ( $role->user_type ) {
523	case LATEPOINT_USER_TYPE_ADMIN:
524	$wp_users = get_users( [ 'role__in' => LATEPOINT_WP_ADMIN_ROLE ] );
525	break;
526	case LATEPOINT_USER_TYPE_AGENT:
527	$wp_users = get_users( [ 'role' => LATEPOINT_WP_AGENT_ROLE ] );
528	break;
529	case LATEPOINT_USER_TYPE_CUSTOM:
530	if ( $role->wp_role ) {
531	$wp_users = get_users( [ 'role' => $role->wp_role ] );
532	}
533	break;
534	}
535	foreach ( $wp_users as $wp_user ) {
536	$users[] = \LatePoint\Misc\User::load_from_wp_user( $wp_user );
537	}
538	return $users;
539	}
540
541	public static function get_user_roles( $user ): array {
542	return [];
543	}
544
545	/**
546	* Checks if currently logged in user has certain capabilities
547	*
548	* @param array\|string $capabilities array or string of capabilities that you want to check if logged in user has or not
549	* @return bool
550	*/
551	public static function can_user( $capabilities ): bool {
552	if ( OsAuthHelper::get_current_user() ) {
553	return OsAuthHelper::get_current_user()->has_capability( $capabilities );
554	}
555
556	return false;
557	}
558
559	public static function get_allowed_records( string $model_type, $load_from_db = false ) {
560	return OsAuthHelper::get_current_user()->get_allowed_records( $model_type, $load_from_db );
561	}
562
563	public static function are_all_records_allowed( string $model_type = '', $load_from_db = false ): bool {
564	return OsAuthHelper::get_current_user()->are_all_records_allowed( $model_type, $load_from_db );
565	}
566
567	/*
568	* Pass filter object or an array of arguments for a query to be filtered based on what logged in user is allowed to access
569	*/
570	public static function filter_allowed_records_from_arguments_or_filter( $args_or_filter ) {
571	$model_types = [ 'agent', 'location', 'service' ];
572	foreach ( $model_types as $model_type ) {
573	if ( ! OsAuthHelper::get_current_user()->are_all_records_allowed( $model_type ) ) {
574	$prop = $model_type . '_id';
575
576	// get value that needs to be filtered by allowed records
577	$value = ( $args_or_filter instanceof \LatePoint\Misc\Filter ) ? $args_or_filter->$prop ?? [] : $args_or_filter[ $prop ] ?? [];
578
579	if ( empty( $value ) ) {
580	// no value is set - limit it to allowed records
581	$value = OsAuthHelper::get_current_user()->get_allowed_records( $model_type );
582	} else {
583	// value is set - make sure it's in the allowed records list, if not - set to allowed records
584	$allowed_from_set = array_intersect( is_array( $value ) ? $value : [ $value ], OsAuthHelper::get_current_user()->get_allowed_records( $model_type ) );
585	$value = empty( $allowed_from_set ) ? OsAuthHelper::get_current_user()->get_allowed_records( $model_type ) : $allowed_from_set;
586	}
587	if ( $args_or_filter instanceof \LatePoint\Misc\Filter ) {
588	$args_or_filter->$prop = $value;
589	} elseif ( is_array( $args_or_filter ) ) {
590	$args_or_filter[ $prop ] = $value;
591	}
592	}
593	}
594	return $args_or_filter;
595	}
596	}
597