テーマ・メニュー・ショートコード・ブロックの記事一覧|WordPressの専門家が作る教科書 https://wordpress.ks-product.com WordPressを活用したウェブサイトの制作方法を教えます Sun, 01 Nov 2026 23:00:00 +0000 ja hourly 1 https://wordpress.org/?v=7.1.5 ショートコードの出力位置がずれる原因|echo ではなく return https://wordpress.ks-product.com/3080/ Sun, 01 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3080 結論

ショートコードの出力位置がずれる原因は、コールバック内で echo や get_template_part() などを直接出力していることです。ショートコードは「戻り値で本文の該当箇所を置き換える」仕組みなので、return で文字列を返します。

テンプレートファイルを読み込みたい場合は、出力バッファで包みます。

add_shortcode( 'tpl', function () {
    ob_start();
    get_template_part( 'parts/card' );
    return ob_get_clean();
} );

原因・仕組み

the_content の途中で do_shortcode が実行され、本文の文字列の中の [タグ] が、コールバックの戻り値で置き換えられます。この処理が終わる前に、コールバック内で echo された内容は、その時点ですぐ画面に出力されます。一方、本文は処理が終わってから出力されるので、echo した部分が本文より前(多くは記事の先頭やテーマの上部)に表示されます。

公式のリファレンスにも、ショートコードの関数は置き換える文字列を返すもので、直接出力すると意図しない結果になる、と書かれています。

手順(サンプルコード)

1. 悪い例(そのまま使わない)

add_shortcode( 'bad_echo', function () {
    echo '<span>ECHOED</span>'; // 本文より先に出力される
    return '';
} );

2. 良い例:文字列を返す

add_shortcode( 'good_return', function () {
    return '<span>RETURNED</span>';
} );

3. 関数が echo する場合は出力バッファで受ける

add_shortcode( 'tpl', function () {
    ob_start();
    echo '<p>from template</p>';      // 既存の echo 型の関数をここで呼ぶ
    return ob_get_clean();
} );

get_template_part() や、echo するテンプレート関数を使うときの定番です。エラー時にバッファが残らないよう、ob_start() と ob_get_clean() は同じ関数内で対にします。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • apply_filters( 'the_content', 'before [bad_echo] after' ) の戻り値は <p>before after</p>(ショートコードの位置には何も入らない)で、<span>ECHOED</span> は戻り値より先に標準出力へ出た。
  • do_shortcode( 'before [bad_echo] after' ) の戻り値は before after、ob_start で捕まえた echo 分は <span>ECHOED</span>。
  • ob_start() で包んだ [tpl] は x<p>from template</p>y と、正しい位置に入った。

ログは testsshortcode-output-position-wrong-echo-vs-return.md に保存しています。

ショートコードの出力位置がずれる原因の注意点

  • 出力バッファ内で例外が出ると、バッファが閉じられず出力が崩れることがあります。例外が起きうる処理には try/finally を検討します。
  • 返す HTML は、ショートコード自身でエスケープします。属性の扱いはショートコードの作り方と属性を参照してください。
  • 戻り値が長大になる場合は、sprintf や配列の implode で組み立てると読みやすくなります。
  • キャッシュしたい場合は、set_transient() に戻り値の文字列を保存できます(echo 型だとできません)。

ショートコードの出力位置がずれる原因でよくあるミス

  • ショートコードの中で the_title() などの echo 型テンプレートタグを直接呼ぶ。get_the_title() のような get_ 系を使います。
  • return と echo の両方を書く。
  • ob_start() したのに ob_get_clean() を返さず、ob_end_flush() で出力してしまう。
  • 戻り値に NULL(return 忘れ)を返す。

ショートコードの出力位置がずれる原因のチェックリスト

  • コールバック内に echo / print が残っていないか
  • テンプレート読み込みは ob_start() で包んだか
  • the_* ではなく get_the_* を使っているか
  • 戻り値は常に文字列か
  • 本文の途中に正しく入ることを確認したか

ショートコードの出力位置がずれる原因のFAQ(よくある質問)

Q. 既存プラグインのショートコードが先頭に出るのは、同じ原因ですか?
A. その可能性が高いです。作者に報告するか、ob_start で包んだラッパーのショートコードを作る方法があります。

Q. ウィジェットやテンプレートでも同じですか?
A. テンプレートで echo do_shortcode() する場合は、戻り値が文字列なので、同じ書き方で問題ありません。

Q. get_template_part() の戻り値は使えますか?
A. 戻り値は void または false で、HTML は返しません。出力バッファを使います。

筆者の見解(ショートコードの出力位置がずれる原因)

「echo 型のコードを無理に return 型に直す」のではなく、最初から get_ 系の関数と文字列の組み立てで書く方が、テストしやすいと考えます。出力バッファは便利ですが、使いすぎると流れが追いにくくなるため、既存のテンプレートを再利用したい場面に限るのが良いと思います。

ショートコードの出力位置がずれる原因の関連項目

出典(一次情報)

]]>
WordPress ショートコードの使い方|投稿・テンプレート・ウィジェットでの呼び出し方と登録済み一覧の確認 https://wordpress.ks-product.com/3178/ Tue, 27 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3178 結論

WordPress のショートコードは、[タグ名 属性="値"] の形で書くと、登録されている関数の出力に置き換わる仕組みです。使う場所ごとの書き方は次のとおりです。

使う場所 書き方
投稿・固定ページ(ブロックエディター) ショートコードブロック(/shortcode と入力)に [タグ] を書く
テーマのテンプレート(PHP) <?php echo do_shortcode( '[タグ]' ); ?>
ウィジェット テキストウィジェット、またはショートコードブロック

いま使えるショートコードの一覧は、グローバル変数 $shortcode_tags のキーで確認できます。WordPress 本体だけなら audio、caption、embed、gallery、playlist、video、wp_caption でした(検証環境)。

自分で作る方法は ショートコードの作り方|属性・囲み・安全な出力の書き方 を参照してください。本記事は「使う側」に絞ります。

原因・仕組み

ショートコードは、書いた場所で自動的に展開されるわけではありません。do_shortcode() を通った文字列だけが置き換わります。

  • 投稿本文: コアが the_content フィルターで do_shortcode を実行します。ショートコードブロックの中身も、本文全体がこのフィルターを通るときに展開されます。
  • テキストウィジェット: WordPress 4.9 から、widget_text_content フィルターで do_shortcode() を実行するようになりました(Make WordPress Core の告知)。
  • テンプレート: 自分で do_shortcode() を呼ぶ必要があります(WordPress 2.5.0 からある関数)。

逆に、タイトル(the_title)や抜粋、カスタムフィールドの値などは、標準では展開されません。

手順(サンプルコード)

1. テンプレートから呼ぶ

<?php echo do_shortcode( '' ); ?>

do_shortcode() は文字列を返すだけなので、echo を忘れると何も表示されません。

2. 登録済みショートコードの一覧を確認する

add_action( 'wp_footer', function () {
    if ( ! current_user_can( 'manage_options' ) ) {
        return; // 管理者だけに表示
    }
    global $shortcode_tags;
    $tags = array_keys( $shortcode_tags );
    sort( $tags );
    echo '<pre>' . esc_html( implode( "n", $tags ) ) . '</pre>';
} );

