loop.php — Advanced Custom Fields (ACF®) 6.8.7

advanced-custom-fields / includes / loop.php

advanced-custom-fields / includes Last commit date

loop.php

294 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	if ( ! defined( 'ABSPATH' ) ) {
13	exit; // Exit if accessed directly
14	}
15
16	if ( ! class_exists( 'acf_loop' ) ) :
17	class acf_loop {
18
19	/**
20	* An array of loops.
21	* @var array
22	*/
23	public $loops = array();
24
25	/**
26	* This function will return true if no loops exist
27	*
28	* @type function
29	* @date 3/03/2016
30	* @since 5.3.2
31	*
32	* @param n/a
33	* @return (boolean)
34	*/
35	function is_empty() {
36
37	return empty( $this->loops );
38	}
39
40
41	/**
42	* This function will return true if a loop exists for the given array index
43	*
44	* @type function
45	* @date 3/03/2016
46	* @since 5.3.2
47	*
48	* @param $i (int)
49	* @return (boolean)
50	*/
51	function is_loop( $i = 0 ) {
52
53	return isset( $this->loops[ $i ] );
54	}
55
56
57	/**
58	* This function will return a valid array index for the given $i
59	*
60	* @type function
61	* @date 3/03/2016
62	* @since 5.3.2
63	*
64	* @param $i (mixed)
65	* @return (int)
66	*/
67	function get_i( $i = 0 ) {
68
69	// 'active'
70	if ( $i === 'active' ) {
71	$i = -1;
72	}
73
74	// 'previous'
75	if ( $i === 'previous' ) {
76	$i = -2;
77	}
78
79	// allow negative to look at end of loops
80	if ( $i < 0 ) {
81	$i = count( $this->loops ) + $i;
82	}
83
84	// return
85	return $i;
86	}
87
88
89	/**
90	* This function will add a new loop
91	*
92	* @type function
93	* @date 3/03/2016
94	* @since 5.3.2
95	*
96	* @param $loop (array)
97	* @return n/a
98	*/
99	function add_loop( $loop = array() ) {
100
101	// defaults
102	$loop = wp_parse_args(
103	$loop,
104	array(
105	'selector' => '',
106	'name' => '',
107	'value' => false,
108	'field' => false,
109	'i' => -1,
110	'post_id' => 0,
111	'key' => '',
112	)
113	);
114
115	// ensure array
116	$loop['value'] = acf_get_array( $loop['value'] );
117
118	// Re-index values if this loop starts from index 0.
119	// This allows ajax previews to work ($_POST data contains random unique array keys)
120	if ( $loop['i'] == -1 ) {
121	$loop['value'] = array_values( $loop['value'] );
122	}
123
124	// append
125	$this->loops[] = $loop;
126
127	// return
128	return $loop;
129	}
130
131
132	/**
133	* This function will update a loop's setting
134	*
135	* @type function
136	* @date 3/03/2016
137	* @since 5.3.2
138	*
139	* @param $i (mixed)
140	* @param $key (string) the loop setting name
141	* @param $value (mixed) the loop setting value
142	* @return (boolean) true on success
143	*/
144	function update_loop( $i = 'active', $key = null, $value = null ) {
145
146	// i
147	$i = $this->get_i( $i );
148
149	// bail early if no set
150	if ( ! $this->is_loop( $i ) ) {
151	return false;
152	}
153
154	// set
155	$this->loops[ $i ][ $key ] = $value;
156
157	// return
158	return true;
159	}
160
161
162	/**
163	* This function will return a loop, or loop's setting for a given index & key
164	*
165	* @type function
166	* @date 3/03/2016
167	* @since 5.3.2
168	*
169	* @param $i (mixed)
170	* @param $key (string) the loop setting name
171	* @return (mixed) false on failure
172	*/
173	function get_loop( $i = 'active', $key = null ) {
174
175	// i
176	$i = $this->get_i( $i );
177
178	// bail early if no set
179	if ( ! $this->is_loop( $i ) ) {
180	return false;
181	}
182
183	// check for key
184	if ( $key !== null ) {
185	return $this->loops[ $i ][ $key ];
186	}
187
188	// return
189	return $this->loops[ $i ];
190	}
191
192
193	/**
194	* This function will remove a loop
195	*
196	* @type function
197	* @date 3/03/2016
198	* @since 5.3.2
199	*
200	* @param $i (mixed)
201	* @return (boolean) true on success
202	*/
203	function remove_loop( $i = 'active' ) {
204
205	// i
206	$i = $this->get_i( $i );
207
208	// bail early if no set
209	if ( ! $this->is_loop( $i ) ) {
210	return false;
211	}
212
213	// remove
214	unset( $this->loops[ $i ] );
215
216	// reset keys
217	$this->loops = array_values( $this->loops );
218
219	// PHP 7.2 no longer resets array keys for empty value
220	if ( $this->is_empty() ) {
221	$this->loops = array();
222	}
223	}
224	}
225
226	// initialize
227	acf()->loop = new acf_loop();
228	endif; // class_exists check
229
230
231
232	/**
233	* alias of acf()->loop->add_loop()
234	*
235	* @type function
236	* @date 6/10/13
237	* @since 5.0.0
238	*
239	* @param n/a
240	* @return n/a
241	*/
242	function acf_add_loop( $loop = array() ) {
243
244	return acf()->loop->add_loop( $loop );
245	}
246
247
248	/**
249	* alias of acf()->loop->update_loop()
250	*
251	* @type function
252	* @date 6/10/13
253	* @since 5.0.0
254	*
255	* @param n/a
256	* @return n/a
257	*/
258	function acf_update_loop( $i = 'active', $key = null, $value = null ) {
259
260	return acf()->loop->update_loop( $i, $key, $value );
261	}
262
263
264	/**
265	* alias of acf()->loop->get_loop()
266	*
267	* @type function
268	* @date 6/10/13
269	* @since 5.0.0
270	*
271	* @param n/a
272	* @return n/a
273	*/
274	function acf_get_loop( $i = 'active', $key = null ) {
275
276	return acf()->loop->get_loop( $i, $key );
277	}
278
279
280	/**
281	* alias of acf()->loop->remove_loop()
282	*
283	* @type function
284	* @date 6/10/13
285	* @since 5.0.0
286	*
287	* @param n/a
288	* @return n/a
289	*/
290	function acf_remove_loop( $i = 'active' ) {
291
292	return acf()->loop->remove_loop( $i );
293	}
294