WordPressのカスタムフィールドとその値を取得するpost_custom関数について

カスタムフィールドは投稿に独自の項目を追加できる機能です。
プラグインがいっぱい（Advanced Custom Fields や Custom Field Template など）出てるので、そのまま使うことはあんまりないと思いますが、プレーンな状態で使ってみると下記のようになります。

カスタムフィールドの入力

投稿画面の表示オプション「カスタムフィールド」にチェックを入れます。

カスタムフィールドの表示

本文欄の下にカスタムフィールドを入力するためのテキストボックスが追加されます。

カスタムフィールドの入力

名前（キー）とそこに入る内容を入れていきます。

カスタムフィールドの値設定後

一度保存すると、カスタムフィールドの名前（キー）は一覧から選べるようになります（新規追加を押すと新しいキーを入力できます）。
カスタムフィールドを最初に入れた投稿以外の、他の投稿（既存・新規）でもこの機能は有効です。

カスタムフィールドのキー選択

カスタムフィールドの入っているテーブル

このカスタムフィールドの名前（キー）と値がデータベースのどのテーブルに入るかというと、post_metaテーブルにはいります。
このpost_metaテーブルはカスタムフィールドだけでなく、投稿に紐づいたいろいろなデータ（アップロードした画像のサイズ・アイキャッチ画像のID・投稿記事の編集ロックなどなど）がいっぱい溜まっていきます。

カスタムフィールド部分だけ抜き出すと、下記のような形で格納されています。post_idで投稿と紐づいているのがわかるかと。

meta_id	post_id	meta_key	meta_value
12	4	fld_01	あああ
13	4	fld_02	いいい
14	4	fld_01	ううう

カスタムフィールドの値を出力をするpost_custom関数

前置きはこんな感じで、本題にはいります。

カスタムフィールドの値を出力（取得）するテンプレートタグ（関数）はいくつかあるのですが、なぜかCodexに載ってないけどよく使われるpost_custom関数について。

post_custom関数

引数に指定したカスタムフィールド（もしくは他のメタデータ）の名前（キー）を元に対応したカスタムフィールド（もしくは他のメタデータ）の値を取得する。

echo関数は含んでいないので、値を返すのみで出力はしない。

値は入力された文字列そのままなので、状況に応じてesc_attrやesc_htmlなどエスケープ系の関数を使用して出力する。

引数：: カスタムフィールド（もしくは他の投稿に関連したメタデータ）の名前（キー）

返値：

3種類（false ｜文字列 | 配列）の内どれかの型の値を返します。

false：カスタムフィールドの名前（キー）が登録されていない
文字列：カスタムフィールドの名前（キー）がひとつだけ
配列：カスタムフィールドの同じ名前（キー）が複数ある

下記のようにカスタムフィールドの名前（キー）と値が入ってたとします。

名前（キー）	値
fld_01	あああ
fld_02	いいい
fld_01	ううう

キー「fld_01」を指定した場合：配列を返す

<?php var_dump( post_custom( 'fld_01' ) ) ?>

1	<?php var_dump( post_custom( 'fld_01' ) ) ?>

array(2) {
  [0]=>
  string(9) "あああ"
  [1]=>
  string(9) "ううう"
}

array(2) {

[0]=>

string(9) "あああ"

[1]=>

string(9) "ううう"

}

キー「fld_02」を指定した場合：文字列を返す

<?php var_dump( post_custom( 'fld_02' ) ) ?>

1	<?php var_dump( post_custom( 'fld_02' ) ) ?>

string(9) "いいい"

1	string(9) "いいい"

キー「fld_03」を指定した場合：falseを返す

<?php var_dump( post_custom('fld_03') ) ?>

1	<?php var_dump( post_custom('fld_03') ) ?>

bool(false)

1	bool(false)

どの値が入ってきても表示できるようなコード例は下記。（キー：fld_01を指定した場合）
（あんまりこういうことはないと思いますが）

<?php
$fld_01 = post_custom( 'fld_01' ) ;
if( $fld_01 ){
	if( is_array( $fld_01 ) ){
		foreach( $fld_01 as $fld ){
			echo '<p>フィールド01（配列）：'.$fld.'</p>';
		}
	}
	else{
		echo '<p>フィールド01（文字列）：'.$fld_01.'</p>';
	}
}
else{
	echo '<p>フィールド01（false）：値はないよ！</p>';
}
?>

<?php

$fld_01 = post_custom( 'fld_01' ) ;

if( $fld_01 ){

if( is_array( $fld_01 ) ){

foreach( $fld_01 as $fld ){

echo 'フィールド01（配列）：'.$fld.'';

}

else{

echo 'フィールド01（文字列）：'.$fld_01.'';

}

else{

echo 'フィールド01（false）：値はないよ！';

}

post_custom関数は下記のように関数を呼び出していますので、順に追っていくとどんな風に値を取得してるかわかるかと思います。
post_custom → get_post_custom → get_post_meta

詳しくは、下記の関数リファレンスを読みましょう。
WordPress › post_custom() | Function | WordPress Developer Resource

カスタムフィールドは、入力に関してはプラグインを利用して、そのまま使うことはそうそうないかと思います。
プラグインで入力した値を表示させるときは、WordPressにデフォルトで備わった関数を使うのです（プラグインによっては独自の関数を使う場合も）が、その中で post_custom を使ったときに、返ってくる値が文字列だったり配列だったりしたので、なんでかなと調べたのでした。
同じキーが複数登録できるというのも調べてはじめて知ったのでした。（プラグインによってはこれはできなくなる機能が備わってるものがあるかもしれません。調べてませんが。）