class-acf-field-user.php — Secure Custom Fields 6.9.1

secure-custom-fields / includes / fields / class-acf-field-user.php

secure-custom-fields / includes / fields Last commit date

class-acf-field-user.php

756 lines

1	<?php
2
3	if ( ! class_exists( 'ACF_Field_User' ) ) :
4
5	/**
6	* ACF_Field_User Class
7	*/
8	class ACF_Field_User extends acf_field {
9
10
11	/**
12	* Initializes the field type.
13	*
14	* @date 5/03/2014
15	* @since ACF 5.0.0
16	*/
17	function initialize() {
18	$this->name = 'user';
19	$this->label = __( 'User', 'secure-custom-fields' );
20	$this->category = 'relational';
21	$this->description = __( 'Allows the selection of one or more users which can be used to create relationships between data objects.', 'secure-custom-fields' );
22	$this->preview_image = acf_get_url() . '/assets/images/field-type-previews/field-preview-user.png';
23	$this->doc_url = 'https://developer.wordpress.org/secure-custom-fields/features/fields/user/';
24	$this->tutorial_url = 'https://developer.wordpress.org/secure-custom-fields/features/fields/user/user-tutorial/';
25	$this->defaults = array(
26	'role' => '',
27	'multiple' => 0,
28	'allow_null' => 0,
29	'return_format' => 'array',
30	'bidirectional_target' => array(),
31	);
32
33	// Register filter variations.
34	acf_add_filter_variations( 'acf/fields/user/query', array( 'name', 'key' ), 1 );
35	acf_add_filter_variations( 'acf/fields/user/result', array( 'name', 'key' ), 2 );
36	acf_add_filter_variations( 'acf/fields/user/search_columns', array( 'name', 'key' ), 3 );
37	add_filter( 'acf/conditional_logic/choices', array( $this, 'render_field_user_conditional_choices' ), 10, 3 );
38
39	// Add AJAX query.
40	add_action( 'wp_ajax_acf/fields/user/query', array( $this, 'ajax_query' ) );
41	add_action( 'wp_ajax_nopriv_acf/fields/user/query', array( $this, 'ajax_query' ) );
42	}
43
44	/**
45	* Filters choices in user conditions.
46	*
47	* @since ACF 6.3
48	*
49	* @param array $choices The selected choice.
50	* @param array $conditional_field The conditional field settings object.
51	* @param string $rule_value The rule value.
52	* @return array
53	*/
54	public function render_field_user_conditional_choices( $choices, $conditional_field, $rule_value ) {
55	if ( ! is_array( $conditional_field ) \|\| $conditional_field['type'] !== 'user' ) {
56	return $choices;
57	}
58	if ( ! empty( $rule_value ) ) {
59	$user = acf_get_users(
60	array(
61	'include' => array( $rule_value ),
62	)
63	);
64
65	$user_result = acf_get_user_result( $user[0] );
66	$choices = array( $user_result['id'] => $user_result['text'] );
67	}
68
69	return $choices;
70	}
71
72	/**
73	* Renders the field settings HTML.
74	*
75	* @date 23/01/13
76	* @since ACF 3.6.0
77	*
78	* @param array $field The ACF field.
79	* @return void
80	*/
81	function render_field_settings( $field ) {
82	acf_render_field_setting(
83	$field,
84	array(
85	'label' => __( 'Filter by Role', 'secure-custom-fields' ),
86	'instructions' => '',
87	'type' => 'select',
88	'name' => 'role',
89	'choices' => acf_get_user_role_labels(),
90	'multiple' => 1,
91	'ui' => 1,
92	'allow_null' => 1,
93	'placeholder' => __( 'All user roles', 'secure-custom-fields' ),
94	)
95	);
96
97	acf_render_field_setting(
98	$field,
99	array(
100	'label' => __( 'Return Format', 'secure-custom-fields' ),
101	'instructions' => '',
102	'type' => 'radio',
103	'name' => 'return_format',
104	'choices' => array(
105	'array' => __( 'User Array', 'secure-custom-fields' ),
106	'object' => __( 'User Object', 'secure-custom-fields' ),
107	'id' => __( 'User ID', 'secure-custom-fields' ),
108	),
109	'layout' => 'horizontal',
110	)
111	);
112
113	acf_render_field_setting(
114	$field,
115	array(
116	'label' => __( 'Select Multiple', 'secure-custom-fields' ),
117	'instructions' => 'Allow content editors to select multiple values',
118	'name' => 'multiple',
119	'type' => 'true_false',
120	'ui' => 1,
121	)
122	);
123	}
124
125	/**
126	* Renders the field settings used in the "Validation" tab.
127	*
128	* @since ACF 6.0
129	*
130	* @param array $field The field settings array.
131	* @return void
132	*/
133	function render_field_validation_settings( $field ) {
134	acf_render_field_setting(
135	$field,
136	array(
137	'label' => __( 'Allow Null', 'secure-custom-fields' ),
138	'instructions' => '',
139	'name' => 'allow_null',
140	'type' => 'true_false',
141	'ui' => 1,
142	)
143	);
144	}
145
146	/**
147	* Renders the field settings used in the "Advanced" tab.
148	*
149	* @since ACF 6.2
150	*
151	* @param array $field The field settings array.
152	* @return void
153	*/
154	public function render_field_advanced_settings( $field ) {
155	acf_render_bidirectional_field_settings( $field );
156	}
157
158	/**
159	* Renders the field input HTML.
160	*
161	* @since ACF 3.6.0
162	*
163	* @param array $field The ACF field.
164	* @return void
165	*/
166	public function render_field( $field ) {
167	// Change Field into a select.
168	$field['type'] = 'select';
169	$field['ui'] = 1;
170	$field['ajax'] = 1;
171	$field['choices'] = array();
172	$field['nonce'] = wp_create_nonce( 'acf_field_' . $this->name . '_' . $field['key'] );
173
174	// Populate choices.
175	if ( $field['value'] ) {
176
177	// Clean value into an array of IDs.
178	$user_ids = array_map( 'intval', acf_array( $field['value'] ) );
179
180	// Find users in database (ensures all results are real).
181	$users = acf_get_users(
182	array(
183	'include' => $user_ids,
184	)
185	);
186
187	// Append.
188	if ( $users ) {
189	foreach ( $users as $user ) {
190	$field['choices'][ $user->ID ] = $this->get_result( $user, $field );
191	}
192	}
193	}
194
195	// Render.
196	acf_render_field( $field );
197	}
198
199	/**
200	* Returns the result text for a given WP_User object.
201	*
202	* @date 1/11/2013
203	* @since ACF 5.0.0
204	*
205	* @param WP_User $user The WP_User object.
206	* @param array $field The ACF field related to this query.
207	* @param (int\|string) $post_id The post_id being edited.
208	* @return string
209	*/
210	function get_result( $user, $field, $post_id = 0 ) {
211
212	// Get user result item.
213	$item = acf_get_user_result( $user );
214
215	// Default $post_id to current post being edited.
216	$post_id = $post_id ? $post_id : acf_get_form_data( 'post_id' );
217
218	/**
219	* Filters the result text.
220	*
221	* @date 21/5/19
222	* @since ACF 5.8.1
223	*
224	* @param string $item['text'] The user text.
225	* @param WP_User $user The user object.
226	* @param array $field The ACF field related to this query.
227	* @param (int\|string) $post_id The post_id being edited.
228	*/
229	return apply_filters( 'acf/fields/user/result', $item['text'], $user, $field, $post_id );
230	}
231
232	/**
233	* Filters the field value after it is loaded from the database.
234	*
235	* @date 23/01/13
236	* @since ACF 3.6.0
237	*
238	* @param mixed $value The field value.
239	* @param mixed $post_id The post ID where the value is saved.
240	* @param array $field The field array containing all settings.
241	* @return mixed
242	*/
243	function load_value( $value, $post_id, $field ) {
244
245	// Add compatibility for version 4.
246	if ( $value === 'null' ) {
247	return false;
248	}
249	return $value;
250	}
251
252	/**
253	* Filters the field value after it is loaded from the database but before it is returned to the front-end API.
254	*
255	* @date 23/01/13
256	* @since ACF 3.6.0
257	*
258	* @param mixed $value The field value.
259	* @param mixed $post_id The post ID where the value is saved.
260	* @param array $field The field array containing all settings.
261	* @return mixed
262	*/
263	function format_value( $value, $post_id, $field ) {
264
265	// Bail early if no value.
266	if ( ! $value ) {
267	return false;
268	}
269
270	// Clean value into an array of IDs.
271	$user_ids = array_map( 'intval', acf_array( $value ) );
272
273	// Find users in database (ensures all results are real).
274	$users = acf_get_users(
275	array(
276	'include' => $user_ids,
277	)
278	);
279
280	// Bail early if no users found.
281	if ( ! $users ) {
282	return false;
283	}
284
285	// Format values using field settings.
286	$value = array();
287	foreach ( $users as $user ) {
288
289	// Return object.
290	if ( $field['return_format'] == 'object' ) {
291	$item = $user;
292
293	// Return array.
294	} elseif ( $field['return_format'] == 'array' ) {
295	$item = array(
296	'ID' => $user->ID,
297	'user_firstname' => $user->user_firstname,
298	'user_lastname' => $user->user_lastname,
299	'nickname' => $user->nickname,
300	'user_nicename' => $user->user_nicename,
301	'display_name' => $user->display_name,
302	'user_email' => $user->user_email,
303	'user_url' => $user->user_url,
304	'user_registered' => $user->user_registered,
305	'user_description' => $user->user_description,
306	'user_avatar' => get_avatar( $user->ID ),
307	);
308
309	// Return ID.
310	} else {
311	$item = $user->ID;
312	}
313
314	// Append item
315	$value[] = $item;
316	}
317
318	// Convert to single.
319	if ( ! $field['multiple'] ) {
320	$value = array_shift( $value );
321	}
322
323	// Return.
324	return $value;
325	}
326
327	/**
328	* Filters the field value before it is saved into the database.
329	*
330	* @since ACF 3.6.0
331	*
332	* @param mixed $value The field value.
333	* @param mixed $post_id The post ID where the value is saved.
334	* @param array $field The field array containing all settings.
335	* @return mixed $value The modified value.
336	*/
337	public function update_value( $value, $post_id, $field ) {
338
339	// Bail early if no value.
340	if ( empty( $value ) ) {
341	acf_update_bidirectional_values( array(), $post_id, $field, 'user' );
342	return $value;
343	}
344
345	// Format array of values.
346	// - ensure each value is an id.
347	// - Parse each id as string for SQL LIKE queries.
348	if ( acf_is_sequential_array( $value ) ) {
349	$value = array_map( 'acf_idval', $value );
350	$value = array_map( 'strval', $value );
351
352	// Parse single value for id.
353	} else {
354	$value = acf_idval( $value );
355	}
356
357	acf_update_bidirectional_values( acf_get_array( $value ), $post_id, $field, 'user' );
358
359	// Return value.
360	return $value;
361	}
362
363	/**
364	* Callback for the AJAX query request.
365	*
366	* @date 24/10/13
367	* @since ACF 5.0.0
368	*
369	* @return void
370	*/
371	function ajax_query() {
372
373	// phpcs:disable WordPress.Security.NonceVerification.Recommended
374	// Modify Request args.
375	if ( isset( $_REQUEST['s'] ) ) {
376	$_REQUEST['search'] = sanitize_text_field( $_REQUEST['s'] );
377	}
378	if ( isset( $_REQUEST['paged'] ) ) {
379	$_REQUEST['page'] = absint( $_REQUEST['paged'] );
380	}
381	// phpcs:enable WordPress.Security.NonceVerification.Recommended
382
383	// Add query hooks.
384	add_action( 'acf/ajax/query_users/init', array( $this, 'ajax_query_init' ), 10, 2 );
385	add_filter( 'acf/ajax/query_users/args', array( $this, 'ajax_query_args' ), 10, 3 );
386	add_filter( 'acf/ajax/query_users/result', array( $this, 'ajax_query_result' ), 10, 3 );
387	add_filter( 'acf/ajax/query_users/search_columns', array( $this, 'ajax_query_search_columns' ), 10, 4 );
388	// Simulate AJAX request.
389	acf_get_instance( 'ACF_Ajax_Query_Users' )->request();
390	}
391
392	/**
393	* Runs during the AJAX query initialization.
394	*
395	* @date 9/3/20
396	* @since ACF 5.8.8
397	*
398	* @param array $request The query request.
399	* @param ACF_Ajax_Query $query The query object.
400	* @return void
401	*/
402	function ajax_query_init( $request, $query ) {
403	// Require field and make sure it's a user field.
404	if ( ! $query->field \|\| $query->field['type'] !== $this->name ) {
405	$query->send( new WP_Error( 'acf_missing_field', __( 'Error loading field.', 'secure-custom-fields' ), array( 'status' => 404 ) ) );
406	}
407
408	// Verify that this is a legitimate request using a separate nonce from the main AJAX nonce.
409	$nonce = acf_request_arg( 'nonce', '' );
410	$key = acf_request_arg( 'field_key', '' );
411
412	if ( ! acf_verify_ajax( $nonce, $key, true, 'user' ) ) {
413	$query->send( new WP_Error( 'acf_invalid_request', __( 'Invalid request.', 'secure-custom-fields' ), array( 'status' => 404 ) ) );
414	}
415	}
416
417	/**
418	* Filters the AJAX query args.
419	*
420	* @date 9/3/20
421	* @since ACF 5.8.8
422	*
423	* @param array $args The query args.
424	* @param array $request The query request.
425	* @param ACF_Ajax_Query $query The query object.
426	* @return array
427	*/
428	function ajax_query_args( $args, $request, $query ) {
429
430	// Add specific roles.
431	if ( $query->field['role'] ) {
432	$args['role__in'] = acf_array( $query->field['role'] );
433	}
434
435	/**
436	* Filters the query args.
437	*
438	* @date 21/5/19
439	* @since ACF 5.8.1
440	*
441	* @param array $args The query args.
442	* @param array $field The ACF field related to this query.
443	* @param (int\|string) $post_id The post_id being edited.
444	*/
445	return apply_filters( 'acf/fields/user/query', $args, $query->field, $query->post_id );
446	}
447
448	/**
449	* Filters the WP_User_Query search columns.
450	*
451	* @date 9/3/20
452	* @since ACF 5.8.8
453	*
454	* @param array $columns An array of column names to be searched.
455	* @param string $search The search term.
456	* @param WP_User_Query $WP_User_Query The WP_User_Query instance.
457	* @return array
458	*/
459	function ajax_query_search_columns( $columns, $search, $WP_User_Query, $query ) {
460
461	/**
462	* Filters the column names to be searched.
463	*
464	* @date 21/5/19
465	* @since ACF 5.8.1
466	*
467	* @param array $columns An array of column names to be searched.
468	* @param string $search The search term.
469	* @param WP_User_Query $WP_User_Query The WP_User_Query instance.
470	* @param array $field The ACF field related to this query.
471	*/
472	return apply_filters( 'acf/fields/user/search_columns', $columns, $search, $WP_User_Query, $query->field );
473	}
474
475	/**
476	* Filters the AJAX Query result.
477	*
478	* @date 9/3/20
479	* @since ACF 5.8.8
480	*
481	* @param array $item The choice id and text.
482	* @param WP_User $user The user object.
483	* @param ACF_Ajax_Query $query The query object.
484	* @return array
485	*/
486	function ajax_query_result( $item, $user, $query ) {
487
488	/**
489	* Filters the result text.
490	*
491	* @date 21/5/19
492	* @since ACF 5.8.1
493	*
494	* @param string $item['text'] The result text.
495	* @param WP_User $user The user object.
496	* @param array $field The ACF field related to this query.
497	* @param (int\|string) $post_id The post_id being edited.
498	*/
499	$item['text'] = apply_filters( 'acf/fields/user/result', $item['text'], $user, $query->field, $query->post_id );
500	return $item;
501	}
502
503	/**
504	* Return an array of data formatted for use in a select2 AJAX response.
505	*
506	* @date 15/10/2014
507	* @since ACF 5.0.9
508	* @deprecated 5.8.9
509	*
510	* @param array $args An array of query args.
511	* @return array
512	*/
513	function get_ajax_query( $options = array() ) {
514	_deprecated_function( __FUNCTION__, '5.8.9' );
515	return array();
516	}
517
518	/**
519	* Filters the WP_User_Query search columns.
520	*
521	* @date 15/10/2014
522	* @since ACF 5.0.9
523	* @deprecated 5.8.9
524	*
525	* @param array $columns An array of column names to be searched.
526	* @param string $search The search term.
527	* @param WP_User_Query $WP_User_Query The WP_User_Query instance.
528	* @return array
529	*/
530	function user_search_columns( $columns, $search, $WP_User_Query ) {
531	_deprecated_function( __FUNCTION__, '5.8.9' );
532	return $columns;
533	}
534
535	/**
536	* Validates user fields updated via the REST API.
537	*
538	* @param boolean $valid The current validity boolean.
539	* @param integer $value The value of the field.
540	* @param array $field The field array.
541	* @return boolean\|WP_Error
542	*/
543	public function validate_rest_value( $valid, $value, $field ) {
544	if ( is_null( $value ) ) {
545	return $valid;
546	}
547
548	$param = sprintf( '%s[%s]', $field['prefix'], $field['name'] );
549	$data = array( 'param' => $param );
550	$value = is_array( $value ) ? $value : array( $value );
551
552	$invalid_users = array();
553	$insufficient_roles = array();
554
555	foreach ( $value as $user_id ) {
556	$user_data = get_userdata( $user_id );
557	if ( ! $user_data ) {
558	$invalid_users[] = $user_id;
559	continue;
560	}
561
562	if ( empty( $field['role'] ) ) {
563	continue;
564	}
565
566	$has_roles = count( array_intersect( $field['role'], $user_data->roles ) );
567	if ( ! $has_roles ) {
568	$insufficient_roles[] = $user_id;
569	}
570	}
571
572	if ( count( $invalid_users ) ) {
573	$error = sprintf(
574	/* translators: %s: field value */
575	__( '%1$s must have a valid user ID.', 'secure-custom-fields' ),
576	$param
577	);
578	$data['value'] = $invalid_users;
579	return new WP_Error( 'rest_invalid_param', $error, $data );
580	}
581
582	if ( count( $insufficient_roles ) ) {
583	$error = sprintf(
584	/* translators: 1: field name, 2: role name */
585	_n(
586	'%1$s must have a user with the %2$s role.',
587	'%1$s must have a user with one of the following roles: %2$s',
588	count( $field['role'] ),
589	'secure-custom-fields'
590	),
591	$param,
592	count( $field['role'] ) > 1 ? implode( ', ', $field['role'] ) : $field['role'][0]
593	);
594	$data['value'] = $insufficient_roles;
595	return new WP_Error( 'rest_invalid_param', $error, $data );
596	}
597
598	return $valid;
599	}
600
601	/**
602	* Return the schema array for the REST API.
603	*
604	* @param array $field
605	* @return array
606	*/
607	public function get_rest_schema( array $field ) {
608	$schema = array(
609	'type' => array( 'integer', 'array', 'null' ),
610	'required' => ! empty( $field['required'] ),
611	'items' => array(
612	'type' => 'integer',
613	),
614	);
615
616	if ( empty( $field['allow_null'] ) ) {
617	$schema['minItems'] = 1;
618	}
619
620	if ( empty( $field['multiple'] ) ) {
621	$schema['maxItems'] = 1;
622	}
623
624	return $schema;
625	}
626
627	/**
628	* @see \acf_field::get_rest_links()
629	* @param mixed $value The raw (unformatted) field value.
630	* @param integer\|string $post_id
631	* @param array $field
632	* @return array
633	*/
634	public function get_rest_links( $value, $post_id, array $field ) {
635	$links = array();
636
637	if ( empty( $value ) ) {
638	return $links;
639	}
640
641	foreach ( (array) $value as $object_id ) {
642	$links[] = array(
643	'rel' => 'acf:user',
644	'href' => rest_url( '/wp/v2/users/' . $object_id ),
645	'embeddable' => true,
646	);
647	}
648
649	return $links;
650	}
651
652	/**
653	* Apply basic formatting to prepare the value for default REST output.
654	*
655	* @param mixed $value
656	* @param string\|integer $post_id
657	* @param array $field
658	* @return mixed
659	*/
660	public function format_value_for_rest( $value, $post_id, array $field ) {
661	return acf_format_numerics( $value );
662	}
663
664	/**
665	* Formats the field value for JSON-LD output.
666	*
667	* @since 6.8.0
668	*
669	* @param mixed $value The value of the field.
670	* @param integer\|string $post_id The ID of the post.
671	* @param array $field The field array.
672	* @return mixed
673	*/
674	public function format_value_for_jsonld( $value, $post_id, $field ) {
675	if ( empty( $value ) ) {
676	return null;
677	}
678
679	// Get output format with fallback.
680	$output_format = $field['schema_output_format'] ?? '';
681	if ( empty( $output_format ) ) {
682	$property = $field['schema_property'] ?? '';
683	$output_format = \SCF\AI\GEO\Schema::get_default_output_format( $this->name, $property );
684	}
685
686	// Default to Person if still empty.
687	if ( empty( $output_format ) ) {
688	$output_format = 'Person';
689	}
690
691	$field['return_format'] = 'object';
692	$users = $this->format_value( $value, $post_id, $field );
693
694	if ( ! $users ) {
695	return null;
696	}
697
698	// Handle single user.
699	if ( $users instanceof \WP_User ) {
700	return $this->format_user_for_jsonld( $users, $output_format );
701	}
702
703	// Handle multiple users.
704	$formatted = array();
705	if ( is_array( $users ) ) {
706	foreach ( $users as $user ) {
707	if ( $user instanceof \WP_User ) {
708	$formatted[] = $this->format_user_for_jsonld( $user, $output_format );
709	}
710	}
711	}
712
713	return $formatted;
714	}
715
716	/**
717	* Format a single user for JSON-LD output.
718	*
719	* @since 6.8.0
720	*
721	* @param \WP_User $user The user object.
722	* @param string $output_format The output format (Person or Organization).
723	* @return array The formatted user data.
724	*/
725	private function format_user_for_jsonld( $user, $output_format ) {
726	$data = array(
727	'@type' => $output_format,
728	'name' => $user->get( 'display_name' ),
729	);
730
731	// Add URL if available.
732	$url = $user->get( 'user_url' );
733	if ( $url ) {
734	$data['url'] = $url;
735	}
736
737	return $data;
738	}
739
740	/**
741	* Returns an array of JSON-LD Property output types that are supported by this field type.
742	*
743	* @since 6.8
744	*
745	* @return string[]
746	*/
747	public function get_jsonld_output_types(): array {
748	return array( 'Person', 'Organization' );
749	}
750	}
751
752
753	// initialize
754	acf_register_field_type( 'ACF_Field_User' );
755	endif; // class_exists check
756