get_post_custom()

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