acf-value-functions.php — Secure Custom Fields trunk

secure-custom-fields / includes / acf-value-functions.php

secure-custom-fields / includes Last commit date

acf-value-functions.php

397 lines

1	<?php
2
3	// Register store.
4	acf_register_store( 'values' )->prop( 'multisite', true );
5
6	/**
7	* acf_get_reference
8	*
9	* Retrieves the field key for a given field name and post_id.
10	*
11	* @date 26/1/18
12	* @since ACF 5.6.5
13	*
14	* @param string $field_name The name of the field. eg 'sub_heading'.
15	* @param mixed $post_id The post_id of which the value is saved against.
16	* @return string The field key.
17	*/
18	function acf_get_reference( $field_name, $post_id ) {
19	// Allow filter to short-circuit load_value logic.
20	$reference = apply_filters( 'acf/pre_load_reference', null, $field_name, $post_id );
21	if ( null !== $reference ) {
22	return $reference;
23	}
24
25	// Back-compat.
26	$reference = apply_filters( 'acf/pre_load_metadata', null, $post_id, $field_name, true );
27	if ( null !== $reference ) {
28	return ( '__return_null' === $reference ) ? null : $reference;
29	}
30
31	$decoded = acf_decode_post_id( $post_id );
32
33	// Bail if no ID or type.
34	if ( empty( $decoded['id'] ) \|\| empty( $decoded['type'] ) ) {
35	return null;
36	}
37
38	$meta_instance = acf_get_meta_instance( $decoded['type'] );
39	if ( ! $meta_instance ) {
40	return null;
41	}
42
43	// Get hidden meta for this field name.
44	$reference = $meta_instance->get_reference( $decoded['id'], $field_name );
45
46	/**
47	* Filters the reference value.
48	*
49	* @date 25/1/19
50	* @since ACF 5.7.11
51	*
52	* @param string $reference The reference value.
53	* @param string $field_name The field name.
54	* @param (int\|string) $post_id The post ID where meta is stored.
55	*/
56	return apply_filters( 'acf/load_reference', $reference, $field_name, $post_id );
57	}
58
59	/**
60	* Retrieves the value for a given field and post_id.
61	*
62	* @date 28/09/13
63	* @since ACF 5.0.0
64	*
65	* @param integer\|string $post_id The post id.
66	* @param array $field The field array.
67	* @return mixed
68	*/
69	function acf_get_value( $post_id, $field ) {
70
71	// Allow filter to short-circuit load_value logic.
72	$value = apply_filters( 'acf/pre_load_value', null, $post_id, $field );
73	if ( $value !== null ) {
74	return $value;
75	}
76
77	// Get field name.
78	$field_name = $field['name'];
79
80	// Get field ID & type.
81	$decoded = acf_decode_post_id( $post_id );
82
83	$allow_load = true;
84
85	// If we don't have a proper field array, the field doesn't exist currently.
86	if ( empty( $field['type'] ) && empty( $field['key'] ) ) {
87
88	// Check if we should trigger warning about accessing fields too early via action.
89	do_action( 'acf/get_invalid_field_value', $field, __FUNCTION__ );
90
91	if ( apply_filters( 'acf/prevent_access_to_unknown_fields', false ) \|\| ( 'option' === $decoded['type'] && 'options' !== $decoded['id'] ) ) {
92	$allow_load = false;
93	}
94	}
95
96	// If we're using a non options_ option key, ensure we have a valid reference key.
97	if ( 'option' === $decoded['type'] && 'options' !== $decoded['id'] ) {
98
99	$meta = acf_get_metadata_by_field( $post_id, $field, true );
100
101	if ( ! $meta ) {
102	$allow_load = false;
103	} elseif ( $meta !== $field['key'] ) {
104	if ( ! isset( $field['__key'] ) \|\| $meta !== $field['__key'] ) {
105	$allow_load = false;
106	}
107	}
108	}
109
110	// Load Store.
111	$store = acf_get_store( 'values' );
112
113	// If we're allowing load, check the store or load value from database.
114	if ( $allow_load ) {
115	if ( $store->has( "$post_id:$field_name" ) ) {
116	return $store->get( "$post_id:$field_name" );
117	}
118
119	$value = acf_get_metadata_by_field( $post_id, $field );
120	}
121
122	// Use field's default_value if no meta was found.
123	if ( $value === null && isset( $field['default_value'] ) ) {
124	$value = $field['default_value'];
125	}
126
127	/**
128	* Filters the $value after it has been loaded.
129	*
130	* @date 28/09/13
131	* @since ACF 5.0.0
132	*
133	* @param mixed $value The value to preview.
134	* @param string $post_id The post ID for this value.
135	* @param array $field The field array.
136	*/
137	$value = apply_filters( 'acf/load_value', $value, $post_id, $field );
138
139	// Update store if we allowed the value load.
140	if ( $allow_load ) {
141	$store->set( "$post_id:$field_name", $value );
142	}
143
144	// Return value.
145	return $value;
146	}
147
148	// Register variation.
149	acf_add_filter_variations( 'acf/load_value', array( 'type', 'name', 'key' ), 2 );
150
151	/**
152	* Returns a formatted version of the provided value.
153	*
154	* @since ACF 5.0.0
155	*
156	* @param mixed $value The field value.
157	* @param integer\|string $post_id The post id.
158	* @param array $field The field array.
159	* @param boolean $escape_html Ask the field for a HTML safe version of it's output.
160	*
161	* @return mixed
162	*/
163	function acf_format_value( $value, $post_id, $field, $escape_html = false ) {
164
165	// Allow filter to short-circuit load_value logic.
166	$check = apply_filters( 'acf/pre_format_value', null, $value, $post_id, $field, $escape_html );
167	if ( $check !== null ) {
168	return $check;
169	}
170
171	// Get field name.
172	$field_name = $field['name'];
173	$cache_name = $escape_html ? "$post_id:$field_name:escaped" : "$post_id:$field_name:formatted";
174
175	// Check store.
176	$store = acf_get_store( 'values' );
177	if ( $store->has( $cache_name ) ) {
178	return $store->get( $cache_name );
179	}
180
181	/**
182	* Filters the $value for use in a template function.
183	*
184	* @since ACF 5.0.0
185	*
186	* @param mixed $value The value to preview.
187	* @param string $post_id The post ID for this value.
188	* @param array $field The field array.
189	* @param boolean $escape_html Ask the field for a HTML safe version of it's output.
190	*/
191	$value = apply_filters( 'acf/format_value', $value, $post_id, $field, $escape_html );
192
193	// Update store.
194	$store->set( $cache_name, $value );
195
196	// Return value.
197	return $value;
198	}
199
200	// Register variation.
201	acf_add_filter_variations( 'acf/format_value', array( 'type', 'name', 'key' ), 2 );
202
203	/**
204	* acf_update_value
205	*
206	* Updates the value for a given field and post_id.
207	*
208	* @date 28/09/13
209	* @since ACF 5.0.0
210	*
211	* @param mixed $value The new value.
212	* @param (int\|string) $post_id The post id.
213	* @param array $field The field array.
214	* @return boolean
215	*/
216	function acf_update_value( $value, $post_id, $field ) {
217
218	// Allow filter to short-circuit update_value logic.
219	$check = apply_filters( 'acf/pre_update_value', null, $value, $post_id, $field );
220	if ( null !== $check ) {
221	return $check;
222	}
223
224	/**
225	* Filters the $value before it is updated.
226	*
227	* @date 28/09/13
228	* @since ACF 5.0.0
229	*
230	* @param mixed $value The value to update.
231	* @param string $post_id The post ID for this value.
232	* @param array $field The field array.
233	* @param mixed $original The original value before modification.
234	*/
235	$value = apply_filters( 'acf/update_value', $value, $post_id, $field, $value );
236
237	// Allow null to delete value.
238	if ( null === $value ) {
239	return acf_delete_value( $post_id, $field );
240	}
241
242	// Update value and reference key.
243	$return = acf_update_metadata_by_field( $post_id, $field, $value );
244	acf_update_metadata_by_field( $post_id, $field, $field['key'], true );
245
246	// Delete stored data.
247	acf_flush_value_cache( $post_id, $field['name'] );
248
249	// Return update status.
250	return $return;
251	}
252
253	// Register variation.
254	acf_add_filter_variations( 'acf/update_value', array( 'type', 'name', 'key' ), 2 );
255
256	/**
257	* acf_update_values
258	*
259	* Updates an array of values.
260	*
261	* @date 26/2/19
262	* @since ACF 5.7.13
263	*
264	* @param array values The array of values.
265	* @param (int\|string) $post_id The post id.
266	* @return void
267	*/
268	function acf_update_values( $values, $post_id ) {
269
270	// Loop over values.
271	foreach ( $values as $key => $value ) {
272
273	// Get field.
274	$field = acf_get_field( $key );
275
276	// Update value.
277	if ( $field ) {
278	acf_update_value( $value, $post_id, $field );
279	}
280	}
281	}
282
283	/**
284	* acf_flush_value_cache
285	*
286	* Deletes all cached data for this value.
287	*
288	* @date 22/1/19
289	* @since ACF 5.7.10
290	*
291	* @param (int\|string) $post_id The post id.
292	* @param string $field_name The field name.
293	* @return void
294	*/
295	function acf_flush_value_cache( $post_id = 0, $field_name = '' ) {
296
297	// Delete stored data.
298	acf_get_store( 'values' )
299	->remove( "$post_id:$field_name" )
300	->remove( "$post_id:$field_name:formatted" )
301	->remove( "$post_id:$field_name:escaped" );
302	}
303
304	/**
305	* acf_delete_value
306	*
307	* Deletes the value for a given field and post_id.
308	*
309	* @date 28/09/13
310	* @since ACF 5.0.0
311	*
312	* @param (int\|string) $post_id The post id.
313	* @param array $field The field array.
314	* @return boolean
315	*/
316	function acf_delete_value( $post_id, $field ) {
317
318	/**
319	* Fires before a value is deleted.
320	*
321	* @date 28/09/13
322	* @since ACF 5.0.0
323	*
324	* @param string $post_id The post ID for this value.
325	* @param mixed $name The meta name.
326	* @param array $field The field array.
327	*/
328	do_action( 'acf/delete_value', $post_id, $field['name'], $field );
329
330	// Delete value and reference key.
331	$return = acf_delete_metadata_by_field( $post_id, $field );
332	acf_delete_metadata_by_field( $post_id, $field, true );
333
334	// Delete stored data.
335	acf_flush_value_cache( $post_id, $field['name'] );
336
337	// Return delete status.
338	return $return;
339	}
340
341	// Register variation.
342	acf_add_filter_variations( 'acf/delete_value', array( 'type', 'name', 'key' ), 2 );
343
344	/**
345	* acf_preview_value
346	*
347	* Return a human friendly 'preview' for a given field value.
348	*
349	* @date 28/09/13
350	* @since ACF 5.0.0
351	*
352	* @param mixed $value The new value.
353	* @param (int\|string) $post_id The post id.
354	* @param array $field The field array.
355	* @return boolean
356	*/
357	function acf_preview_value( $value, $post_id, $field ) {
358
359	/**
360	* Filters the $value before used in HTML.
361	*
362	* @date 24/10/16
363	* @since ACF 5.5.0
364	*
365	* @param mixed $value The value to preview.
366	* @param string $post_id The post ID for this value.
367	* @param array $field The field array.
368	*/
369	return apply_filters( 'acf/preview_value', $value, $post_id, $field );
370	}
371
372	// Register variation.
373	acf_add_filter_variations( 'acf/preview_value', array( 'type', 'name', 'key' ), 2 );
374
375	/**
376	* Potentially log an error if a field doesn't exist when we expect it to.
377	*
378	* @param array $field An array representing the field that a value was requested for.
379	* @param string $function The function that noticed the problem.
380	*
381	* @return void
382	*/
383	function acf_log_invalid_field_notice( $field, $function ) {
384	// If "init" has fired, ACF probably wasn't initialized early.
385	if ( did_action( 'init' ) ) {
386	return;
387	}
388
389	$error_text = sprintf(
390	/* translators: %1 plugin name */
391	__( '<strong>%1$s</strong> - We\'ve detected one or more calls to retrieve ACF field values before ACF has been initialized. This is not supported and can result in malformed or missing data.', 'secure-custom-fields' ),
392	acf_get_setting( 'name' ),
393	);
394	_doing_it_wrong( esc_html( $function ), acf_esc_html( $error_text ), '5.11.1' );
395	}
396	add_action( 'acf/get_invalid_field_value', 'acf_log_invalid_field_notice', 10, 2 );
397