2026年最新版: WordPressショートコード作成基礎とトラブル解決ガイド

WordPressショートコードとは？その重要性と近年の動向

WordPressにおけるショートコードは、特定の機能やコンテンツを簡単なタグで呼び出すための強力なツールでございます。例えば、[my_button text="クリック"]のような短いコードを投稿や固定ページに記述するだけで、複雑なHTMLやPHPコードを記述することなく、あらかじめ定義されたボタンが自動的に表示されるといった活用が可能です。

近年、WordPressはブロックエディタ（Gutenberg）の導入により、コンテンツ作成の体験が大きく変化いたしました。しかし、ショートコードはその役割を終えたわけではございません。特定の動的なコンテンツを繰り返し表示したい場合や、既存のテーマ・プラグインとの連携、あるいはPHPのロジックをシンプルに埋め込みたい場合など、ショートコードが依然として非常に有効な場面は多々ございます。特に、Classicブロックやショートコードブロックを利用することで、ブロックエディタ環境でもスムーズにショートコードを組み込むことが可能でございます。

また、WordPress本体やPHPのバージョンアップ（特にPHP 8.x系）に伴い、ショートコードの記述方法や互換性についても注意を払う必要がございます。本記事では、これらの最新の動向を踏まえ、ショートコードの安全かつ効果的な作成方法をご紹介してまいります。

ショートコードは、ブロックエディタでは難しい複雑なロジックや動的コンテンツの表示に、引き続き重宝いたします。

WordPressショートコードの基本的な作成手順

ショートコードを作成する最も基本的な方法は、WordPressのテーマファイル内にあるfunctions.phpにPHPコードを記述すること、またはカスタムプラグインとして作成することの2通りございます。弊社では、特にカスタムプラグインでの作成を強く推奨しております。これは、functions.phpに直接記述した場合、テーマの更新時にコードが失われるリスクがあるためでございます。

1. ショートコードの基本構造

ショートコードは、WordPressのadd_shortcode()関数を用いて登録いたします。この関数は、最初の引数にショートコード名（例：'my_shortcode'）、2番目の引数にそのショートコードが呼び出されたときに実行されるコールバック関数を指定いたします。

テーマ更新時のコード消失リスクを考えると、カスタムプラグインでの実装は将来的なメンテナンス性向上に繋がると存じます。

以下に、シンプルなショートコードの例をご紹介いたします。これは、現在の年月日を表示するショートコードです。


<?php
// ショートコードのコールバック関数
function display_current_date_shortcode() {
    return '<p>本日は ' . date_i18n( 'Y年m月d日' ) . ' でございます。</p>';
}

// ショートコードを登録
add_shortcode( 'current_date', 'display_current_date_shortcode' );
?>

このコードを記述し、投稿や固定ページに[current_date]と入力すると、「本日は 2026年xx月xx日でございます。」と表示されるようになります。

2. 属性（引数）を持つショートコードの作成

ショートコードに動的な情報を渡したい場合は、属性（attributes）を使用いたします。例えば、ボタンの色やテキストをショートコード内で指定できるようにする、といった活用方法がございます。属性を扱う際には、shortcode_atts()関数を用いてデフォルト値を設定し、ユーザーが指定した属性とマージすることが一般的でございます。

以下は、色とテキストを指定できるボタンショートコードの例でございます。


<?php
function custom_button_shortcode( $atts ) {
    // 属性のデフォルト値を設定し、ユーザー指定値とマージ
    $atts = shortcode_atts(
        array(
            'text'  => 'ボタン',
            'url'   => '#',
            'color' => 'blue',
            'target'=> '_self',
        ),
        $atts,
        'custom_button'
    );

    // HTMLを生成
    $output = '<a href="' . esc_url( $atts['url'] ) . '" class="custom-button" style="background-color:' . esc_attr( $atts['color'] ) . ';" target="' . esc_attr( $atts['target'] ) . '">';
    $output .= esc_html( $atts['text'] );
    $output .= '</a>';

    return $output;
}
add_shortcode( 'custom_button', 'custom_button_shortcode' );
?>

このショートコードは、[custom_button text="詳細はこちら" url="/contact/" color="green" target="_blank"]のように使用することが可能でございます。

3. 囲み型ショートコードの作成

ショートコードの中にもコンテンツを記述したい場合は、囲み型ショートコードを使用いたします。例えば、引用文を装飾するショートコードなどが考えられます。

コールバック関数の3番目の引数として$contentを受け取ることで、囲まれたコンテンツを処理できます。


