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