WordPressショートコードの使い方と作り方｜functions.php例

WordPressのショートコードは、角括弧で書いた短い記号を、表示時に文章やHTMLへ置き換える仕組みです。プラグインが用意した機能を呼び出すだけでなく、PHPでサイト専用の部品も作れます。

ただし、保存場所や出力処理を誤ると、テーマ更新でコードが消えたり、意図しないHTMLが出力されたりします。この記事では、使う側の操作から安全な自作例、ブロックとの選び分けまで順に説明します。

WordPressのショートコードとは

ショートコードは、投稿本文などに書いたタグをWordPressが解析し、登録済みのコールバック関数の戻り値へ差し替える機能です。たとえば site_notice というタグを登録すると、編集画面には角括弧付きの短い記述だけを置き、閲覧画面には案内ボックスを表示できます。

主な用途は次のとおりです。

• フォームやギャラリーなど、プラグイン機能の呼び出し
• 定型の注意書きや料金表の共通化
• 属性で内容を変える表示部品
• 投稿情報やログイン状態に応じた出力

WordPress公式のShortcode APIでは、登録、属性の既定値、囲み型の処理などが用意されています。仕組みを理解する前にPHP全体を確認したい場合は「PHPの基礎知識」、サイト固有の変更方針は「カスタマイズまとめ」、動的な画面操作を加える場合は「JavaScriptの追加」で切り分けると整理しやすくなります。

ショートコードは保存時ではなく表示時に展開されます。したがって、登録元のテーマやプラグインを停止すると、角括弧の文字列がそのまま残ることがあります。

WordPress標準のショートコード

WordPressコアには、audio、video、gallery、caption、playlistなどのショートコードがあります。利用できるタグや属性は機能ごとに異なるため、記憶だけで属性名を決めず、WordPress公式のShortcode APIにある標準一覧を確認してください。

ブロックエディターでは、画像・音声・ギャラリーを専用ブロックで挿入できるため、標準ショートコードをあえて入力する場面は減っています。既存記事の互換性を保つ場合や、プラグインがタグ形式だけを提供している場合には、現在も有効です。

ショートコードを投稿・固定ページで使う方法

ブロックエディターでは「ショートコード」ブロックを追加し、プラグインなどが示すタグをそのまま入力します。段落ブロックへ混ぜるより、独立したショートコードブロックに置くほうが、前後の自動整形による崩れを切り分けやすくなります。

操作は次の流れです。

1. 対象の投稿または固定ページを編集する
2. ブロック追加で「ショートコード」を選ぶ
3. 角括弧を含む指定のタグを入力する
4. プレビューで表示と余白を確認する
5. 問題がなければ更新する

属性は、タグ名の後ろに半角スペースを置き、属性名と値を指定します。値は引用符で囲むと、空白を含む文字列も扱いやすくなります。ページ一覧の分割など、目的が明確な実装は「ページネーションの実装」で専用の方法を確認し、ショートコードだけで無理に代替しないことが大切です。

テーマ・プラグインのショートコードを使う

プラグインが提供するタグは、そのプラグインが有効な間だけ動作します。名称が似ていても、属性、利用場所、権限条件は製品ごとに異なります。管理画面の生成ボタンや公式マニュアルから記述をコピーし、まず下書きまたは検証環境で確認してください。

テーマ内に独自タグを置くと、テーマ変更時に機能まで失われます。サイトのデザインではなく継続して使う機能なら、小さな専用プラグインへ分離するほうが保守しやすい設計です。テーマ側で管理する場合も、親テーマを直接編集せず「子テーマで安全に編集」の手順を使います。

外部から入手したPHPを、意味を確認せず貼り付けないでください。権限確認、入力値の検証、出力時のエスケープが不足していると、管理者以外の入力を通じて危険なHTMLを表示する原因になります。

ショートコードを自作する前の準備

自作前に、置き場所と仕様を決めます。短期の試作でも本番サイトの親テーマへ直接追加するのは避け、検証環境で作業してください。

最低限決めておきたい項目は次のとおりです。

項目	決める内容	理由
タグ名	他機能と衝突しにくい接頭辞付きの名前	同名登録は後から読み込まれた処理で上書きされ得る
入力	許可する属性、型、既定値	想定外の値を処理しないため
出力	HTML構造とエスケープ方法	表示崩れや不正な出力を防ぐため
保存場所	専用プラグインまたは子テーマ	更新で消えるのを避けるため
停止時	タグが残った場合の扱い	将来の移行をしやすくするため

タグ名には小文字の英字とアンダースコアを中心に使い、サイト固有の接頭辞を付けます。WordPress公式はハイフンを避けるよう案内しています。

functions.phpでショートコードを作る

次は、案内文を返す最小構成です。ここでは子テーマのfunctions.phpへ追加する想定ですが、長く使うなら専用プラグイン化を検討してください。

function mysite_notice_shortcode() {
    return '<p class="mysite-notice">営業時間は平日9時から17時です。</p>';
}
add_shortcode( 'mysite_notice', 'mysite_notice_shortcode' );

本文に角括弧付きで mysite_notice と入力すると、p要素が表示されます。コールバックではechoせず、文字列をreturnします。echoすると意図した位置より前へ出るなど、予測しにくい結果になります。

属性付きショートコードを作る