<?php
function custom_quote_shortcode( $atts, $content = null ) {
    // 属性のデフォルト値を設定
    $atts = shortcode_atts(
        array(
            'author' => '名無し',
        ),
        $atts,
        'custom_quote'
    );

    // 囲まれたコンテンツと属性を元にHTMLを生成
    $output = '<blockquote class="custom-quote">';
    $output .= '<p>' . do_shortcode( wpautop( esc_html( $content ) ) ) . '</p>'; // do_shortcodeでネストされたショートコードも処理
    $output .= '<footer><cite>' . esc_html( $atts['author'] ) . '</cite></footer>';
    $output .= '</blockquote>';

    return $output;
}
add_shortcode( 'custom_quote', 'custom_quote_shortcode' );
?>

使用例：[custom_quote author="ブログ管理者"]ショートコードはサイト運営を効率化する強力なツールです。[/custom_quote]

カスタムプラグインとしての実装を推奨する理由

先述の通り、ショートコードのコードはカスタムプラグインとして作成し、管理することをおすすめいたします。

カスタムプラグインを作成する手順は以下の通りでございます。

WordPressのwp-content/plugins/ディレクトリ内に、新しいフォルダを作成します（例: my-custom-shortcodes）。
そのフォルダ内に、PHPファイルを作成します（例: my-custom-shortcodes.php）。
作成したPHPファイルの冒頭に、プラグイン情報を示すヘッダーを記述します。
上記でご紹介したショートコードのコードを、このPHPファイルに記述します。

my-custom-shortcodes.phpの例:


<?php
/**
 * Plugin Name: My Custom Shortcodes
 * Description: カスタムショートコードをまとめて管理するプラグインです。
 * Version: 1.0.0
 * Author: Your Name
 */

// ここにショートコードのコードを記述します

// 例: 現在日付表示ショートコード
function display_current_date_shortcode() {
    return '<p>本日は ' . date_i18n( 'Y年m月d日' ) . ' でございます。</p>';
}
add_shortcode( 'current_date', 'display_current_date_shortcode' );

// 例: カスタムボタンショートコード
function custom_button_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'text'  => 'ボタン',
            'url'   => '#',
            'color' => 'blue',
            'target'=> '_self',
        ),
        $atts,
        'custom_button'
    );
    $output = '<a href="' . esc_url( $atts['url'] ) . '" class="custom-button" style="background-color:' . esc_attr( $atts['color'] ) . ';" target="' . esc_attr( $atts['target'] ) . '">';
    $output .= esc_html( $atts['text'] );
    $output .= '</a>';
    return $output;
}
add_shortcode( 'custom_button', 'custom_button_shortcode' );

?>

このプラグインをWordPressの管理画面から有効化することで、テーマの変更や更新の影響を受けることなく、作成したショートコードを永続的に利用できるようになります。

ショートコード作成でよくある問題と解決方法

ショートコードの作成は非常に便利ですが、いくつかの問題に直面することもございます。ここでは、よくあるトラブルとその解決策をご紹介いたします。

1. ショートコードが機能しない・何も表示されない

記述ミス: ショートコード名や関数のスペルミス、セミコロンの抜けなど、PHPコードの記述ミスがないかご確認ください。
PHPエラー: PHP構文エラーが発生している可能性がございます。wp-config.phpファイルでdefine( 'WP_DEBUG', true );を設定し、エラーメッセージを確認してください。エラーログを確認することも有効でございます。
プラグインの未有効化: カスタムプラグインとして作成した場合、WordPress管理画面の「プラグイン」から有効化されているかご確認ください。
キャッシュの問題: サーバーキャッシュやWordPressのキャッシュプラグインが原因で、変更が反映されていない可能性がございます。キャッシュをクリアしてから再度お試しください。

2. HTMLタグが正しく出力されない・余計な改行が入る

自動改行の問題: WordPressは、ショートコードの前後や内部に<p>タグや<br />タグを自動挿入することがございます。これを防ぐには、ショートコードのコールバック関数の戻り値でHTMLを生成する際に、余計な空白や改行を含めないように注意し、場合によってはremove_filter( 'the_content', 'wpautop' );やremove_filter( 'the_excerpt', 'wpautop' );を一時的に使用することも検討できますが、これはサイト全体に影響するため慎重に行ってください。
エスケープ処理の不足: 出力するHTMLコンテンツや属性値に対して、適切なエスケープ処理（esc_html(), esc_url(), esc_attr()など）が施されていないと、意図しない表示になったり、セキュリティ上の脆弱性につながったりする可能性がございます。

3. PHPバージョンアップによる非互換性