プラグインが追加したショートコードも含めて、その時点で登録されているタグが分かります。確認が終わったら削除します。

3. 存在を確かめてから使う

if ( shortcode_exists( 'contact-form' ) ) {
    echo do_shortcode( '[contact-form id="1"]' );
}

プラグインを停止すると、本文に [タグ] がそのまま文字で残ります。テンプレート側は shortcode_exists() で囲むと安全です。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12、テーマ Twenty Twenty-Five、プラグインなしの CLI 検証環境で、テスト用ショートコード [wl1_hello name="..."] を登録して確認しました。

  • $shortcode_tags のキーは audio, caption, embed, gallery, playlist, video, wp_caption の7つだった。
  • do_shortcode( '[wl1_hello name="佐藤"]' ) → <span class="hello">こんにちは、佐藤さん</span>。
  • the_content フィルター → <p>本文 <span class="hello">こんにちは、ゲストさん</span></p>。
  • widget_text_content フィルター → 展開された。
  • ショートコードブロックのマークアップを do_blocks() だけに通すと <p>[wl1_hello name="B"]</p> のまま。the_content フィルター全体に通すと展開された(ブロックの描画の後で do_shortcode が走るため)。
  • 未登録の [wl1_nothing] はそのまま文字で返った。
  • the_title フィルターでは展開されず タイトル [wl1_hello] のまま。
  • strip_shortcodes() はタグを取り除いた。[[wl1_hello]] と二重括弧で書くと、展開されずに [wl1_hello] という文字として出力された。

ログは testsshortcode-usage-template-widget-list.md にあります。

WordPress ショートコードの使い方の注意点

  • do_shortcode() のリファレンスにあるとおり、ショートコードが1つも登録されていなければ、文字列はそのまま返ります。プラグインを停止した後の本文には [タグ] が残る点に注意します。
  • ショートコードの出力内容は、登録したテーマ・プラグインに依存します。テーマを変えると使えなくなるショートコード(テーマ独自のもの)は、本文に多用しない方が移行が楽です。
  • ショートコードの説明を記事に書きたいときは、[[タグ]] と二重括弧で書くと展開されずに表示できます。
  • 投稿者が自由に属性を書けるため、自作ショートコード側でのエスケープが必須です(ショートコードの作り方|属性・囲み・安全な出力の書き方)。

WordPress ショートコードの使い方でよくあるミス

  • テンプレートで do_shortcode() の結果を echo していない。
  • 段落ブロックや見出しブロックに書いたつもりが、HTML の属性値の中など展開されない位置に入っている。
  • カスタムフィールドの値に書いたショートコードが展開されない(取得した値を自分で do_shortcode() に通す必要がある)。
  • ショートコードの出力位置が本文の先頭にずれる(作り手側が echo している。ショートコードの出力位置がずれる原因|echo ではなく return)。

WordPress ショートコードの使い方のチェックリスト

  • 使いたいタグが $shortcode_tags に登録されているか
  • 本文ではショートコードブロックに書いたか
  • テンプレートでは echo do_shortcode() にしたか
  • プラグイン停止に備えて shortcode_exists() で囲んだか
  • 説明用の表記は [[ ]] にしたか

WordPress ショートコードの使い方のFAQ(よくある質問)

Q. ショートコードブロックと段落ブロックのどちらに書くべきですか?
A. 段落ブロックでも本文のフィルターで展開されますが、自動で <p> に囲まれます。意図どおりのマークアップにしたいときはショートコードブロックを使います。

Q. タイトルでショートコードを使えますか?
A. 標準では展開されません。テーマ側で add_filter( 'the_title', 'do_shortcode' ) を追加する方法がありますが、管理画面や RSS など影響範囲が広いため、おすすめしません。

Q. ブロックテーマのテンプレートで使うには?
A. サイトエディターでショートコードブロックを配置します。

筆者の見解(WordPress ショートコードの使い方)

ショートコードのトラブルの多くは「どこで do_shortcode() が実行されるか」を知れば説明がつくと考えます。本文・テキストウィジェットは自動、テンプレートとカスタムフィールドは手動、タイトルは対象外、と覚えておけば十分です。また、プラグインを止めたときに本文へ [タグ] が残る問題は避けられないので、私は本文に入れるショートコードは数を絞り、一覧($shortcode_tags)を時々確認して、使われていないものを整理するのがよいと思います。

WordPress ショートコードの使い方の関連項目

出典(一次情報)

]]>
WordPress テーマ自作の手順|最小構成(style.css・index.php)から作る方法 https://wordpress.ks-product.com/3161/ Wed, 07 Oct 2026 15:07:03 +0000 https://wordpress.ks-product.com/3161/ 結論

WordPress テーマ自作(クラシックテーマ)は、次の2ファイルがあれば WordPress にテーマとして認識され、有効化できます。

  1. style.css(テーマのルートに置き、先頭のコメントに Theme Name などのヘッダーを書く)
  2. index.php(すべての表示の最後の受け皿になるテンプレート)

Theme Handbook は、style.css を「すべてのテーマに必要」、index.php(ブロックテーマでは templates/index.html)を「すべてのテーマで必須」と説明しています。そこから header.php・footer.php・functions.php を足し、必要に応じて single.php や page.php を追加していくのが、自作テーマの基本の順番です。

原因・仕組み

style.css のヘッダー

WordPress はテーマフォルダ直下の style.css の先頭コメントを読み、テーマ名やバージョンを取得します。サブフォルダに置くと認識されません。Handbook では Theme Name、Author、Description、Version、Requires at least、Tested up to、Requires PHP、License、License URI、Text Domain に必須の印が付いていますが、これは主に公式ディレクトリで配布する場合の要件です。自社サイト用でも、Theme Name・Version・Text Domain は最初から書いておくと後で困りません。

テンプレート階層

WordPress は表示するページの種類に応じて、テーマ内のファイルを決まった順に探します。たとえば個別投稿は single-{post-type}-{slug}.php → single-{post-type}.php → single.php → singular.php、カテゴリーは category-{slug}.php → category-{id}.php → category.php → archive.php の順です。どれも無ければ最後に index.php が使われます(Handbook の Template Hierarchy)。つまり、最初は index.php 1枚で全ページを表示させ、見た目を分けたいページだけテンプレートを足せばよい、という作り方ができます。

手順(サンプルコード)

テーマフォルダ wp-content/themes/wl1-mini/ を作り、次のファイルを置きます。

1. style.css

/*
Theme Name: WL1 Mini
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 7.4
Text Domain: wl1-mini
*/
body { margin: 0; }

2. header.php(wp_head() と wp_body_open() を必ず呼ぶ)

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<header class="site-header">
    <a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a>
</header>
<main class="site-main">

3. footer.php(wp_footer() を必ず呼ぶ)

</main>
<footer class="site-footer">
    <p>&copy; <?php echo esc_html( wp_date( 'Y' ) ); ?> <?php bloginfo( 'name' ); ?></p>
</footer>
<?php wp_footer(); ?>
</body>
</html>

4. index.php(メインループ)

<?php get_header(); ?>
<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <?php the_excerpt(); ?>
        </article>
    <?php endwhile; ?>
    <?php the_posts_pagination(); ?>
<?php else : ?>
    <p><?php esc_html_e( '記事が見つかりませんでした。', 'wl1-mini' ); ?></p>
