There’s very little said about get_post_custom() in codex. I also couldn’t find any good explanations or usage from G search. My current understanding is that it gets all the post meta related to the post.
Could someone provide more information? I’ve prepered few questions to help you out..
Returns a multidimensional array with all custom fields of a
particular post or page.
- What qualifies as custom field? Am I right if I say that it’s just an alias to post meta?
Note: not only does the function return a multi-dimensional array (ie:
always be prepared to deal with an array of arrays, even if expecting
array of single values), but it also returns serialized values of any
arrays stored as meta values.
- How to know if it’s array or array of arrays? Is there a safe way to check it automatically via code or do I have to check everything manually from database or know by heart?
- When should I prefer
get_post_custom() to get_post_meta()? When I need to retrieve/use most (over 50%) of the data posts has? What other helpful uses does it serve?
What qualifies as custom field?
Yes, a custom field is equal to post metadata, but be aware that some metadata is only for internal use (usually prepended with an underscore, for example _edit_lock.
A more detailed look at the function
The function get_post_custom() is actually just a wrapper for get_post_meta(): (wp-includes/post.php line 1764), but with the check of the input variable, to ensure a $post_id is set.
function get_post_custom( $post_id = 0 ) {
$post_id = absint( $post_id );
if ( ! $post_id )
$post_id = get_the_ID();
return get_post_meta( $post_id );
}
which, in return, is just a wrapper for get_metadata().
function get_post_meta( $post_id, $key = '', $single = false ) {
return get_metadata('post', $post_id, $key, $single);
}
As the $key for the metadata will always be empty, it always returns an array from the $meta_cache.
How to know if it’s array or array of arrays?
The return will always be an array, if no $key is set, and this is the case for get_post_custom().
The only thing you have to check is if it is an empty one, or if there are entries:
if ( count( $return ) > 0 ) { // whatever you want to do
Afterwards you can check, if the desired value is set:
if ( isset( $return['yourpostmeta'] ) ) { // whatever you want to do
And, to answer your question more directly:
Every entry in the return array is an array itself. Even if there is just one value for the key, it will be $return['yourpostmeta'][0]. If there are more, they are just added to the array, for example $return['yourpostmeta'][1] or $return['yourpostmeta'][456165].
There are a few things to consider:
- If you need only one value, use the
$key in the function get_post_meta( $post_id, $key, true );, as you will get a single value, or a unserialized array if the data was serialized.
- No entry in the subarray will be serialized.
- You can always use a combination of
isset() and foreach() to loop through the desired keys
This would be an example function for that:
if ( isset( $return['yourpostmeta'] ) ) {
foreach( $return['yourpostmeta'] as $key => $val ) {
echo $val;
}
}
When should I prefer get_post_custom() to get_post_meta()?
You can use get_post_custom() in the loop without any arguments, as it defaults the $post_id to get_the_ID().
get_post_meta( $post_id ) is great if you need all the values of a specific post anywhere in your site.
get_post_meta( $post_id, $key, $single ) is great for retrieving just one specific custom value.
Additional resources
Just for interest sake, you should read @PieterGoosen answer about custom fields to the following question
- Custom post meta field effect on the performance on the post
