既存のウィジェットに独自設定を追加して保存・取得する方法

はじめに
完成イメージ
実装手順
さいごに

はじめに

既存ウィジェットに独自の設定項目を追加したい場合は、用意されているフックを利用することで、安全に拡張できます。

この記事では、「最新の投稿」ウィジェットに表示フラグ（チェック項目）を追加するケースを例に、処理を大きな単位ごとに分けて解説します。

完成イメージ

実装手順

以下の流れで実装します。

対象のウィジェットIDの特定
設定メニューを追加
入力データを保存
フロントエンド表示へ反映

対象のウィジェットIDの特定

カスタマイズを適用するには、対象ウィジェットの内部ID（id_base）を確認する必要があります。
管理画面の外観 → ウィジェットを開き、対象ウィジェットのHTMLを確認します。

id="widget-xxxx-__i__"のxxxx部分がid_baseです。
例えば「最新の投稿」ウィジェットの場合は recent-postsになります。

設定メニューを追加

in_widget_formアクションフックを使用し、既存ウィジェットの編集画面（管理画面）に独自のカスタム設定項目を追加します。

add_action('in_widget_form', function ($widget, $return, $instance) {
  if ($widget->id_base !== 'recent-posts') {
    return;
  }

  $key = 'custom_display_flag'; 

  $field_id   = $widget->get_field_id($key);
  $field_name = $widget->get_field_name($key);
  $checked    = checked(!empty($instance[$key]), true, false);

  ?>
  <p>
    <input type="checkbox" id="<?= esc_attr($field_id); ?>" name="<?= esc_attr($field_name); ?>" value="1" <?= $checked; ?>>
    <label for="<?= esc_attr($field_id); ?>">独自オプションを有効にする</label>
  </p>
  <?php
}, 10, 3);

入力データを保存

管理画面でウィジェットの設定が保存された際、widget_update_callbackフィルターを使用して、追加した独自項目の状態（オン・オフ）を安全にデータベースへ保存・更新します。

add_filter('widget_update_callback', function ($instance, $new_instance, $old_instance, $widget) {
  if ($widget->id_base !== 'recent-posts') {
    return $instance;
  }

  $key = 'custom_display_flag';

  if (isset($new_instance[$key])) {
    $instance[$key] = sanitize_text_field($new_instance[$key]);
  } else {
    unset($instance[$key]);
  }

  return $instance;
}, 10, 4);

フロントエンド表示への反映

保存された設定値は$instanceに格納されています。
widget_display_callbackフィルターでその値を取得し、チェックが入っている場合にのみHTML構造やクラスの書き換えなど、独自の出力処理をサイト上に反映させます。

add_filter('widget_display_callback', function ($instance, $widget, $args) {
  if ($widget->id_base !== 'recent-posts') {
    return $instance;
  }

  $key = 'custom_display_flag';

  if (empty($instance[$key])) {
    return $instance;
  }

  // ここに独自処理を書く（例：CSSクラスを追加）
  $args['before_widget'] = str_replace(
    'class="',
    'class="is-special-style ',
    $args['before_widget']
  );

  $widget->widget($args, $instance);
  return false;
}, 10, 3);

さいごに

今回紹介した方法を使えば、既存ウィジェットに独自の設定項目を追加し、保存・取得まで安全に実装できます。
これにより、ウィジェットの機能を拡張し、用途に応じた表示制御や独自仕様を安全に追加することが可能です。