<?php endif; ?>
<?php get_footer(); ?>

5. functions.php(機能の宣言と CSS の読み込み)

<?php
add_action( 'after_setup_theme', function () {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
} );

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'wl1-mini-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );
} );

<title> タグは header.php に直接書かず、title-tag のサポートを宣言して WordPress に出力させます。CSS は <link> を直書きせず wp_enqueue_style() で読み込みます(wp_enqueue_style() の使い方|説明・引数・注意点)。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 検証環境で、上のファイルを wp-content/themes/wl1-mini/ に置いて確認しました。

  • 4ファイルとも php -l で構文エラーなし。
  • style.css だけの状態では wp_get_theme()->errors() が「テンプレートが不足しています。独立したテーマには templates/index.html または index.php テンプレートファイルが必要です」を返した。index.php を追加するとエラーは消えた。
  • Theme Name を書かない style.css では、エラーにはならず get( 'Name' ) が空、display( 'Name' ) はフォルダ名(wl1-noname)になった。管理画面でテーマを見分けにくくなるので、必ず書くべきです。
  • switch_theme( 'wl1-mini' ) で有効化し、次のリクエストで index.php を出力したところ、<title> が出力され、wl1-mini-style-css の <link> に style.css?ver=1.0.0 が付き、投稿2件の <h2> が表示された。
  • single.php が無い状態で get_single_template() は空文字を返した(この場合、個別投稿も index.php で表示されます)。
  • 確認後は Twenty Twenty-Five に戻し、テーマフォルダを削除した。

ログは testswordpress-theme-from-scratch-minimum-files.md にあります。

WordPress テーマ自作の手順の注意点

WordPress テーマ自作の手順でよくあるミス

  • style.css をサブフォルダ(css/style.css など)にだけ置き、テーマ一覧に出てこない。
  • index.php を作らず front-page.php や single.php だけ用意して、「テンプレートが不足」と表示される。
  • <title> を手書きし、title-tag と二重に出力する。
  • テキストドメインを style.css と翻訳関数で別の文字列にしてしまう。

WordPress テーマ自作の手順のチェックリスト

  • テーマ直下に style.css があり、Theme Name・Version・Text Domain を書いた
  • index.php がある
  • header.php に wp_head() と wp_body_open()、footer.php に wp_footer() がある
  • CSS・JS は wp_enqueue_scripts フックで読み込んでいる
  • 出力はエスケープしている

WordPress テーマ自作の手順のFAQ(よくある質問)

Q. 最初にどのテンプレートを足せばよいですか?
A. 一覧と個別で見た目が違うことが多いので、single.php(個別投稿)と page.php(固定ページ)から足すと効果が大きいです。共通部分は get_template_part() の使い方|説明・引数・注意点 で部品化します。

Q. スクリーンショットは必要ですか?
A. 必須ではありませんが、テーマ直下に screenshot.png を置くと管理画面のテーマ一覧に表示されます。

Q. functions.php は必須ですか?
A. 必須ファイルではありません。ただし title-tag の宣言や CSS の読み込みのために、実際にはほぼ必ず作ります(WordPress の functions.php とは|書き方の基本と、プラグインに書くべきものの見分け方)。

筆者の見解(WordPress テーマ自作の手順)

テーマ自作でつまずく原因の多くは、最初から多くのテンプレートを並べてしまい、どのファイルが表示に使われているのか分からなくなることだと考えます。index.php 1枚で全ページが出ることを確認してから、テンプレート階層に沿って1枚ずつ足す進め方の方が、結果的に早く仕上がると私は思います。また、wp_head()・wp_footer()・title-tag の3点は見た目に関係なく最初に入れておくのが、後からプラグインを入れたときの不具合を防ぐ近道だと考えています。

関連サービス

  • LIQUID PRESS:WordPressの有料テーマ。自作せずに既製のテーマを使う場合の選択肢です。テーマの種類・価格は公式サイトで確認できます。

※本記事はアフィリエイト広告(PR)を含みます。

WordPress テーマ自作の手順の関連項目

出典(一次情報)

]]>
WordPress の functions.php とは|書き方の基本と、プラグインに書くべきものの見分け方 https://wordpress.ks-product.com/3160/ Wed, 07 Oct 2026 15:07:03 +0000 https://wordpress.ks-product.com/3160/ 結論

WordPress の functions.php は、有効化しているテーマに機能を追加するための PHP ファイルです。Theme Handbook は「functions.php はプラグインのように振る舞い、サイトに機能を追加する」と説明しています。書き方の基本は次の3つです。

  1. 処理は関数にまとめ、add_action() / add_filter() で適切なフックに登録する(ファイルに直接処理を書き並べない)
  2. 関数名にはテーマ固有の接頭辞を付ける
  3. ファイル末尾の ?> は書かない

そして、テーマを変えても残すべき機能はプラグインに書く、というのが公式の推奨です。

原因・仕組み

functions.php とプラグインの違い

Handbook によると、両者の違いは次のとおりです。

項目 functions.php プラグイン
置き場所 テーマのフォルダ wp-content/plugins
ヘッダー 不要 専用のヘッダーが必要
効く範囲 有効なテーマのときだけ テーマに関係なく有効

同じ処理はどちらでも書けますが、Handbook は「サイトの見た目に関係なく使えるべき機能は、プラグインに入れるのがベストプラクティス」としています。

読み込まれるタイミング

functions.php はすべてのプラグインの読み込みが終わった後に読み込まれます(Handbook)。子テーマを使っている場合は、子テーマの functions.php が親テーマより先に読み込まれ、親を置き換えるのではなく両方が読み込まれます。読み込まれた直後に after_setup_theme が実行され、その後に init が来ます。

このため、functions.php の中でいきなり処理を実行すると、まだ準備ができていない機能に触れることがあります。フックに登録して、WordPress が呼び出すのを待つのが基本の形です。

手順(サンプルコード)

基本の書き方

<?php
// テーマ固有の接頭辞 wl1_ を付ける
if ( ! function_exists( 'wl1_site_label' ) ) {
    function wl1_site_label() {
        return 'WL1:' . get_bloginfo( 'name' );
    }
}

// テーマの機能宣言は after_setup_theme
add_action( 'after_setup_theme', function () {
    add_theme_support( 'post-thumbnails' );
} );

// 投稿タイプ・ショートコードなどの登録は init
add_action( 'init', function () {
    // register_post_type() や add_shortcode() をここで
} );

// 値を変えるときはフィルターで、必ず return する
add_filter( 'excerpt_length', function ( $length ) {
    return 40;
} );

function_exists() で囲むのは、子テーマで同じ名前の関数を先に定義して差し替えられるようにするためです(子テーマの functions.php が先に読み込まれるので、親テーマ側を囲んでおくと子テーマの定義が優先されます)。

どこに何を書くかの目安

