なぜブロックテーマでショートコードを使うのか？

ブロックテーマ以前はテンプレートファイルとして header.php single.php など phpファイルが使用されていたので、これらにコードを追記してカスタマイズしていた人も多いでしょう。

しかし、ブロックテーマではこれらのテンプレートphpファイルは使われません。

フルサイトエディターで種々のブロックを挿入、配置することでコードを記述することなく簡単にテンプレートを作成できます。
カスタマイズもプラグインで目的のブロックを追加し、そのブロックを挿入、配置することで行います。

ここで問題になるのは、必要なブロックのプラグインがない場合です。

その場合、ブロックを自作すればいいのですが、作り方が分からない…
ブロックを自作するためのプラグインもあるようなのでいずれは自作してみたいですが、もっと簡単なやり方はないでしょうか？

そこで登場するのがショートコードです。

ショートコードブロックを挿入・配置し、そこからショートコードを呼び出して phpコードを実行させるのです。
これなら「phpコードをコピペで貼り付け」みたいに簡単にできます。

ショートコードはあらかじめ functions.php で登録しておきます。

ショートコードの登録（基本）

// 自己完結型ショートコード（引数なし）
function my_shortcode01() {
   ob_start();
   // ここに phpコードを書く
   return ob_get_clean();
}
add_shortcode( 'shortcode_name01', 'my_shortcode01' );

２～６行目が関数の定義で、２行目の my_shortcode01 はこの関数の名前です。
７行目がショートコードの登録で、関数 my_shortcode01 をショートコード名 shortcode_name01として登録しています。
ショートコード名はショートコードを呼び出すときに使う名前です。

ショートコードを使うときはショートコードブロックに [ショートコード名] と記述します。
上記例の場合、[shortcode_name01] と記述すればショートコード shortcode_name01 が呼び出され、関数 my_shortcode01 が実行されます。

上記例では関数に名前を付けましたが、名前を付けずに登録することも出来ます。

// 自己完結型ショートコード（引数なし）
add_shortcode( 'shortcode_name01', function() {
   ob_start();
   // ここに phpコードを書く
   return ob_get_clean();
} );

ただし、add_filter() と add_action() で無名関数を使用することは禁止されています。
※ remove_filter()、remove_action() で無名関数を解除できない為

引数ありショートコード

// 自己完結型ショートコード（引数あり）
function my_shortcode02( $atts ) {
  $atts = shortcode_atts( array(
    'jp'  => 'あいう',
    'num' => '123',
    'en'  => 'abc',
  ), $atts );
  ob_start();
  // ここに phpコードを書く
  // 引数は $atts['jp'], $atts['num'], $atts['en'] として利用できます
  return ob_get_clean();
}
add_shortcode( 'shortcode02', 'my_shortcode02' );

引数ありのショートコードを使えば [shortcode02 jp="かきく" en="def" num="456"] などとして値を渡すことが出来ます。

３～７行目で使用するキーと初期値を定義しています。
'jp' => 'あいう' はキーが jp で、その初期値が あいう です。
初期値は [shortcode02 num="456"] など、引数が省略された時に使用されます。

以下は受け取った引数（配列）を取り扱いやすいように extract() 関数を使って変数にしています。（関数名なし）

// 自己完結型ショートコード（引数あり）
add_shortcode('shortcode02', function( $atts ) {
  extract( shortcode_atts( array(
    'jp'  => 'あいう',
    'num' => '123',
  ), $atts) );

  ob_start();
  // ここに phpコードを書く
  // 引数は $jp, $num として利用できます
  return ob_get_clean();
} );

ただし、WordPress では extract() 関数の利用は禁止されているようです。

なので上記コードは下記のように記述した方がいいでしょう。

// 自己完結型ショートコード（引数あり）
add_shortcode( 'shortcode02', function( $atts ) {
   $atts = shortcode_atts( array(
      'jp'  => 'あいう',
      'num' => '123',
   ), $atts );

   $jp  = $atts['jp'];
   $num = $atts['num'];

   ob_start();
   // ここに phpコードを書く
   // $jp, $num を利用する
   return ob_get_clean();
} );

囲み型ショートコード

囲み型ショートコードは [ショートコード名]テキスト[/ショートコード名] と記述して使用すると間に挟まれたテキストを引数として渡すことが出来ます。

//囲み型ショートコード
function my_shortcode03( $atts, $content ) {
  $atts = shortcode_atts( array(
      'key01' => '',
   ), $atts );

   if ( empty( $content ) && !( $content === 0 || $content === "0" ) )
      $content = '初期値';

   ob_start();
   // ここに phpコードを書く
   // 間に挟まれたテキストは $content として利用できます
   return ob_get_clean();
}
add_shortcode( 'shortcode03', 'my_shortcode03' );

間に挟まれたテキストは第２引数が受け取ります。（上記例では $content）

初期値を設定する為に２行目を

function my_shortcode03( $atts, $content = '初期値' ) {

とした場合、引数に null を渡すとデフォルト値は代入されません。（$content = null になる）
※ 引数に null が渡された場合デフォルト値は代入されないのは PHP の仕様です

なので ７～８行目で引数が null や空文字（''）などの場合のデフォルト値を設定しています。

ショートコードブロックを使う場合の注意点

ショートコードブロックからショートコードを呼び出すと remove_filter('the_content', 'wpautop'); を記述していても wpautop が適用され表示が崩れることがあります。

wpautop を無効にできればいいのですが、その方法が分かりません…

この場合、カスタムHTMLブロックから呼び出せば wpautop は適用されない様です。（remove_filter('the_content', 'wpautop'); は必要かも？）