属性を受け取る場合は、shortcode_attsで許可するキーと既定値をそろえ、その後で値を検証します。次の例はlevelをinfoまたはwarningに限定し、textをプレーンテキストとして出力します。

function mysite_box_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'level' => 'info',
            'text'  => '',
        ),
        $atts,
        'mysite_box'
    );

    $level = in_array( $atts['level'], array( 'info', 'warning' ), true )
        ? $atts['level']
        : 'info';

    if ( '' === trim( $atts['text'] ) ) {
        return '';
    }

    return sprintf(
        '<div class="mysite-box mysite-box--%1$s">%2$s</div>',
        esc_attr( $level ),
        esc_html( $atts['text'] )
    );
}
add_shortcode( 'mysite_box', 'mysite_box_shortcode' );

属性は利用者が編集できる入力です。CSSクラス、URL、HTML本文など、出力先の文脈に合う関数でエスケープしてください。

囲み型ショートコードを作る

開始タグと終了タグの間を使う囲み型では、コールバックの第2引数で内容を受け取ります。HTMLを許可する範囲をwp_kses_postで絞った例です。

function mysite_note_shortcode( $atts, $content = null ) {
    if ( null === $content ) {
        return '';
    }

    return '<aside class="mysite-note">' . wp_kses_post( $content ) . '</aside>';
}
add_shortcode( 'mysite_note', 'mysite_note_shortcode' );

内側のショートコードまで実行したい設計ではdo_shortcodeを明示的に使います。ただし入れ子を深くすると編集者が構造を把握しにくくなるため、ブロックへの置き換えも検討します。

条件分岐を使ったショートコードの応用

条件分岐では、表示しない場合に空文字を返すのが基本です。たとえばログイン者専用の補足を出すなら、is_user_logged_inで判定できます。ただし、表示を隠すだけでは機密データのアクセス制御になりません。取得処理やREST APIにも権限確認が必要です。

投稿ID、投稿タイプ、ユーザー権限を参照するときは、ショートコードが一覧、ウィジェット、テンプレートなど複数の場所から呼ばれる可能性を考えます。グローバル変数が常に期待どおりとは限らないため、値が取得できない場合の戻り値も決めてください。

プラグインでショートコードを作る方法

PHPを直接編集したくない場合は、コードスニペット管理プラグインやショートコード作成プラグインを使う方法があります。選ぶときは、更新状況、対応するWordPress・PHP、権限管理、無効化時の挙動、エクスポート機能を確認します。

管理画面からPHPを実行できる製品は便利ですが、入力できるユーザーが増えるほど危険性も増します。管理者権限を必要最小限にし、変更履歴と復旧手段を用意してください。

ブロックパターン・同期パターンとの使い分け

見た目の部品を編集画面で再利用したいなら、ショートコードよりブロックパターンが適しています。現在のWordPressでは、内容を一括同期するものは同期パターン、挿入後に個別編集するものは非同期のパターンとして扱えます。

目的	向いている仕組み
PHPで計算・取得して動的に表示	ショートコードまたは動的ブロック
編集者が見たまま配置・変更	ブロックパターン
複数ページの同じ内容を一括更新	同期パターン
JavaScriptを含む高度なUI	カスタムブロック

新規実装では、編集体験、停止時の影響、移行のしやすさを比べて選びます。既存のショートコードを急いで置換する必要はありませんが、頻繁に編集する複雑なレイアウトはブロックのほうが扱いやすい場合があります。

ショートコードが表示されない・文字のまま出る場合

文字のまま出るときは、WordPressがそのタグを登録できていない可能性が高いです。次の順に確認します。

1. タグ名、角括弧、引用符に誤りがないか確認する
2. 提供元のテーマまたはプラグインが有効か確認する
3. ショートコードブロック単体へ移して試す
4. PHPエラーや重複したタグ登録がないかログを確認する
5. キャッシュを消し、ログイン状態を変えて再確認する

何も表示されない場合は、コールバックが空文字を返す条件、属性名の小文字化、権限判定を確認します。HTMLだけ崩れる場合は、タグの閉じ忘れやテーマCSSとの衝突を開発者ツールで調べます。

セキュリティと管理上の注意

ショートコードの入力値を信頼せず、受け取り時に型と許容範囲を検証し、表示時に文脈別のエスケープを行います。URLはesc_url、属性値はesc_attr、通常の文字列はesc_htmlが基本です。限定したHTMLを許可する場合はwp_kses系を使います。

データ更新、メール送信、外部API呼び出しなど副作用のある処理を、ページ表示だけで繰り返す設計は避けます。必要なら権限確認、nonce、重複実行防止を含むフォームや専用処理に分けてください。

また、どのタグをどの記事で使っているかを一覧化すると、提供元の停止や置換時に探しやすくなります。

よくある質問

まとめ

WordPressショートコードは、登録済みの処理を短いタグで呼び出す仕組みです。既存タグはショートコードブロックで使い、自作時は衝突しにくい名前、許可する属性、保存場所を先に決めます。

コールバックはechoではなく文字列をreturnし、入力検証と出力時のエスケープを組み合わせます。見た目の再利用が中心ならパターン、編集画面での操作性を高めたいならブロックも比較し、将来の停止やテーマ変更まで見通して選んでください。