はじめに
Advanced Custom Fields（ACF）はWordPressの定番カスタムフィールドプラグインです。管理画面のGUIでフィールドを設定し、the_field() や get_field() で値を取得できます。繰り返しフィールドやフレキシブルコンテンツなど高機能なフィールドも使えます。
症状・原因
- コードを書かずにカスタムフィールドを追加したい
- 画像・日付・選択肢など多様なフィールドが必要
- 繰り返すデータ（スタッフ一覧・FAQ）を管理したい
- ACFのフィールドをGitで管理したい
解決手順
ステップ1：ACFをインストールして基本フィールドを設定する
# WP-CLI でインストール
wp plugin install advanced-custom-fields --activate
# 確認
wp plugin list | grep acf管理画面での設定:
1. カスタムフィールド → フィールドグループ → 新規追加
2. フィールドを追加:
- フィールドラベル: 価格
- フィールド名: price（英数字・アンダースコアのみ）
- フィールドタイプ: 数値
3. 表示ルール:
- 投稿タイプが「商品（product）」と等しい
4. 公開して保存ステップ2：テンプレートでフィールドを表示する
// single-product.php
// 値を直接出力（エスケープあり）
the_field('price');
// 値を変数に取得してから使用
$price = get_field('price');
if ($price) {
echo '¥' . number_format((int) $price);
}
// 画像フィールド（「画像オブジェクト」形式の場合）
$image = get_field('main_image');
if ($image) {
echo '<img src="' . esc_url($image['url']) . '" alt="' . esc_attr($image['alt']) . '" width="' . $image['width'] . '" height="' . $image['height'] . '">';
}
// セレクトフィールド（ラベルを表示）
$status = get_field('product_status'); // 選択値を返す
echo esc_html($status);
// チェックボックスフィールド（配列を返す）
$features = get_field('features'); // 選択された値の配列
if ($features) {
foreach ($features as $feature) {
echo '<li>' . esc_html($feature) . '</li>';
}
}ステップ3：繰り返しフィールド（Repeater）を使う
// 繰り返しフィールド「faq」内の「question」「answer」を表示
if (have_rows('faq')):
?>
<dl class="faq-list">
<?php while (have_rows('faq')): the_row(); ?>
<dt><?php the_sub_field('question'); ?></dt>
<dd><?php the_sub_field('answer'); ?></dd>
<?php endwhile; ?>
</dl>
<?php endif; ?>
// または get_field() で配列として取得
$faqs = get_field('faq');
if ($faqs) {
foreach ($faqs as $faq) {
echo '<dt>' . esc_html($faq['question']) . '</dt>';
echo '<dd>' . wp_kses_post($faq['answer']) . '</dd>';
}
}ステップ4：オプションページでサイト全体の設定を管理する
// functions.php — ACF オプションページを追加
add_action('acf/init', function(): void {
if (function_exists('acf_add_options_page')) {
acf_add_options_page([
'page_title' => 'サイト設定',
'menu_title' => 'サイト設定',
'menu_slug' => 'site-settings',
'capability' => 'manage_options',
'redirect' => false,
]);
}
});// テンプレートでオプションページの値を取得
$phone = get_field('contact_phone', 'option');
$address = get_field('company_address', 'option');
echo esc_html($phone);
echo esc_html($address);ステップ5：ACFフィールドをコードでエクスポート・管理する
// functions.php — フィールドグループをコードで登録（Git管理に最適）
add_action('acf/init', function(): void {
if (!function_exists('acf_add_local_field_group')) return;
acf_add_local_field_group([
'key' => 'group_product_info',
'title' => '商品情報',
'fields' => [
[
'key' => 'field_price',
'label' => '価格',
'name' => 'price',
'type' => 'number',
],
[
'key' => 'field_main_image',
'label' => 'メイン画像',
'name' => 'main_image',
'type' => 'image',
'return_format' => 'array',
],
],
'location' => [
[['param' => 'post_type', 'operator' => '==', 'value' => 'product']],
],
]);
});注意事項
- ACF Freeの繰り返しフィールド（Repeater）はACF Pro（有料）の機能です。無料版では利用できません
the_field()はACFが内部でエスケープを行いますが、HTMLを含むフィールド（wysiwyg等）はwp_kses_post()でサニタイズしてください- フィールドグループをコードで管理することで、開発環境→本番環境への設定移行が容易になります
まとめ
ACFのフィールドグループを管理画面で作成し、the_field() または get_field() でテンプレートから値を取得します。繰り返しデータには have_rows() ループを使います。フィールド定義は acf_add_local_field_group() でコード管理するとGitで追跡できます。