やりたいこと 書くフック
add_theme_support()、メニュー位置、画像サイズ after_setup_theme
投稿タイプ・タクソノミー・ショートコードの登録 init
CSS・JS の読み込み wp_enqueue_scripts
メインクエリの件数変更など pre_get_posts

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 検証環境で、上のコードを --theme-functions(テーマの functions.php 相当として読み込む機能)で実行しました。この環境は after_setup_theme の先頭で読み込む仕様のため、その時点の状態を確認しています。

  • 読み込み時点で did_action( 'plugins_loaded' ) は 1、did_action( 'init' ) は 0 だった(プラグインより後・init より前)。
  • after_setup_theme に登録した関数は実行され、current_theme_supports( 'post-thumbnails' ) は true。
  • init に登録した関数も実行され、その中の is_user_logged_in() は true を返した。
  • 後から wl1_site_label() を呼ぶと WL1:WP Test、apply_filters( 'excerpt_length', 55 ) は 40 になった。
  • 純 PHP で同じ名前の関数を2回宣言すると Fatal error: Cannot redeclare get_site_label() で止まった。functions.php とプラグインで関数名がぶつかると、同じ理由でサイトが表示されなくなります。

ログは testsfunctions-php-what-is-how-to-write.md にあります。

WordPress の functions.phpの注意点

  • functions.php はテーマを切り替えると読み込まれなくなります。カスタム投稿タイプやショートコードをここに書くと、テーマ変更後に投稿が管理画面から見えなくなったり、本文に [タグ] が文字のまま出たりします。
  • 親テーマを直接編集すると、テーマの更新で上書きされます。配布テーマを使っているなら子テーマの functions.php に書きます(子テーマの作り方と functions.php|親テーマCSSの正しい読み込み)。
  • PHP マニュアルは、PHP だけのファイルでは末尾の ?> を省略するよう勧めています。閉じタグの後の空白や改行が意図しない出力になるのを防ぐためです。
  • 管理画面のテーマファイルエディターで直接編集すると、構文エラーで画面が開けなくなることがあります。FTP などで元に戻せる状態で編集します。

WordPress の functions.phpでよくあるミス

  • ファイル直下で add_theme_support() や register_post_type() を実行し、タイミングの問題で一部が効かない。
  • add_filter() のコールバックで値を return し忘れる(add_filter で return を忘れると|空表示・NULL の原因と対処)。
  • my_function のような一般的な関数名を付け、プラグインと衝突する。
  • 外部サイトのコードを貼り付ける際に、先頭へ <?php をもう一度書いてしまう。

WordPress の functions.phpのチェックリスト

  • 処理はフックに登録しているか
  • 関数名・ハンドル名にテーマ固有の接頭辞を付けたか
  • フィルターは値を return しているか
  • テーマ変更後も必要な機能を、プラグインに分けたか
  • 末尾の ?> を省略したか

WordPress の functions.phpのFAQ(よくある質問)

Q. functions.php に書いたコードが管理画面でも動きますか?
A. 動きます。検証環境の WordPress 7.1.2 の wp-settings.php(740〜757行目)では、有効なテーマ(子テーマなら子と親)の functions.php を管理画面かどうかの条件なしに読み込み、その直後に after_setup_theme を実行しています。フロントだけで動かしたい処理は、wp_enqueue_scripts や template_redirect など、フロントで実行されるフックに登録します。

Q. ファイルが長くなったら?
A. require get_theme_file_path( 'inc/setup.php' ); のように機能ごとにファイルを分けて読み込みます。

Q. コードスニペット系プラグインとの違いは?
A. テーマに依存しない点ではプラグイン側と同じ扱いです。どこに何を書いたかを把握できる方を選びます。

筆者の見解(WordPress の functions.php)

functions.php は手軽なぶん、ネットで見つけたコードを貼り足していくうちに「テーマを変えるとサイトが壊れる」状態になりやすいと考えます。私は、見た目に関わるもの(テーマサポート、CSS の読み込み、テンプレート用の小さな関数)だけを functions.php に置き、投稿タイプ・ショートコード・外部連携は最初から小さな独自プラグインに分ける線引きが、長く運用するサイトでは最も安全だと思います。迷ったら「テーマを変えてもこの機能は必要か」を基準にするのがおすすめです。

WordPress の functions.phpの関連項目

出典(一次情報)

]]>
WordPressのループとは|have_posts と the_post の基本と注意点 https://wordpress.ks-product.com/3134/ Wed, 07 Oct 2026 08:57:36 +0000 https://wordpress.ks-product.com/3134/ 結論

ループ(The Loop)は、WordPress が表示する投稿を1件ずつ取り出して、タイトルや本文を出力するための決まった書き方です。テーマのテンプレートでは、次の形をそのまま使います。

<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <h2><?php the_title(); ?></h2>
        <?php the_content(); ?>
    <?php endwhile; ?>
<?php else : ?>
    <p>記事がありません。</p>
<?php endif; ?>

have_posts() は「まだ表示する投稿があるか」を調べ、the_post() は「次の投稿を、今の投稿としてセットする」関数です。ただし、別の条件で投稿を取り出す2つ目のループを書いたときは、終わったあとに wp_reset_postdata() の使い方|説明・引数・注意点 で元に戻します。

原因・仕組み

WordPress は、URL(どのページを開いたか)から「表示すべき投稿の一覧」をあらかじめ取得しています。これをメインクエリと呼びます。ループは、その一覧を上から順に読む仕組みです。

部品 やさしい言い換え 役割
have_posts() 「次はある?」 残りの投稿があれば true
the_post() 「次の1件を手に取る」 次の投稿を「今の投稿」にする
テンプレートタグ 「手に取った1件の情報を出す」 the_title() の使い方|説明・引数・注意点、the_content() の使い方|説明・引数・注意点、the_permalink() の使い方|説明・引数・注意点 など

Theme Handbook は、ループの中で使う代表的なテンプレートタグとして、the_title()、the_content()、the_excerpt()、the_category()、the_author()、the_tags()、the_post_thumbnail() などを挙げています。これらは「今の投稿」の情報を出すので、the_post() の後で使います。

2つ目のループには、WP_Query を使います(WP_Query クラスの使い方|説明・引数・注意点)。Theme Handbook は、2つ目のループの後に wp_reset_postdata() で、グローバルな $post(今の投稿)を戻すよう説明しています。同じ一覧をもう一度回したいときは rewind_posts() を使います。

have_postsでまだ投稿があるか調べ、the_postで次の1件をセットし、テンプレートタグで出力して繰り返す。投稿が無くなればループ終了The Loop の流れhave_posts()まだ投稿がある?はいthe_post()次の1件をセットthe_title() などその1件を出力次の投稿へいいえループ終了2つ目のループ(WP_Query)の後は wp_reset_postdata() で元に戻す
ループで回すのは、URL から WordPress が先に取得した投稿の一覧(メインクエリ)。テンプレートタグは the_post() の後で使う。

手順(サンプルコード:2つ目のループ)

<?php
$recent = new WP_Query( array( 'posts_per_page' => 3 ) );
if ( $recent->have_posts() ) :
    echo '<ul>';
    while ( $recent->have_posts() ) : $recent->the_post();
        echo '<li><a href="' . esc_url( get_permalink() ) . '">' . esc_html( get_the_title() ) . '</a></li>';
    endwhile;
    echo '</ul>';
    wp_reset_postdata();
endif;

$recent->have_posts() のように、2つ目のループでは作ったクエリの変数から呼びます。出力は esc_html() の使い方|説明・引数・注意点 などでエスケープします。

動作確認(検証環境と結果)

WordPress 7.1.3(ja)、PHP 8.2.12 の CLI 検証環境で、投稿を3件(Loop A・B・C)作って確かめました。

