-
-
Notifications
You must be signed in to change notification settings - Fork 506
/
CoreEntity.php
310 lines (288 loc) · 11.5 KB
/
CoreEntity.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
<?php
namespace Timber;
abstract class CoreEntity extends Core implements CoreInterface, CoreEntityInterface, MetaInterface
{
/**
* Gets an object meta value.
*
* Returns a meta value or all meta values for all custom fields of an object saved in the
* meta database table.
*
* Fetching all values is only advised during development, because it can have a big performance
* impact, when all filters are applied.
*
* @api
*
* @param string $field_name Optional. The field name for which you want to get the value. If
* no field name is provided, this function will fetch values for all
* custom fields. Default empty string.
* @param array $args An array of arguments for getting the meta value. Third-party integrations
* can use this argument to make their API arguments available in Timber.
* Default empty array.
* @return mixed The custom field value or an array of custom field values. Null if no value
* could be found.
*/
public function meta($field_name = '', $args = [])
{
return $this->fetch_meta($field_name, $args);
}
/**
* Gets an object meta value directly from the database.
*
* Returns a raw meta value or all raw meta values saved in the meta database table. In
* comparison to `meta()`, this function will return raw values that are not filtered by third-
* party plugins.
*
* Fetching raw values for all custom fields will not have a big performance impact, because
* WordPress gets all meta values, when the first meta value is accessed.
*
* @api
* @since 2.0.0
*
* @param string $field_name Optional. The field name for which you want to get the value. If
* no field name is provided, this function will fetch values for all
* custom fields. Default empty string.
*
* @return null|mixed The meta field value(s). Null if no value could be found, an empty array
* if all fields were requested but no values could be found.
*/
public function raw_meta($field_name = '')
{
return $this->fetch_meta($field_name, [], false);
}
/**
* Gets an object meta value.
*
* Returns a meta value or all meta values for all custom fields of an object saved in the object
* meta database table.
*
* Fetching all values is only advised during development, because it can have a big performance
* impact, when all filters are applied.
*
* @api
*
* @param string $field_name Optional. The field name for which you want to get the value. If
* no field name is provided, this function will fetch values for all
* custom fields. Default empty string.
* @param array $args {
* An array of arguments for getting the meta value. Third-party integrations can use this
* argument to make their API arguments available in Timber. Default empty array.
* }
* @param bool $apply_filters Whether to apply filtering of meta values. You can also use
* the `raw_meta()` method as a shortcut to apply this argument.
* Default true.
*
* @return mixed The custom field value or an array of custom field values. Null if no value
* could be found.
*/
protected function fetch_meta($field_name = '', $args = [], $apply_filters = true)
{
/**
* Filters whether to transform a meta value.
*
* If the filter returns `true`, all meta value will be transformed to Timber/standard PHP objects if possible.
*
* @api
* @since 2.0.0
* @example
* ```php
* // Transforms all meta value.
* add_filter( 'timber/meta/transform_value', '__return_true' );
* ```
*
* @param bool $transform_value
*/
$transform_value = \apply_filters('timber/meta/transform_value', false);
$args = \wp_parse_args($args, [
'transform_value' => $transform_value,
]);
$object_meta = null;
$object_type = $this->get_object_type();
if ($apply_filters) {
/**
* Filters object meta data before it is fetched from the database.
*
* @since 2.0.0
*
* @example
* ```php
* // Disable fetching meta values.
* add_filter( 'timber/post/pre_meta', '__return_false' );
*
* // Add your own meta data.
* add_filter( 'timber/post/pre_meta', function( $post_meta, $post_id, $post ) {
* $post_meta = array_merge( $post_meta, [
* 'custom_data_1' => 73,
* 'custom_data_2' => 274,
* ] );
*
* return $post_meta;
* }, 10, 3 );
* ```
*
* @param string|null $object_meta The field value. Default null. Passing a non-null
* value will skip fetching the value from the database
* and will use the value from the filter instead.
* @param int $post_id The post ID.
* @param string $field_name The name of the meta field to get the value for.
* @param object $object The Timber object.
* @param array $args An array of arguments.
*/
$object_meta = \apply_filters(
"timber/{$object_type}/pre_meta",
$object_meta,
$this->ID,
$field_name,
$this,
$args
);
if ($object_type !== 'term') {
/**
* Filters the value for a post meta field before it is fetched from the database.
*
* @deprecated 2.0.0, use `timber/{object_type}/pre_meta`
*/
$object_meta = \apply_filters_deprecated(
"timber_{$object_type}_get_meta_field_pre",
[$object_meta, $this->ID, $field_name, $this],
'2.0.0',
"timber/{$object_type}/pre_meta"
);
/**
* Filters post meta data before it is fetched from the database.
*
* @deprecated 2.0.0, use `timber/{object_type}/pre_meta`
*/
\do_action_deprecated(
"timber_{$object_type}_get_meta_pre",
[$object_meta, $this->ID, $this],
'2.0.0',
"timber/{$object_type}/pre_meta"
);
}
}
if (null === $object_meta) {
// Fetch values. Auto-fetches all values if $field_name is empty.
$object_meta = \get_metadata($object_type, $this->ID, $field_name, true);
// Mimick $single argument when fetching all meta values.
if (empty($field_name) && \is_array($object_meta) && !empty($object_meta)) {
$object_meta = \array_map(function ($meta) {
/**
* We use array_key_exists() instead of isset(), because when the meta value is null, isset() would
* return false, even though null is a valid value to return.
*
* @ticket #2519
*/
if (1 === \count($meta) && \array_key_exists(0, $meta)) {
return $meta[0];
}
return $meta;
}, $object_meta);
}
// Empty result.
if (empty($object_meta)) {
$object_meta = empty($field_name) ? [] : null;
}
}
if ($apply_filters) {
/**
* Filters the value for a post meta field.
*
* This filter is used by the ACF Integration.
*
* @see \Timber\Post::meta()
* @since 2.0.0
*
* @example
* ```php
* add_filter( 'timber/post/meta', function( $post_meta, $post_id, $field_name, $post ) {
* if ( 'event' === $post->post_type ) {
* // Do something special.
* $post_meta['foo'] = $post_meta['foo'] . ' bar';
* }
*
* return $post_meta;
* }, 10, 4 );
* ```
*
* @param string $post_meta The field value.
* @param int $post_id The post ID.
* @param string $field_name The name of the meta field to get the value for.
* @param CoreEntity $post The post object.
* @param array $args An array of arguments.
*/
$object_meta = \apply_filters(
"timber/{$object_type}/meta",
$object_meta,
$this->ID,
$field_name,
$this,
$args
);
if ($object_type === 'term') {
/**
* Filters the value for a term meta field.
*
* @deprecated 2.0.0, use `timber/term/meta`
*/
$object_meta = \apply_filters_deprecated(
'timber/term/meta/field',
[$object_meta, $this->ID, $field_name, $this],
'2.0.0',
'timber/term/meta'
);
}
/**
* Filters the value for an object meta field.
*
* @deprecated 2.0.0, use `timber/{object_type}/meta`
*/
$object_meta = \apply_filters_deprecated(
"timber_{$object_type}_get_meta_field",
[$object_meta, $this->ID, $field_name, $this],
'2.0.0',
"timber/{$object_type}/meta"
);
/**
* Filters object meta data fetched from the database.
*
* @deprecated 2.0.0, use `timber/{object_type}/meta`
*/
$object_meta = \apply_filters_deprecated(
"timber_{$object_type}_get_meta",
[$object_meta, $this->ID, $this],
'2.0.0',
"timber/{$object_type}/meta"
);
// Maybe convert values to Timber objects.
if ($args['transform_value']) {
$object_meta = $this->convert($object_meta);
}
}
return $object_meta;
}
/**
* Finds any WP_Post objects and converts them to Timber\Posts
*
* @api
* @param array|\Timber\CoreEntity $data
*/
public function convert($data)
{
if (\is_object($data)) {
$data = Helper::convert_wp_object($data);
} elseif (\is_array($data)) {
$data = \array_map([$this, 'convert'], $data);
}
return $data;
}
/**
* Get the base object type
*
* @return string
*/
protected function get_object_type()
{
return $this->object_type;
}
}