local-meta.php — Advanced Custom Fields (ACF®) 6.8.8

advanced-custom-fields / includes / local-meta.php

advanced-custom-fields / includes Last commit date

local-meta.php

266 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_Local_Meta' ) ) :
17
18	class ACF_Local_Meta {
19
20	/** @var array Storage for meta data. */
21	var $meta = array();
22
23	/** @var mixed Storage for the current post_id. */
24	var $post_id = 0;
25
26	/**
27	* __construct
28	*
29	* Sets up the class functionality.
30	*
31	* @date 8/10/18
32	* @since 5.8.0
33	*
34	* @param void
35	* @return void
36	*/
37	function __construct() {
38
39	// add filters
40	add_filter( 'acf/pre_load_post_id', array( $this, 'pre_load_post_id' ), 1, 2 );
41	add_filter( 'acf/pre_load_meta', array( $this, 'pre_load_meta' ), 1, 2 );
42	add_filter( 'acf/pre_load_metadata', array( $this, 'pre_load_metadata' ), 1, 4 );
43	}
44
45	/**
46	* add
47	*
48	* Adds postmeta to storage.
49	* Accepts data in either raw or request format.
50	*
51	* @date 8/10/18
52	* @since 5.8.0
53	*
54	* @param array $meta An array of metdata to store.
55	* @param mixed $post_id The post_id for this data.
56	* @param boolean $is_main Makes this postmeta visible to get_field() without a $post_id value.
57	* @return array
58	*/
59	function add( $meta = array(), $post_id = 0, $is_main = false ) {
60
61	// Capture meta if supplied meta is from a REQUEST.
62	if ( $this->is_request( $meta ) ) {
63	$meta = $this->capture( $meta, $post_id );
64	}
65
66	// Add to storage.
67	$this->meta[ $post_id ] = $meta;
68
69	// Set $post_id reference when is the "main" postmeta.
70	if ( $is_main ) {
71	$this->post_id = $post_id;
72	}
73
74	// Return meta.
75	return $meta;
76	}
77
78	/**
79	* is_request
80	*
81	* Returns true if the supplied $meta is from a REQUEST (serialized <form> data).
82	*
83	* @date 11/3/19
84	* @since 5.7.14
85	*
86	* @param array $meta An array of metdata to check.
87	* @return boolean
88	*/
89	function is_request( $meta = array() ) {
90	return acf_is_field_key( key( $meta ) );
91	}
92
93	/**
94	* capture
95	*
96	* Returns a flattened array of meta for the given postdata.
97	* This is achieved by simulating a save whilst capturing all meta changes.
98	*
99	* @date 26/2/19
100	* @since 5.7.13
101	*
102	* @param array $values An array of raw values.
103	* @param mixed $post_id The post_id for this data.
104	* @return array
105	*/
106	function capture( $values = array(), $post_id = 0 ) {
107
108	// Reset meta.
109	$this->meta[ $post_id ] = array();
110
111	// Listen for any added meta.
112	add_filter( 'acf/pre_update_metadata', array( $this, 'capture_update_metadata' ), 1, 5 );
113
114	// Simulate update.
115	if ( $values ) {
116	acf_update_values( $values, $post_id );
117	}
118
119	// Remove listener filter.
120	remove_filter( 'acf/pre_update_metadata', array( $this, 'capture_update_metadata' ), 1, 5 );
121
122	// Return meta.
123	return $this->meta[ $post_id ];
124	}
125
126	/**
127	* capture_update_metadata
128	*
129	* Records all meta activity and returns a non null value to bypass DB updates.
130	*
131	* @date 26/2/19
132	* @since 5.7.13
133	*
134	* @param null $null .
135	* @param (int\|string) $post_id The post id.
136	* @param string $name The meta name.
137	* @param mixed $value The meta value.
138	* @param boolean $hidden If the meta is hidden (starts with an underscore).
139	* @return false.
140	*/
141	function capture_update_metadata( $null, $post_id, $name, $value, $hidden ) {
142	$name = ( $hidden ? '_' : '' ) . $name;
143	$this->meta[ $post_id ][ $name ] = $value;
144
145	// Return non null value to escape update process.
146	return true;
147	}
148
149	/**
150	* remove
151	*
152	* Removes postmeta from storage.
153	*
154	* @date 8/10/18
155	* @since 5.8.0
156	*
157	* @param mixed $post_id The post_id for this data.
158	* @return void
159	*/
160	function remove( $post_id = 0 ) {
161
162	// unset meta
163	unset( $this->meta[ $post_id ] );
164
165	// reset post_id
166	if ( $post_id === $this->post_id ) {
167	$this->post_id = 0;
168	}
169	}
170
171	/**
172	* pre_load_meta
173	*
174	* Injects the local meta.
175	*
176	* @date 8/10/18
177	* @since 5.8.0
178	*
179	* @param null $null An empty parameter. Return a non null value to short-circuit the function.
180	* @param mixed $post_id The post_id for this data.
181	* @return mixed
182	*/
183	function pre_load_meta( $null, $post_id ) {
184	if ( isset( $this->meta[ $post_id ] ) ) {
185	return $this->meta[ $post_id ];
186	}
187	return $null;
188	}
189
190	/**
191	* pre_load_metadata
192	*
193	* Injects the local meta.
194	*
195	* @date 8/10/18
196	* @since 5.8.0
197	*
198	* @param null $null An empty parameter. Return a non null value to short-circuit the function.
199	* @param (int\|string) $post_id The post id.
200	* @param string $name The meta name.
201	* @param boolean $hidden If the meta is hidden (starts with an underscore).
202	* @return mixed
203	*/
204	function pre_load_metadata( $null, $post_id, $name, $hidden ) {
205	$name = ( $hidden ? '_' : '' ) . $name;
206	if ( isset( $this->meta[ $post_id ] ) ) {
207	if ( isset( $this->meta[ $post_id ][ $name ] ) ) {
208	return $this->meta[ $post_id ][ $name ];
209	}
210	return '__return_null';
211	}
212	return $null;
213	}
214
215	/**
216	* pre_load_post_id
217	*
218	* Injects the local post_id.
219	*
220	* @date 8/10/18
221	* @since 5.8.0
222	*
223	* @param null $null An empty parameter. Return a non null value to short-circuit the function.
224	* @param mixed $post_id The post_id for this data.
225	* @return mixed
226	*/
227	function pre_load_post_id( $null, $post_id ) {
228	if ( ! $post_id && $this->post_id ) {
229	return $this->post_id;
230	}
231	return $null;
232	}
233	}
234
235	endif; // class_exists check
236
237	/**
238	* acf_setup_meta
239	*
240	* Adds postmeta to storage.
241	*
242	* @date 8/10/18
243	* @since 5.8.0
244	* @see ACF_Local_Meta::add() for list of parameters.
245	*
246	* @return array
247	*/
248	function acf_setup_meta( $meta = array(), $post_id = 0, $is_main = false ) {
249	return acf_get_instance( 'ACF_Local_Meta' )->add( $meta, $post_id, $is_main );
250	}
251
252	/**
253	* acf_reset_meta
254	*
255	* Removes postmeta to storage.
256	*
257	* @date 8/10/18
258	* @since 5.8.0
259	* @see ACF_Local_Meta::remove() for list of parameters.
260	*
261	* @return void
262	*/
263	function acf_reset_meta( $post_id = 0 ) {
264	return acf_get_instance( 'ACF_Local_Meta' )->remove( $post_id );
265	}
266