1<?php
  2/**
  3 * User API: WP_Roles class
  4 *
  5 * @package WordPress
  6 * @subpackage Users
  7 * @since 4.4.0
  8 */
  9
 10/**
 11 * Core class used to implement a user roles API.
 12 *
 13 * The role option is simple, the structure is organized by role name that store
 14 * the name in value of the 'name' key. The capabilities are stored as an array
 15 * in the value of the 'capability' key.
 16 *
 17 *     array (
 18 *          'rolename' => array (
 19 *              'name' => 'rolename',
 20 *              'capabilities' => array()
 21 *          )
 22 *     )
 23 *
 24 * @since 2.0.0
 25 */
 26#[AllowDynamicProperties]
 27class WP_Roles {
 28	/**
 29	 * List of roles and capabilities.
 30	 *
 31	 * @since 2.0.0
 32	 * @var array[]
 33	 */
 34	public $roles;
 35
 36	/**
 37	 * List of the role objects.
 38	 *
 39	 * @since 2.0.0
 40	 * @var WP_Role[]
 41	 */
 42	public $role_objects = array();
 43
 44	/**
 45	 * List of role names.
 46	 *
 47	 * @since 2.0.0
 48	 * @var string[]
 49	 */
 50	public $role_names = array();
 51
 52	/**
 53	 * Option name for storing role list.
 54	 *
 55	 * @since 2.0.0
 56	 * @var string
 57	 */
 58	public $role_key;
 59
 60	/**
 61	 * Whether to use the database for retrieval and storage.
 62	 *
 63	 * @since 2.1.0
 64	 * @var bool
 65	 */
 66	public $use_db = true;
 67
 68	/**
 69	 * The site ID the roles are initialized for.
 70	 *
 71	 * @since 4.9.0
 72	 * @var int
 73	 */
 74	protected $site_id = 0;
 75
 76	/**
 77	 * Constructor.
 78	 *
 79	 * @since 2.0.0
 80	 * @since 4.9.0 The `$site_id` argument was added.
 81	 *
 82	 * @global array $wp_user_roles Used to set the 'roles' property value.
 83	 *
 84	 * @param int $site_id Site ID to initialize roles for. Default is the current site.
 85	 */
 86	public function __construct( $site_id = null ) {
 87		global $wp_user_roles;
 88
 89		$this->use_db = empty( $wp_user_roles );
 90
 91		$this->for_site( $site_id );
 92	}
 93
 94	/**
 95	 * Makes private/protected methods readable for backward compatibility.
 96	 *
 97	 * @since 4.0.0
 98	 *
 99	 * @param string $name      Method to call.
100	 * @param array  $arguments Arguments to pass when calling.
101	 * @return mixed|false Return value of the callback, false otherwise.
102	 */
103	public function __call( $name, $arguments ) {
104		if ( '_init' === $name ) {
105			return $this->_init( ...$arguments );
106		}
107		return false;
108	}
109
110	/**
111	 * Sets up the object properties.
112	 *
113	 * The role key is set to the current prefix for the $wpdb object with
114	 * 'user_roles' appended. If the $wp_user_roles global is set, then it will
115	 * be used and the role option will not be updated or used.
116	 *
117	 * @since 2.1.0
118	 * @deprecated 4.9.0 Use WP_Roles::for_site()
119	 */
120	protected function _init() {
121		_deprecated_function( __METHOD__, '4.9.0', 'WP_Roles::for_site()' );
122
123		$this->for_site();
124	}
125
126	/**
127	 * Reinitializes the object.
128	 *
129	 * Recreates the role objects. This is typically called only by switch_to_blog()
130	 * after switching wpdb to a new site ID.
131	 *
132	 * @since 3.5.0
133	 * @deprecated 4.7.0 Use WP_Roles::for_site()
134	 */
135	public function reinit() {
136		_deprecated_function( __METHOD__, '4.7.0', 'WP_Roles::for_site()' );
137
138		$this->for_site();
139	}
140
141	/**
142	 * Adds a role name with capabilities to the list.
143	 *
144	 * Updates the list of roles, if the role doesn't already exist.
145	 *
146	 * The list of capabilities can be passed either as a numerically indexed array of capability names, or an
147	 * associative array of boolean values keyed by the capability name. To explicitly deny the role a capability, set
148	 * the value for that capability to false.
149	 *
150	 * Examples:
151	 *
152	 *     // Add a role that can edit posts.
153	 *     wp_roles()->add_role( 'custom_role', 'Custom Role', array(
154	 *         'read',
155	 *         'edit_posts',
156	 *     ) );
157	 *
158	 * Or, using an associative array:
159	 *
160	 *     // Add a role that can edit posts but explicitly cannot not delete them.
161	 *     wp_roles()->add_role( 'custom_role', 'Custom Role', array(
162	 *         'read' => true,
163	 *         'edit_posts' => true,
164	 *         'delete_posts' => false,
165	 *     ) );
166	 *
167	 * @since 2.0.0
168	 * @since 6.9.0 Support was added for a numerically indexed array of strings for the capabilities array.
169	 *
170	 * @param string                               $role         Role name.
171	 * @param string                               $display_name Role display name.
172	 * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
173	 *                                                           Default empty array.
174	 * @return WP_Role|void WP_Role object, if the role is added.
175	 */
176	public function add_role( $role, $display_name, $capabilities = array() ) {
177		if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
178			return;
179		}
180
181		if ( wp_is_numeric_array( $capabilities ) ) {
182			$capabilities = array_fill_keys( $capabilities, true );
183		}
184
185		$this->roles[ $role ] = array(
186			'name'         => $display_name,
187			'capabilities' => $capabilities,
188		);
189		if ( $this->use_db ) {
190			update_option( $this->role_key, $this->roles, true );
191		}
192		$this->role_objects[ $role ] = new WP_Role( $role, $capabilities );
193		$this->role_names[ $role ]   = $display_name;
194		return $this->role_objects[ $role ];
195	}
196
197	/**
198	 * Removes a role by name.
199	 *
200	 * @since 2.0.0
201	 *
202	 * @param string $role Role name.
203	 */
204	public function remove_role( $role ) {
205		if ( ! isset( $this->role_objects[ $role ] ) ) {
206			return;
207		}
208
209		unset( $this->role_objects[ $role ] );
210		unset( $this->role_names[ $role ] );
211		unset( $this->roles[ $role ] );
212
213		if ( $this->use_db ) {
214			update_option( $this->role_key, $this->roles );
215		}
216
217		if ( get_option( 'default_role' ) === $role ) {
218			update_option( 'default_role', 'subscriber' );
219		}
220	}
221
222	/**
223	 * Adds a capability to role.
224	 *
225	 * @since 2.0.0
226	 *
227	 * @param string $role  Role name.
228	 * @param string $cap   Capability name.
229	 * @param bool   $grant Optional. Whether role is capable of performing capability.
230	 *                      Default true.
231	 */
232	public function add_cap( $role, $cap, $grant = true ) {
233		if ( ! isset( $this->roles[ $role ] ) ) {
234			return;
235		}
236
237		$this->roles[ $role ]['capabilities'][ $cap ] = $grant;
238		if ( $this->use_db ) {
239			update_option( $this->role_key, $this->roles );
240		}
241	}
242
243	/**
244	 * Removes a capability from role.
245	 *
246	 * @since 2.0.0
247	 *
248	 * @param string $role Role name.
249	 * @param string $cap  Capability name.
250	 */
251	public function remove_cap( $role, $cap ) {
252		if ( ! isset( $this->roles[ $role ] ) ) {
253			return;
254		}
255
256		unset( $this->roles[ $role ]['capabilities'][ $cap ] );
257		if ( $this->use_db ) {
258			update_option( $this->role_key, $this->roles );
259		}
260	}
261
262	/**
263	 * Retrieves a role object by name.
264	 *
265	 * @since 2.0.0
266	 *
267	 * @param string $role Role name.
268	 * @return WP_Role|null WP_Role object if found, null if the role does not exist.
269	 */
270	public function get_role( $role ) {
271		if ( isset( $this->role_objects[ $role ] ) ) {
272			return $this->role_objects[ $role ];
273		} else {
274			return null;
275		}
276	}
277
278	/**
279	 * Retrieves a list of role names.
280	 *
281	 * @since 2.0.0
282	 *
283	 * @return string[] List of role names.
284	 */
285	public function get_names() {
286		return $this->role_names;
287	}
288
289	/**
290	 * Determines whether a role name is currently in the list of available roles.
291	 *
292	 * @since 2.0.0
293	 *
294	 * @param string $role Role name to look up.
295	 * @return bool
296	 */
297	public function is_role( $role ) {
298		return isset( $this->role_names[ $role ] );
299	}
300
301	/**
302	 * Initializes all of the available roles.
303	 *
304	 * @since 4.9.0
305	 */
306	public function init_roles() {
307		if ( empty( $this->roles ) ) {
308			return;
309		}
310
311		$this->role_objects = array();
312		$this->role_names   = array();
313		foreach ( array_keys( $this->roles ) as $role ) {
314			$this->role_objects[ $role ] = new WP_Role( $role, $this->roles[ $role ]['capabilities'] );
315			$this->role_names[ $role ]   = $this->roles[ $role ]['name'];
316		}
317
318		/**
319		 * Fires after the roles have been initialized, allowing plugins to add their own roles.
320		 *
321		 * @since 4.7.0
322		 *
323		 * @param WP_Roles $wp_roles A reference to the WP_Roles object.
324		 */
325		do_action( 'wp_roles_init', $this );
326	}
327
328	/**
329	 * Sets the site to operate on. Defaults to the current site.
330	 *
331	 * @since 4.9.0
332	 *
333	 * @global wpdb $wpdb WordPress database abstraction object.
334	 *
335	 * @param int $site_id Site ID to initialize roles for. Default is the current site.
336	 */
337	public function for_site( $site_id = null ) {
338		global $wpdb;
339
340		if ( ! empty( $site_id ) ) {
341			$this->site_id = absint( $site_id );
342		} else {
343			$this->site_id = get_current_blog_id();
344		}
345
346		$this->role_key = $wpdb->get_blog_prefix( $this->site_id ) . 'user_roles';
347
348		if ( ! empty( $this->roles ) && ! $this->use_db ) {
349			return;
350		}
351
352		$this->roles = $this->get_roles_data();
353
354		$this->init_roles();
355	}
356
357	/**
358	 * Gets the ID of the site for which roles are currently initialized.
359	 *
360	 * @since 4.9.0
361	 *
362	 * @return int Site ID.
363	 */
364	public function get_site_id() {
365		return $this->site_id;
366	}
367
368	/**
369	 * Gets the available roles data.
370	 *
371	 * @since 4.9.0
372	 *
373	 * @global array $wp_user_roles Used to set the 'roles' property value.
374	 *
375	 * @return array Roles array.
376	 */
377	protected function get_roles_data() {
378		global $wp_user_roles;
379
380		if ( ! empty( $wp_user_roles ) ) {
381			return $wp_user_roles;
382		}
383
384		if ( is_multisite() && get_current_blog_id() !== $this->site_id ) {
385			remove_action( 'switch_blog', 'wp_switch_roles_and_user', 1 );
386
387			$roles = get_blog_option( $this->site_id, $this->role_key, array() );
388
389			add_action( 'switch_blog', 'wp_switch_roles_and_user', 1, 2 );
390
391			return $roles;
392		}
393
394		return get_option( $this->role_key, array() );
395	}
396}
397