advanced-custom-fields / includes / loop.php

loop.php in Advanced Custom Fields (ACF®) 6.5.1, at includes/loop.php

285 lines 4.8 KB

Raw Download Zip

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