確認したこと 結果
ループで3件を順に出力 Loop A / Loop B / Loop C の順に出た
ループを最後まで回した直後に have_posts() を呼ぶ true が返った(最後まで進むと内部で先頭に巻き戻るため)
rewind_posts() の後に the_post() 今の投稿は Loop A に戻った
2つ目のループ(Loop C だけ)の直後に get_the_title() Loop C(元の投稿から変わったまま)
その後 wp_reset_postdata() を呼んで get_the_title() Loop A(元の投稿に戻った)

2行目の結果から、ループの後に同じ while ( have_posts() ) をもう一度書くと、もう一度最初から回ってしまうことが分かります。4〜5行目は、wp_reset_postdata() を忘れると、その後のタイトル表示などが2つ目のループの投稿のままになることを示しています。確認後、テスト用の投稿は削除しました。

WordPressのループの注意点

  • the_post() を書き忘れない: while ( have_posts() ) の中で the_post() を呼ばないと、次の投稿に進まず、同じ処理が止まらなくなります。
  • query_posts() は使わない: メインクエリを書き換えたいときは pre_get_posts を使います(posts_per_page が効かない原因と pre_get_posts の正しい書き方)。Theme Handbook も、wp_reset_query() が必要なのは非推奨の query_posts() を使った場合だけとしています。
  • ループの外のテンプレートタグ: 今の投稿が無い場所では、タイトルなどは空になります(検証では空文字が返りました)。

WordPressのループでよくあるミス

  • 2つ目のループで have_posts() と書き、作ったクエリではなくメインクエリを見てしまう。
  • wp_reset_postdata() を忘れて、サイドバーやフッターの表示がずれる。
  • endwhile と endif の対応を崩して、構文エラーになる。
  • 一覧ページで the_content() を使い、本文が全部出て長くなる。一覧では the_excerpt() を使う。

WordPressのループのチェックリスト

  • if ( have_posts() ) と while ( have_posts() ) : the_post(); の形になっている
  • 投稿が無いとき(else)の表示を用意した
  • 2つ目のループは WP_Query の変数から呼んでいる
  • 2つ目のループの後に wp_reset_postdata() がある
  • 出力をエスケープしている

WordPressのループのFAQ(よくある質問)

Q. ループは1ページに何回書いてもよいですか?
A. 書けます。メインのループは1つで、追加の一覧は WP_Query で作り、それぞれの後に wp_reset_postdata() を呼びます。

Q. 表示件数はどこで決まりますか?
A. メインクエリの件数は、設定 → 表示設定 の「1ページに表示する最大投稿数」が基本です。テーマ側で変えるなら pre_get_posts を使います。

Q. get_posts() とループの関係は?
A. get_posts() は投稿の配列を返す関数で、the_post() を使う通常のループとは書き方が違います。違いは get_posts と WP_Query の違い|使い分けと実測結果 を参照してください。

筆者の見解(WordPressのループ)

ループは、WordPress のテーマを読むときに必ず出てくる「型」なので、意味を理解する前に形ごと覚えてしまうのがよいと考えます。そのうえで、つまずきやすいのは2つ目のループの後始末で、表示が少しずれるだけなので原因に気づきにくいのが厄介です。「new WP_Query を書いたら、必ず wp_reset_postdata をセットで書く」と決めておくのが、最も効く予防策だと私は思います。

WordPressのループの関連項目

出典(一次情報)

]]>
テンプレート階層とは|WordPressが表示ファイルを選ぶ順番 https://wordpress.ks-product.com/3128/ Wed, 07 Oct 2026 08:57:34 +0000 https://wordpress.ks-product.com/3128/ 結論

テンプレート階層は、WordPress が「今のページを表示するのに、テーマのどのファイルを使うか」を決める探索の順番です。ページの種類ごとに候補のファイルが決まっていて、上から順に探し、最初に見つかったファイルを使います。どれも無ければ、最後は必ず index.php が使われます。

だから、テーマは index.php 1枚から作り始められます。見た目を分けたいページの種類があれば、その種類用のファイルを1枚ずつ足します。ただし、ブロックテーマは .php ではなく .html のテンプレートを使います。Theme Handbook は、その場合も階層(探す順番)は同じだと説明しています。

原因・仕組み(主な探索の順番)

Theme Handbook の Template Hierarchy に載っている順番です(クラシックテーマ)。

ページの種類 探す順番(左から)
個別投稿 single-{post-type}-{slug}.php → single-{post-type}.php → single.php → singular.php → index.php
固定ページ カスタムテンプレート → page-{slug}.php → page-{id}.php → page.php → singular.php → index.php
カテゴリー category-{slug}.php → category-{id}.php → category.php → archive.php → index.php
タグ tag-{slug}.php → tag-{id}.php → tag.php → archive.php → index.php
カスタム投稿タイプの一覧 archive-{post_type}.php → archive.php → index.php
フロントページ front-page.php → home.php → page.php → index.php
投稿一覧(ブログのホーム) home.php → index.php
検索結果 search.php → index.php
404(ページが無い) 404.php → index.php

{slug} はスラッグ(URL に使う英数字の名前)、{id} は ID 番号に置き換わります。たとえばスラッグが news のカテゴリーなら、category-news.php があればそれが最優先です。

「フロントページ」と「投稿一覧(ホーム)」は、設定 → 表示設定 でトップページに固定ページを選ぶかどうかで意味が変わります。判定の違いは is_front_page と is_home の違い|静的フロントページ設定での判定表 で詳しく扱っています。

テンプレート階層の例。個別投稿はsingle-{post-type}.php、single.php、singular.php、index.phpの順に探す。カテゴリーと固定ページも同様で、最後はindex.php左から探して、最初に見つかったファイルを使う個別投稿single-{post-type}.phpsingle.phpsingular.phpindex.phpカテゴリーcategory-{slug}.phpcategory-{id}.phpcategory.phparchive.phpindex.php固定ページpage-{slug}.phppage-{id}.phppage.phpsingular.phpindex.phpどれも無ければ、最後は必ず index.php。だからテーマは index.php 1枚から作れる
個別投稿の先頭には single-{post-type}-{slug}.php もある。固定ページはカスタムテンプレートが最優先。ブロックテーマは .html でも探す順番は同じ。

手順(テンプレートを足していく順番)

  1. style.css と index.php だけでテーマを作り、全ページが表示されることを確認する。
  2. 個別投稿と固定ページの見た目を分けたいなら、single.php と page.php を足す。共通にしたいなら singular.php 1枚でよい。
  3. 一覧ページ(カテゴリー・タグ・日付など)をまとめて変えたいなら archive.php を足す。カテゴリーだけ変えたいなら category.php。
  4. 404 ページと検索結果ページを用意する(404.php、search.php)。
  5. 特定のページだけ特別な見た目にしたいときに、page-{slug}.php などの細かいファイルを足す。

共通の部品(ヘッダー・フッター・記事カード)は、get_header() の使い方|説明・引数・注意点・get_footer() の使い方|説明・引数・注意点・get_template_part() の使い方|説明・引数・注意点 で分けて読み込みます。

動作確認(検証環境と結果)

