MetaLocation.php at 6.8.1 · Advanced Custom Fields (ACF®)

advanced-custom-fields / src / Meta / MetaLocation.php

MetaLocation.php

190 lines 5.2 KB

Raw Download Zip

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	namespace ACF\Meta;
13
14	/**
15	* The MetaType base class.
16	*/
17	class MetaLocation {
18
19	/**
20	* The unique slug/name of the meta location.
21	*
22	* @var string
23	*/
24	public string $location_type = '';
25
26	/**
27	* The prefix to use for ACF reference keys/hidden meta.
28	*
29	* @var string
30	*/
31	public string $reference_prefix = '_';
32
33	/**
34	* Constructs the location.
35	*
36	* @since 6.4
37	*/
38	public function __construct() {
39	$this->register();
40	}
41
42	/**
43	* Registers the meta location with ACF, so it can be used by
44	* various CRUD helper functions.
45	*
46	* @since 6.4
47	*
48	* @return void
49	*/
50	public function register() {
51	if ( empty( $this->location_type ) ) {
52	return;
53	}
54
55	$store = acf_get_store( 'acf-meta-locations' );
56
57	if ( ! $store ) {
58	$store = acf_register_store( 'acf-meta-locations' );
59	}
60
61	$store->set( $this->location_type, get_class( $this ) );
62	}
63
64	/**
65	* Retrieves all ACF meta for the provided object ID.
66	*
67	* @since 6.4
68	*
69	* @param integer\|string $object_id The ID of the object to get meta from.
70	* @return array
71	*/
72	public function get_meta( $object_id = 0 ): array {
73	$meta = array();
74	$all_meta = get_metadata( $this->location_type, $object_id );
75
76	if ( $all_meta ) {
77	foreach ( $all_meta as $key => $value ) {
78	// If a reference exists for this value, add it to the meta array.
79	if ( isset( $all_meta[ $this->reference_prefix . $key ] ) ) {
80	$meta[ $key ] = $value[0];
81	$meta[ $this->reference_prefix . $key ] = $all_meta[ $this->reference_prefix . $key ][0];
82	}
83	}
84	}
85
86	// Unserialize results and return.
87	return array_map( 'acf_maybe_unserialize', $meta );
88	}
89
90	/**
91	* Retrieves a field value from the database.
92	*
93	* @since 6.4
94	*
95	* @param integer\|string $object_id The ID of the object the metadata is for.
96	* @param array $field The field array.
97	* @return mixed
98	*/
99	public function get_value( $object_id = 0, array $field = array() ) {
100	$meta = get_metadata( $this->location_type, $object_id, $field['name'] );
101	return $meta[0] ?? null;
102	}
103
104	/**
105	* Gets a reference key for the provided field name.
106	*
107	* @since 6.4
108	*
109	* @param integer\|string $object_id The ID of the object to get the reference key from.
110	* @param string $field_name The name of the field to get the reference for.
111	* @return string\|null
112	*/
113	public function get_reference( $object_id = 0, $field_name = '' ) {
114	$reference = get_metadata( $this->location_type, $object_id, $this->reference_prefix . $field_name );
115	return $reference[0] ?? null;
116	}
117
118	/**
119	* Updates an object ID with the provided meta array.
120	*
121	* @since 6.4
122	*
123	* @param integer\|string $object_id The ID of the object the metadata is for.
124	* @param array $meta The metadata to save to the object.
125	* @return void
126	*/
127	public function update_meta( $object_id = 0, array $meta = array() ) {
128	// Slash data. WP expects all data to be slashed and will unslash it (fixes '\' character issues).
129	$meta = wp_slash( $meta );
130
131	foreach ( $meta as $name => $value ) {
132	update_metadata( $this->location_type, $object_id, $name, $value );
133	}
134	}
135
136	/**
137	* Updates a field value in the database.
138	*
139	* @since 6.4
140	*
141	* @param integer\|string $object_id The ID of the object the metadata is for.
142	* @param array $field The field array.
143	* @param mixed $value The metadata value.
144	* @return integer\|boolean
145	*/
146	public function update_value( $object_id = 0, array $field = array(), $value = '' ) {
147	return update_metadata( $this->location_type, $object_id, $field['name'], $value );
148	}
149
150	/**
151	* Updates a reference key in the database.
152	*
153	* @since 6.4
154	*
155	* @param integer\|string $object_id The ID of the object the metadata is for.
156	* @param string $field_name The name of the field to update the reference for.
157	* @param string $value The value of the reference key.
158	* @return integer\|boolean
159	*/
160	public function update_reference( $object_id = 0, string $field_name = '', string $value = '' ) {
161	return update_metadata( $this->location_type, $object_id, $this->reference_prefix . $field_name, $value );
162	}
163
164	/**
165	* Deletes a field value from the database.
166	*
167	* @since 6.4
168	*
169	* @param integer\|string $object_id The ID of the object the metadata is for.
170	* @param array $field The field array.
171	* @return boolean
172	*/
173	public function delete_value( $object_id = 0, array $field = array() ): bool {
174	return delete_metadata( $this->location_type, $object_id, $field['name'] );
175	}
176
177	/**
178	* Deletes a reference key from the database.
179	*
180	* @since 6.4
181	*
182	* @param integer\|string $object_id The ID of the object the metadata is for.
183	* @param string $field_name The name of the field to delete the reference from.
184	* @return boolean
185	*/
186	public function delete_reference( $object_id = 0, string $field_name = '' ): bool {
187	return delete_metadata( $this->location_type, $object_id, $this->reference_prefix . $field_name );
188	}
189	}
190