acf-bidirectional-functions.php — Advanced Custom Fields (ACF®) 6.8.7

advanced-custom-fields / includes / acf-bidirectional-functions.php

advanced-custom-fields / includes Last commit date

acf-bidirectional-functions.php

279 lines

1	<?php
2	/**
3	* @package ACF
4	* @author WP Engine
5	*
6	* © 2026 Advanced Custom Fields (ACF®). All rights reserved.
7	* "ACF" is a trademark of WP Engine.
8	* Licensed under the GNU General Public License v2 or later.
9	* https://www.gnu.org/licenses/gpl-2.0.html
10	*/
11
12	/**
13	* Process updating bidirectional fields.
14	*
15	* @since 6.2
16	*
17	* @param array $target_item_ids The post, user or term IDs which should be updated with the origin item ID.
18	* @param integer\|string $post_id The ACF encoded origin post, user or term ID.
19	* @param array $field The field being updated on the origin post, user or term ID.
20	* @param string\|false $target_prefix The ACF prefix for a post, user or term ID required for the update_field call for this field type.
21	*/
22	function acf_update_bidirectional_values( $target_item_ids, $post_id, $field, $target_prefix = false ) {
23
24	// Bail early if we're already updating a bidirectional relationship to prevent recursion.
25	if ( acf_get_data( 'acf_doing_bidirectional_update' ) ) {
26	return;
27	}
28
29	// Support disabling bidirectionality globally.
30	if ( ! acf_get_setting( 'enable_bidirection' ) ) {
31	return;
32	}
33
34	if ( empty( $field['bidirectional'] ) \|\| empty( $field['bidirectional_target'] ) ) {
35	return;
36	}
37
38	$decoded = acf_decode_post_id( $post_id );
39	$item_id = $decoded['id'];
40	$valid_target_types = acf_get_valid_bidirectional_target_types( $decoded['type'] );
41	$valid_targets = array();
42
43	foreach ( $field['bidirectional_target'] as $target_field ) {
44	$target_field_object = get_field_object( $target_field );
45	if ( empty( $target_field_object ) \|\| ! is_array( $target_field_object ) ) {
46	continue;
47	}
48	if ( in_array( $target_field_object['type'], $valid_target_types, true ) ) {
49	$valid_targets[] = $target_field;
50	}
51	}
52
53	if ( ! empty( $valid_targets ) ) {
54
55	// Get current values for this field.
56	$current_values = array_filter( acf_get_array( get_field( $field['key'], $post_id, false ) ) );
57	$new_values = array_filter( acf_get_array( $target_item_ids ) );
58
59	$additions = array_diff( $new_values, $current_values );
60	$subtractions = array_diff( $current_values, $new_values );
61
62	// Prefix additions and subtractions for destinations which aren't posts.
63	if ( ! empty( $target_prefix ) ) {
64	$mapper = function ( $v ) use ( $target_prefix ) {
65	return $target_prefix . '_' . $v;
66	};
67	$additions = array_map( $mapper, $additions );
68	$subtractions = array_map( $mapper, $subtractions );
69	}
70
71	acf_set_data( 'acf_doing_bidirectional_update', true );
72
73	// Loop over each target, processing additions and removals.
74	foreach ( $valid_targets as $target_field ) {
75	foreach ( $additions as $addition ) {
76	$current_value = acf_get_array( get_field( $target_field, $addition, false ) );
77	update_field( $target_field, array_unique( array_merge( $current_value, array( $item_id ) ) ), $addition );
78	}
79
80	foreach ( $subtractions as $subtraction ) {
81	$current_value = acf_get_array( get_field( $target_field, $subtraction, false ) );
82	update_field( $target_field, array_unique( array_diff( $current_value, array( $item_id ) ) ), $subtraction );
83	}
84	}
85
86	acf_set_data( 'acf_doing_bidirectional_update', false );
87	}
88	}
89
90	/**
91	* Allows third party fields to enable support as a target field type for a particular object type
92	*
93	* @since 6.2
94	*
95	* @param string $object_type The object type that will be updated on the target field, such as 'term', 'user' or 'post'.
96	*
97	* @return array An array of valid field type names (slugs) for the target of the bidirectional field.
98	*/
99	function acf_get_valid_bidirectional_target_types( $object_type ) {
100	$valid_target_types = array();
101	switch ( $object_type ) {
102	case 'term':
103	$valid_target_types = array( 'taxonomy' );
104	break;
105	case 'user':
106	$valid_target_types = array( 'user' );
107	break;
108	case 'post':
109	$valid_target_types = array( 'relationship', 'post_object' );
110	break;
111	}
112	return apply_filters( 'acf/bidirectional/supported_field_types_for_post', $valid_target_types, $object_type );
113	}
114
115	/**
116	* Build the complete choices argument for rendering the select2 field for bidirectional target based on the currently selected choices
117	*
118	* @since 6.2
119	*
120	* @param array $choices The currently selected choices (as an array of field keys).
121	*
122	* @return array
123	*/
124	function acf_build_bidirectional_target_current_choices( $choices ) {
125	if ( empty( $choices ) ) {
126	return array();
127	}
128
129	$results = array();
130	foreach ( $choices as $choice ) {
131	if ( empty( $choice ) \|\| ! is_string( $choice ) ) {
132	continue;
133	}
134
135	$field_object = get_field_object( $choice );
136	if ( is_array( $field_object ) && ! empty( $field_object['label'] ) ) {
137	$results[ $choice ] = $field_object['label'];
138	} else {
139	$results[ $choice ] = $choice;
140	}
141	}
142
143	return $results;
144	}
145
146	/**
147	* Build valid fields for a bidirectional relationship for select2 display
148	*
149	* @since 6.2
150	*
151	* @param array $results The original results array.
152	* @param array $options The options provided to the select2 AJAX search.
153	*
154	* @return array
155	*/
156	function acf_build_bidirectional_relationship_field_target_args( $results, $options ) {
157	$valid_field_types = apply_filters( 'acf/bidirectional/supported_target_field_types', array( 'relationship', 'post_object', 'user', 'taxonomy' ) );
158
159	$field_groups = array_filter(
160	acf_get_field_groups(),
161	function ( $field_group ) {
162	return $field_group['active'];
163	}
164	);
165
166	$valid_fields = array();
167	foreach ( $field_groups as $field_group ) {
168	$fields = acf_get_fields( $field_group );
169	foreach ( $fields as $field ) {
170	if ( in_array( $field['type'], $valid_field_types, true ) ) {
171	if ( empty( $valid_fields[ $field_group['title'] ] ) ) {
172	$valid_fields[ $field_group['title'] ] = array();
173	}
174	$valid_fields[ $field_group['title'] ][ $field['key'] ] = array(
175	'type' => $field['type'],
176	'label' => $field['label'],
177	);
178
179	if ( isset( $options['parent_key'] ) && $options['parent_key'] === $field['key'] ) {
180	$valid_fields[ $field_group['title'] ][ $field['key'] ]['this_field'] = true;
181	}
182	}
183	}
184	}
185
186	foreach ( $valid_fields as $field_group_name => $fields ) {
187	$field_group = array(
188	'text' => $field_group_name,
189	'children' => array(),
190	);
191	foreach ( $fields as $key => $data ) {
192	$field_group['children'][] = array(
193	'id' => $key,
194	'text' => $data['label'],
195	'field_type' => $data['type'],
196	/* translators: %s A field type name, such as "Relationship" */
197	'human_field_type' => sprintf( __( '%s Field', 'acf' ), acf_get_field_type_prop( $data['type'], 'label' ) ),
198	'this_field' => ! empty( $data['this_field'] ),
199	);
200	}
201	$results['results'][] = $field_group;
202	}
203
204	return $results;
205	}
206
207	add_action( 'acf/fields/select/query/key=_acf_bidirectional_target', 'acf_build_bidirectional_relationship_field_target_args', 10, 2 );
208
209	/**
210	* Renders the field settings required for bidirectional fields
211	*
212	* @since 6.2
213	*
214	* @param array $field The field object passed into field setting functions.
215	*/
216	function acf_render_bidirectional_field_settings( $field ) {
217	if ( ! acf_get_setting( 'enable_bidirection' ) ) {
218	return;
219	}
220
221	acf_render_field_setting(
222	$field,
223	array(
224	'label' => __( 'Bidirectional', 'acf' ),
225	'instructions' => __( 'Update a field on the selected values, referencing back to this ID', 'acf' ),
226	'type' => 'true_false',
227	'name' => 'bidirectional',
228	'ui' => 1,
229	)
230	);
231
232	acf_render_field_setting(
233	$field,
234	array(
235	'name' => 'bidirectional_notes',
236	'type' => 'message',
237	'message' => acf_get_bidirectional_field_settings_instruction_text(),
238	'conditions' => array(
239	'field' => 'bidirectional',
240	'operator' => '==',
241	'value' => 1,
242	),
243	)
244	);
245
246	acf_render_field_setting(
247	$field,
248	array(
249	'type' => 'select',
250	'name' => 'bidirectional_target',
251	'label' => __( 'Target Field', 'acf' ),
252	'instructions' => __( 'Select field(s) to store the reference back to the item being updated. You may select this field. Target fields must be compatible with where this field is being displayed. For example, if this field is displayed on a Taxonomy, your target field should be of type Taxonomy', 'acf' ),
253	'class' => 'bidrectional_target',
254	'choices' => acf_build_bidirectional_target_current_choices( $field['bidirectional_target'] ),
255	'conditions' => array(
256	'field' => 'bidirectional',
257	'operator' => '==',
258	'value' => 1,
259	),
260	'ui' => 1,
261	'multiple' => 1,
262	'ajax' => 1,
263	)
264	);
265	}
266
267	/**
268	* Returns the translated instructional text for the message field for the bidirectional field settings.
269	*
270	* @since 6.2
271	*
272	* @return string The html containing the instructional message.
273	*/
274	function acf_get_bidirectional_field_settings_instruction_text() {
275	/* translators: %s the URL to ACF's bidirectional relationship documentation */
276	$message = '<p class="acf-feature-notice with-warning-icon">' . sprintf( __( 'Enabling the bidirectional setting allows you to update a value in the target fields for each value selected for this field, adding or removing the Post ID, Taxonomy ID or User ID of the item being updated. For more information, please read the <a href="%s" target="_blank">documentation</a>.', 'acf' ), acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/bidirectional-relationships/', 'docs', 'bidirectional' ) ) . '</p>';
277	return $message;
278	}
279