WordPress 7.1.3(ja)、PHP 8.2.12 の CLI 検証環境で、テーマ guide-th を作って有効化し、個別投稿・固定ページ・カテゴリー・404 の各ページで、コアの get_single_template() などの関数が返すファイル名を、ファイルを足しながら確かめました。

テーマの構成 個別投稿 固定ページ カテゴリー 404
A: index.php のみ index.php index.php index.php index.php
B: Aに singular.php を追加 singular.php singular.php index.php index.php
C: Bに single.php・archive.php を追加 single.php singular.php archive.php index.php
D: Cに category.php・page.php・404.php を追加 single.php page.php category.php 404.php

ファイルを足すたびに、表の順番どおりに、より具体的なファイルへ切り替わることが確認できました。確認後は元のテーマに戻し、テスト用のテーマと投稿を削除しています。

テンプレート階層の注意点

  • ファイル名のつづり: singel.php のような書き間違いは、エラーにならず単に無視され、index.php などが使われます。表示が変わらないときは、まずファイル名を確認します。
  • 子テーマ: 子テーマを使うと、子テーマにあるテンプレートが親テーマより優先されます(子テーマの作り方と functions.php|親テーマCSSの正しい読み込み)。
  • ホームの名前の混乱: 固定ページ用のテンプレートを home.php と名付けると、投稿一覧で使われてしまいます。公式の表示設定の解説も、この名前を避けるよう注意しています。

テンプレート階層でよくあるミス

  • index.php を作らずに single.php だけ用意し、テーマとして認識されない。
  • page.php を作ったのに、front-page.php があるせいでトップページに反映されない。
  • カテゴリーのスラッグを日本語のままにしていて、category-{slug}.php のファイル名と一致しない。
  • 似た内容のテンプレートを何枚も作り、修正のたびに全部を直す羽目になる。部品化で減らす。

テンプレート階層のチェックリスト

  • index.php がある
  • 見た目を分けたいページの種類と、対応するファイル名を表で確認した
  • ファイル名のつづりとスラッグを確認した
  • 共通部分は部品ファイルに分けた
  • 表示設定(トップページ)とフロントページ用ファイルの関係を確認した

テンプレート階層のFAQ(よくある質問)

Q. どのテンプレートが使われているか、画面で確かめる方法はありますか?
A. 開発中なら、テンプレートの先頭に一時的にファイル名を出力する、またはデバッグ用のプラグインを使う方法があります。本番では表示しないようにします。

Q. singular.php と single.php のどちらを作ればよいですか?
A. 個別投稿と固定ページを同じ見た目にするなら singular.php 1枚、分けるなら single.php と page.php を作ります。

Q. ブロックテーマでも同じ考え方ですか?
A. 探す順番は同じです。ファイルが templates/ フォルダの .html になる点が違います。

筆者の見解(テンプレート階層)

テンプレート階層は、表で見ると複雑ですが、「具体的な名前ほど優先、最後は index.php」という1つの規則に尽きると考えます。テーマ作りで迷子になる原因は、どのファイルが使われているかを把握しないまま作り込むことなので、ファイルを1枚足すたびに表示を確かめる進め方が確実です。最初から細かいファイルを並べず、必要になってから足すのが、保守しやすいテーマへの近道だと私は思います。

テンプレート階層の関連項目

出典(一次情報)

]]>
テーマにナビゲーションメニューを追加する方法|register_nav_menus と表示手順 https://wordpress.ks-product.com/3066/ Mon, 05 Oct 2026 15:19:00 +0000 https://wordpress.ks-product.com/3066/ 結論

クラシックテーマにメニューを追加するには、次の3か所を作ります。

  1. functions.php の after_setup_theme で register_nav_menus() を呼び、メニュー位置を登録する
  2. テンプレートに wp_nav_menu( array( 'theme_location' => '位置名' ) ) を書く
  3. 管理画面の「外観 > メニュー」で、メニューを作り、位置に割り当てる

「メニューが出ない」「固定ページの一覧が出てしまう」原因の多くは、位置にメニューが未割り当てであることです。fallback_cb を false にすると、未割り当て時は何も出力しなくなります。

原因・仕組み

register_nav_menus() は「位置」の名前を登録するだけで、メニュー自体は作りません。wp_nav_menu() は、theme_location に割り当てられたメニューを探し、なければ fallback_cb(既定は wp_page_menu)を呼びます。公式リファレンスによると、メニュー指定→位置の割り当て→最初の空でないメニュー→fallback_cb の順に探し、見つからず fallback_cb もなければ false を返します。

そのため、割り当てを忘れても、エラーではなく「固定ページの一覧」がフォールバックとして表示されます。

手順(サンプルコード)

1. メニュー位置を登録する

add_action( 'after_setup_theme', function () {
    register_nav_menus( array(
        'primary' => 'メイン',
        'footer'  => 'フッター',
    ) );
} );

2. テンプレートで表示する

<?php if ( has_nav_menu( 'primary' ) ) : ?>
    <?php
    wp_nav_menu( array(
        'theme_location'  => 'primary',
        'container'       => 'nav',
        'container_class' => 'gnav',
        'menu_class'      => 'gnav__list',
        'depth'           => 1,
        'fallback_cb'     => false,
    ) );
    ?>
<?php endif; ?>

has_nav_menu() で割り当て済みか確認すれば、未設定の場合に空の <nav> を出さずに済みます。

3. 管理画面で割り当てる

「外観 > メニュー」でメニューを作成し、「メニューの設定」の表示場所にチェックします(ブロックテーマでは別の画面になります)。コードで作るなら、wp_create_nav_menu()、wp_update_nav_menu_item()、set_theme_mod( 'nav_menu_locations', ... ) を使います。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で、一時メニューを作成して確認し、終了時に削除しました。

  • 登録直後、has_nav_menu( 'primary' ) は false。
  • 未割り当てで wp_nav_menu を呼ぶと、<div class="menu"><ul><li class="page_item ...">サンプルページ</li></ul></div>(固定ページ一覧)が返った。
  • fallback_cb => false では false(出力なし)。
  • メニューを作成して primary に割り当てると、has_nav_menu( 'primary' ) は true、footer は false。
  • container => 'nav'、menu_class => 'gnav__list'、depth => 1 で、<nav class="gnav"><ul id="menu-p1-tmp-menu" class="gnav__list">... が出力された。
  • 削除後、wp_get_nav_menu_object は false。

ログは testsadd-navigation-menu-theme-register-nav-menus.md にあります。ブラウザでの管理画面操作は、この環境では行っていません。

テーマにナビゲーションメニューを追加する方法の注意点

  • register_nav_menus() は、テーマ機能の宣言として after_setup_theme にまとめて書くのが一般的です(after_setup_theme フックの使い方|説明・引数・注意点参照)。公式リファレンスのユーザー投稿ノートには init で呼ぶ例もあり、どちらでも動作します。
  • メニューの割り当て(nav_menu_locations)はテーマごとに保存されるため、テーマを切り替えると割り当てが外れることがあります。
  • container に使えるのは、既定では div と nav です。
  • ブロックテーマでは、ナビゲーションブロックを使うため、この手順は不要な場合があります。