WordPressはPHPで動作しており、PHPのバージョンは常に進化しております。特にPHP 8.x系では、多くの非推奨関数が削除されたり、厳密な型チェックが導入されたりしております。古いPHPバージョンで作成されたショートコードが、最新のPHP環境でエラーを出すケースがございます。

解決策: エラーメッセージを参考に、非推奨となった関数や構文を使用していないか確認し、最新のPHPバージョンに対応した記述に修正してください。公式サイトのドキュメントやPHPの移行ガイドが参考になります。

実際に弊社で運用しているサイトでも、PHP 8.0へのアップグレード時に、古いショートコードで非推奨関数を使用していたためにエラーが発生したことがございました。この経験から、WordPress本体だけでなく、PHPのバージョンアップにも常に注意を払い、開発環境での十分なテストが極めて重要であると痛感いたしました。

実践的なヒントと現時点でのベストプラクティス

ショートコードを安全かつ効率的に運用するためのヒントとベストプラクティスをご紹介いたします。

1. セキュリティ対策の徹底

ユーザーが入力する可能性のある属性値や、データベースから取得したデータなどを出力する際には、必ず適切なエスケープ処理（esc_html(), esc_attr(), esc_url()など）を行ってください。これにより、XSS（クロスサイトスクリプティング）などのセキュリティ脆弱性を防ぐことができます。

2. 命名規則の統一と衝突回避

ショートコード名やコールバック関数名は、他のプラグインやテーマとの衝突を避けるために、独自の名前空間を意識した命名規則を採用することをおすすめいたします。例えば、[mycompany_button]のように、会社名やプラグイン名をプレフィックスとして付与すると良いでしょう。

セキュリティ確保のため、属性値や出力データのエスケープ処理は必須でございます。 XSS脆弱性防止に直結いたしますため、適切な関数適用にご留意ください。

3. キャッシュ対策の考慮

ショートコードが出力する内容が頻繁に更新される動的な情報（例：リアルタイムの株価、アクセス数など）である場合、キャッシュプラグインやサーバーキャッシュによって古い情報が表示され続ける可能性がございます。このような場合は、ショートコードの出力部分をキャッシュ対象から除外するか、適切にキャッシュを無効化する処理を検討する必要がございます。

4. ブロックエディタとの連携と将来性

ブロックエディタ環境では、ショートコードブロックを利用することで既存のショートコードを挿入できます。より高度なUIや設定項目を必要とする場合は、ショートコードで対応するよりも、カスタムブロックとして実装する方がユーザー体験が向上する可能性もございます。どちらを選択するかは、機能の複雑性や開発リソースを考慮して判断されるのが良いでしょう。

リアルタイム情報を扱うショートコードでは、キャッシュ除外設定が肝要でございます。サーバー側の設定も併せてご確認くださいませ。

シンプルな動的コンテンツや既存のテーマ・プラグインとの連携であればショートコードが手軽でございますが、複雑なUIや高度なインタラクションが必要な場合は、カスタムブロックの導入を検討されるのが良いと存じます。

5. 開発環境での十分なテスト

新しいショートコードを導入したり、既存のショートコードを修正したりする際は、必ず本番環境に適用する前に開発環境で十分にテストを行ってください。WP_DEBUGを有効にし、エラーログを確認しながらデバッグを進めることで、本番環境での予期せぬトラブルを未然に防ぐことができます。

ショートコードの導入・修正時は、開発環境での十分なテストが不可欠でございます。WP_DEBUGの活用もトラブル解決に役立つかと存じます。

まとめ

本記事では、WordPressにおけるショートコードの基本的な作成方法から、属性や囲み型ショートコードの活用、そしてカスタムプラグインとしての実装推奨理由、さらにはよくあるトラブルとその解決策、現時点でのベストプラクティスまでを詳しく解説いたしました。

ショートコードは、WordPressサイトの機能拡張やコンテンツ管理を効率化するための非常に強力なツールでございます。しかし、その作成と運用には、PHPの基礎知識に加え、セキュリティや互換性への配慮が不可欠でございます。特に2026年現在、WordPress本体やPHPの進化に伴い、最新の情報をキャッチアップし、適切な手法で実装することが、安定したサイト運営には欠かせません。

ご紹介した手順やヒントをご参考に、皆様のWordPressサイトがより使いやすく、より安全になるよう、ショートコードを効果的にご活用いただければ幸いでございます。もしショートコードの作成やトラブル解決でお困りの際は、本記事の内容が皆様の一助となればこれに勝る喜びはございません。

目次