テーマにナビゲーションメニューを追加する方法でよくあるミス

  • 位置を登録しただけで、管理画面で割り当てない。
  • theme_location の名前が、登録時と違う(primary と main など)。
  • 位置名(スラッグ)を後から変更し、割り当て済みのメニューが表示されなくなる(公式にも注意書きあり)。子テーマで扱うときは子テーマと functions.phpも参照。
  • $html = wp_nav_menu( ... ) と変数に入れて加工しようとして、echo => false を指定し忘れる。既定(echo => true)では、その場で出力され、戻り値は値を持ちません(検証では NULL)。

テーマにナビゲーションメニューを追加する方法のチェックリスト

  • register_nav_menus() を after_setup_theme で呼んだか
  • theme_location の名前が一致しているか
  • 管理画面で位置に割り当てたか
  • fallback_cb の方針を決めたか
  • depth やクラス名がデザインと合っているか

テーマにナビゲーションメニューを追加する方法のFAQ(よくある質問)

Q. メニューが空のとき、何も出したくありません。
A. fallback_cb => false にするか、has_nav_menu() で囲みます。

Q. メニューのHTMLを細かく変えたいです。
A. walker を渡す方法と、nav_menu_css_class などのフィルターを使う方法があります。

Q. 複数の位置を登録するのに、関数は1つで足りますか?
A. register_nav_menus() に連想配列で渡せば足ります。

筆者の見解(テーマにナビゲーションメニューを追加する方法)

メニューの不具合は、コードより「割り当て忘れ」であることが多いと考えます。まず has_nav_menu() で状態を確かめ、その上で fallback_cb を false にしておくと、未設定のときの挙動が分かりやすくなります。納品時には、位置の名前と割り当て手順を、簡単にでもまとめておくと親切だと思います。

テーマにナビゲーションメニューを追加する方法の関連項目

出典(一次情報)

]]>
ショートコードの作り方|属性・囲み・安全な出力の書き方 https://wordpress.ks-product.com/3052/ Mon, 05 Oct 2026 15:05:00 +0000 https://wordpress.ks-product.com/3052/ 結論

独自ショートコードは、次の3ステップで作れます。

  1. 値を return するコールバック関数を書く(echo しない)
  2. shortcode_atts() で属性の既定値を決め、受け取った値を検証する
  3. add_shortcode( 'タグ名', 'コールバック' ) で登録する

コールバックは ( $atts, $content, $tag ) の3つを受け取ります。HTML を組み立てるときは、属性値を esc_attr() / esc_html() で必ずエスケープします。登録は init フックの中で行うのが一般的です(公式リファレンスのユーザー投稿ノートでも、プラグインでは init にフックした関数の中で登録する書き方が紹介されています)。

原因・仕組み

ショートコードは、本文(the_content)に含まれる [タグ ...] を、WordPress が登録済みのコールバックの戻り値に置き換える仕組みです。コアは the_content フィルターの優先度 11 で do_shortcode を実行します。

属性名は、小文字に変換されてから渡されます(値はそのまま)。属性を何も付けなかったときの $atts は、空の配列(この検証環境では array(0))でした。古い資料には空文字と書かれていることもあるため、shortcode_atts() に通してから使うと、どちらでも安全です。

手順(サンプルコード)

1. 属性つき・囲みつきのショートコード

function p1_notice_sc( $atts, $content = null, $tag = '' ) {
    $a = shortcode_atts(
        array( 'type' => 'info', 'title' => '' ),
        $atts,
        $tag
    );
    // 許可する値だけを通す
    $type  = in_array( $a['type'], array( 'info', 'warning' ), true ) ? $a['type'] : 'info';
    $inner = do_shortcode( (string) $content ); // 囲みの中のショートコードも展開
    return sprintf(
        '<div class="notice notice--%s"><strong>%s</strong>%s</div>',
        esc_attr( $type ),
        esc_html( $a['title'] ),
        wp_kses_post( $inner )
    );
}
add_action( 'init', function () {
    add_shortcode( 'notice', 'p1_notice_sc' );
} );

投稿には [notice type="warning" title="注意"]本文[/notice] と書きます。

2. 属性の書き方による違い

shortcode_atts() の第3引数(タグ名)を渡すと、shortcode_atts_notice フィルターで、他のコードから既定値を変更できます。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • [notice type="warning" title="注意"]本文 [year][/notice] → <div class="notice notice--warning"><strong>注意</strong>本文 2026</div>(囲みの中の [year] も展開された)。
  • type="bad<script>" → 許可リスト外のため info に置き換わった。
  • TYPE="warning"(大文字)、type='warning'(シングルクォート)、type=warning(引用符なし)はいずれも warning として認識された。
  • 属性なしの [chk] では、$atts は空配列だった。
  • shortcode_exists( 'notice' ) と has_shortcode() は true。

ログは testsshortcode-create-attributes-how-to.md にあります。

ショートコードの作り方の注意点

  • ショートコードのタグ名には、< > & / [ ] =、空白、制御文字を使えません(公式リファレンスの記載)。
  • 同じタグ名で再登録すると、後の登録で上書きされます。接頭辞(p1_ など)を付けて衝突を避けます。
  • 属性の値はユーザー(投稿者)が自由に書ける入力です。必ず検証とエスケープを行います。
  • 投稿者が信頼できない場合、出力するHTMLにも wp_kses_post() を使います。

ショートコードの作り方でよくあるミス

  • コールバックで echo する(出力位置がずれます。ショートコードの出力位置ずれ参照)。
  • 属性名は小文字に変換されて渡されるのに、コールバック側で $atts['TYPE'] のように大文字のキーで受け取ろうとして、値が取れない。
  • shortcode_atts() を使わず、$atts['x'] で未定義キーの警告を出す。
  • [notice]...[/notice] の中のショートコードが展開されない(do_shortcode( $content ) を忘れる)。

ショートコードの作り方のチェックリスト

  • コールバックは return しているか
  • shortcode_atts() で既定値を設定したか
  • 属性値を検証し、出力時にエスケープしたか
  • タグ名に接頭辞を付けたか
  • 囲みの中身を do_shortcode() に通したか

ショートコードの作り方のFAQ(よくある質問)

Q. テンプレートからショートコードを呼ぶには?
A. echo do_shortcode( '[notice type="info"]本文[/notice]' ); と書きます。

Q. 属性にハイフンは使えますか?
A. 現在のコアでは使えます(検証環境で [chk data-id="5"] の $atts に 'data-id' => '5' が入ることを確認)。ただし PHP の変数名やキーとして扱いやすいよう、アンダースコアか英数字にそろえる方が無難です。

Q. ショートコードが投稿に表示されず、そのまま文字で出ます。
A. 登録前の実行、タグ名の誤字、the_content を通らない場所での出力(テーマ側で do_shortcode が必要)を確認します。

筆者の見解(ショートコードの作り方)

ショートコードは手軽な反面、投稿内に入力を直接書かせる仕組みなので、検証とエスケープを最初から組み込むべきだと考えます。また、ブロックエディタが標準の今は、複雑な見た目を伴うものはブロックやパターンにして、ショートコードは「値を差し込むだけ」に絞る方が、長期的に保守しやすいと私見では思います。

ショートコードの作り方の関連項目

出典(一次情報)

]]>
子テーマの作り方と functions.php|親テーマCSSの正しい読み込み https://wordpress.ks-product.com/3051/ Mon, 05 Oct 2026 15:04:00 +0000 https://wordpress.ks-product.com/3051/ 結論

子テーマは、wp-content/themes/ の下に新しいフォルダを作り、次の2ファイルを置けば成立します。

  1. style.css:ヘッダーに Theme Name と Template: 親テーマのフォルダ名 を書く
  2. functions.php:親テーマのCSSなどを読み込むコードを書く

Template: は、親テーマのフォルダ名と完全に一致させます(公式ハンドブックの記載)。親の機能を壊さずに上書きできる点が最大の利点で、親テーマの更新でカスタマイズが消えません。

原因・仕組み

子テーマが有効なとき、WordPress は「テンプレート(親)」と「スタイルシート(子)」の2つを区別して持ちます。

  • get_template() / get_template_directory() / get_template_directory_uri() → 親テーマ
  • get_stylesheet() / get_stylesheet_directory() / get_stylesheet_directory_uri() → 有効なテーマ(子があれば子)

functions.php は、子→親の順で両方読み込まれます。コア(wp-settings.php)では、有効なテーマの一覧をループして各 functions.php を include しており、公式ハンドブックにも、子が親の直前に読み込まれると書かれています。親の関数を上書きしたいときは、親が if ( ! function_exists() ) で定義している場合に限り、子で先に定義できます。

子テーマのフォルダにはstyle.cssとfunctions.phpを置き、style.cssのTemplateに親テーマのフォルダ名を書く。functions.phpは子、親の順に読み込まれるwp-content/themes/ の中parent-theme/(親)style.cssfunctions.phpindex.php などmy-child/(子)style.cssTemplate: parent-themefunctions.phpTemplate: に親のフォルダ名を完全一致で書くfunctions.php は 子 → 親 の順に両方読み込まれる親テーマを更新しても、子に書いたカスタマイズは消えない
get_template_directory_uri() は常に親、get_stylesheet_directory_uri() は有効なテーマ(子があれば子)を指す。

手順(サンプルコード)

1. style.css

/*
Theme Name: My Child
Template: twentytwentyfive
Version: 1.0
*/

2. functions.php で親と子のCSSを読み込む

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css', array(), '1.0' );
    wp_enqueue_style( 'child-style', get_stylesheet_uri(), array( 'parent-style' ), '1.0' );
} );

親テーマが自分でCSSを読み込んでいる場合は、二重読み込みになることがあります。公式も、親のコードを見て判断するよう案内しています。

3. ファイルの上書き

子テーマに親と同じ名前のテンプレート(header.php など)を置くと、子の方が優先されます。パーツの読み込みには、子→親の順で探す get_template_part() や get_theme_file_path() を使います。

4. 親のフックを外す

add_action( 'after_setup_theme', function () {
    remove_action( 'wp_head', 'parent_theme_some_output', 10 );
} );

優先度が合わないと外れないため、remove_action が効かないを参照してください。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で、有効テーマは twentytwentyfive のみ(実際の子テーマは作成していません)。

  • 子テーマなしの状態:get_template() と get_stylesheet() はどちらも twentytwentyfive。
  • pre_option_stylesheet を my-child、pre_option_template を twentytwentyfive にして子テーマ状態を擬似的に再現した結果、get_template()=twentytwentyfive、get_stylesheet()=my-child、get_template_directory_uri は .../themes/twentytwentyfive、get_stylesheet_directory_uri は .../themes/my-child。
  • 上記の wp_enqueue_style を実行して wp_print_styles() した出力の順は、parent-style → child-style(子が後)。
  • wp-settings.php 741〜747行目で、各テーマの functions.php を include していることを確認した。

実際のフォルダを使った子テーマの動作、is_child_theme() の結果は、この擬似環境では確認していません(未検証)。ログは testschild-theme-functions-php-how-to.md にあります。

子テーマの作り方と functions.phpの注意点

  • Template: の綴りやフォルダ名が違うと、管理画面で「親テーマが見つかりません」となります。
  • 親テーマのバージョンアップで構造が変わると、子のテンプレートが古いままになります。更新時に差分を確認します。
  • @import でのCSS読み込みは遅くなるため、wp_enqueue_style を使います。
  • ブロックテーマでは、子テーマに theme.json を置いて設定を上書きできます。

子テーマの作り方と functions.phpでよくあるミス

  • 子の functions.php の最初に <?php を書かず、内容がそのまま画面に出る。
  • 親の style.css だけを読み込み、子の style.css を読み込まない。
  • 画像の指定に get_template_directory_uri() を使い、子の画像が見つからない。
  • 子テーマで親の関数を再定義して、「関数の二重定義」で致命的エラーにする。

子テーマの作り方と functions.phpのチェックリスト

  • Template: が親テーマのフォルダ名と完全に一致しているか
  • 親と子のCSSが、重複せず読み込まれているか
  • 画像・ファイルのパス関数が、親・子の使い分けに合っているか
  • 親テーマ更新後に、差分を確認する運用があるか
  • WP_DEBUG でエラーがないか

子テーマの作り方と functions.phpのFAQ(よくある質問)

Q. 子テーマは必ず必要ですか?
A. 自作テーマには不要です。市販・配布テーマを改造するときに有効です。

Q. 子テーマの functions.php で親を require する必要は?
A. ありません。両方自動で読み込まれます。

Q. 子テーマから親のテンプレートパーツを指すには?
A. get_parent_theme_file_path() や、get_template_directory() を使います。

筆者の見解(子テーマの作り方と functions.php)

子テーマは、小さな修正を安全に切り分けるための手段であり、大幅な改造を重ねる場所ではないと考えます。変更が増えてきたら、親テーマとの差分を管理しやすい形(フックやフィルターでの拡張)に寄せていく方が、長く運用しやすいと思います。

子テーマの作り方と functions.phpの関連項目

出典(一次情報)

]]>
get_body_class() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2924/ https://wordpress.ks-product.com/2924/#respond Sat, 03 Oct 2026 12:29:01 +0000 https://wordpress.ks-product.com/?p=2924 説明

get_body_class() は、<body> に付けるクラスを、配列で返す関数です。body_class() が出力する内容の元になります。

基本構文

get_body_class( string|string[] $class = '' ): string[]

引数

  • $class:追加するクラス(文字列または配列)

戻り値

クラス名の配列。

使い方(サンプル)

$classes = get_body_class( 'my-theme' );
echo esc_attr( implode( ' ', $classes ) );

注意点

  • 出力せず、配列を返します。
  • <body> のクラスを出力するときは、body_class()。
  • クラスの追加は、body_class フィルターでもできます。

実務での使いどころ

  • <body> のクラスを、PHPの中で、加工して使うとき。
  • クラスに、特定の値が含まれるかを、確認するとき。

よくあるミスと対策

  • 配列を、そのまま echo している。implode() で、文字列にしてから、出力する。
  • class="..." 全体を出力する body_class() と、取り違える。

NG例

echo get_body_class(); // 配列なので、「Array」になる

OK例

$classes = get_body_class();
if ( in_array( 'home', $classes, true ) ) {
	// トップページ
}

使い分け早見表

関数 役割
get_body_class() クラスの配列を、返す
body_class() class="..." を、出力する
get_post_class() 投稿のクラスの配列を、返す

関連項目

body_class()、get_post_class()

公式リファレンス:get_body_class() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2924/feed/ 0