DEVELOPER · REFERENCE

開発者向けリファレンス

報助 for Welcart が公開しているすべての拡張ポイントのリファレンスです。テーマ / 子テーマや別プラグインから、UI・メール・在庫検知・通知処理の各段階に介入できます。

Contents

  1. ショートコード
  2. フィルタフック
  3. アクションフック
  4. REST API
  5. WP-CLI コマンド
  6. Welcart 連携ポイント
  7. カスタムテーブル
01—Shortcodes

ショートコード

報助 は 3 つのショートコードを提供します。固定ページ・投稿・ウィジェット・テーマテンプレートのいずれでも利用できます。

[hosuke_restock_list]

直近に再入荷した商品の一覧を表示します。

属性型デフォルト説明
daysint7過去何日分の再入荷を表示するか (1〜365)
per_pageint201 ページあたりの表示件数 (1〜100)
[hosuke_restock_list days="14" per_page="30"]

[hosuke_unsubscribe]

通知の解除フォームを表示します。プラグイン有効化時に自動で作成される固定ページ「通知の解除」(スラッグ hosuke-unsubscribe) 内でこのショートコードが使われます。

メール本文内の {unsubscribe_url} はこの固定ページの URL に、解除トークンをクエリで付けたものが自動生成されます。

[hosuke_unsubscribe]

[hosuke_my_notifications]

Welcart 会員マイページ用の通知一覧を表示します。ログイン中の会員自身が登録中の通知を確認・解除できます。

[hosuke_my_notifications]

Welcart マイページへの自動注入も設定画面から有効化できます (表示とカスタマイズ > 会員マイページ統合)。

02—Filters

フィルタフック

報助 は 11 個のフィルタフックを公開しています。値を差し替えて挙動をカスタマイズできます。

hosuke_should_show_button

商品ページに再入荷通知ボタンを表示するかどうかを決定します。

apply_filters( 'hosuke_should_show_button', bool $should, int $post_id, string $sku_code );

例: 特定カテゴリの商品ではボタンを非表示にする。

add_filter( 'hosuke_should_show_button', function ( $should, $post_id, $sku_code ) {
    if ( has_term( 'sale', 'product_category', $post_id ) ) {
        return false;
    }
    return $should;
}, 10, 3 );

hosuke_button_label

ボタンに表示するラベル文字列を差し替えます。

apply_filters( 'hosuke_button_label', string $label, int $post_id, string $sku_code );

hosuke_button_html

ボタン全体の HTML を差し替えます。独自マークアップを注入したい場合に使用。

apply_filters( 'hosuke_button_html', string $html, int $post_id, string $sku_code );

hosuke_default_email

登録フォームのメールアドレス初期値を差し替えます。デフォルトでは Welcart ログイン中の会員のメールアドレスが入ります。

apply_filters( 'hosuke_default_email', string $email );

hosuke_email_subject

送信メールの件名を差し替えます。

apply_filters( 'hosuke_email_subject', string $subject, string $type, array $notification );

$type は 'registration' / 'restock' / 'admin' のいずれか。

hosuke_email_body

送信メールの本文を差し替えます。

apply_filters( 'hosuke_email_body', string $body, string $type, array $notification );

hosuke_email_headers

送信メールのヘッダを差し替えます。Reply-To、Cc 等の追加に。

apply_filters( 'hosuke_email_headers', array $headers, string $type, array $notification );

hosuke_email_template_path

メールテンプレのテンプレートファイルの絶対パスを差し替えます。テーマ側で HTML メールにしたい場合等に。

apply_filters( 'hosuke_email_template_path', string $path, string $type );

hosuke_client_ip

レートリミット判定のクライアント IP を差し替えます。リバースプロキシ配下では X-Forwarded-For 等から取得するよう上書きしてください。

apply_filters( 'hosuke_client_ip', string $ip );
add_filter( 'hosuke_client_ip', function ( $ip ) {
    if ( ! empty( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) {
        $forwarded = sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_FORWARDED_FOR'] ) );
        $parts     = explode( ',', $forwarded );
        return trim( $parts[0] );
    }
    return $ip;
} );

hosuke_recaptcha_threshold

reCAPTCHA v3 のスコア閾値を差し替えます (デフォルト 0.5)。

apply_filters( 'hosuke_recaptcha_threshold', float $threshold );

hosuke_periodic_scan_batch_size

15 分周期スキャン (WP-Cron フォールバック) の 1 回あたりの検査対象 SKU 件数を差し替えます。デフォルト 50。

apply_filters( 'hosuke_periodic_scan_batch_size', int $batch_size );

hosuke_unsubscribe_page_slug

プラグイン有効化時に作成される解除ページのスラッグを差し替えます。デフォルト notify-off。

apply_filters( 'hosuke_unsubscribe_page_slug', string $slug );
03—Actions

アクションフック

報助 は 6 個のアクションフックを発火します。イベントを検知して独自処理を挟むのに使えます。

hosuke_before_register

通知登録の直前に発火します。

do_action( 'hosuke_before_register', array $data );

hosuke_after_register

通知登録が完了した直後に発火します。

do_action( 'hosuke_after_register', int $notification_id, array $data );

例: 外部 CRM に登録者情報を送信する。

add_action( 'hosuke_after_register', function ( $notification_id, $data ) {
    wp_remote_post( 'https://crm.example.com/api/leads', array(
        'body' => wp_json_encode( array(
            'email'    => $data['email'],
            'source'   => 'hosuke',
            'item'     => get_the_title( $data['post_id'] ),
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 2 );

hosuke_stock_restored

在庫が 0 → 1 以上に復活した瞬間に発火します。通知メール送信の直前にも独自処理を挟めます。

do_action( 'hosuke_stock_restored', int $post_id, string $sku_code, int $stock_num );

hosuke_notification_sent

個別の通知メール送信に成功した直後に発火します。

do_action( 'hosuke_notification_sent', int $notification_id, array $row );

hosuke_notification_failed

個別の通知メール送信が失敗した直後に発火します。$error_message には失敗理由が入ります。

do_action( 'hosuke_notification_failed', int $notification_id, array $row, string $error_message );
04—REST API

REST API

報助 は hosuke/v1 名前空間で 2 つのエンドポイントを提供します。

POST /wp-json/hosuke/v1/send-queue

送信キューを手動で処理します。manage_options 権限が必要 (認証付き)。

パラメータ型必須説明
limitint任意1 回に処理する最大件数 (1〜1000)。未指定なら option hosuke_send_queue_batch_size の値を使用
curl -X POST https://example.com/wp-json/hosuke/v1/send-queue \
  -H "X-WP-Nonce: $(wp eval 'echo wp_create_nonce("wp_rest");')" \
  -d "limit=50"

GET /wp-json/hosuke/v1/restock-list

直近の再入荷商品一覧を返します。認証不要 (公開)。

パラメータ型デフォルト説明
daysint7過去何日分の再入荷を返すか (1〜365)
per_pageint201 ページあたりの件数 (1〜100)
curl https://example.com/wp-json/hosuke/v1/restock-list?days=14&per_page=30
05—WP-CLI

WP-CLI コマンド

wp hosuke send-queue

送信キューを手動で処理します。cron や systemd timer からの定期実行に。

オプション型説明
--limit=<number>int1 回に処理する最大件数。未指定なら option hosuke_send_queue_batch_size の値
# デフォルト設定で処理
wp hosuke send-queue

# 10 件だけ処理
wp hosuke send-queue --limit=10

# 100 件まで処理
wp hosuke send-queue --limit=100

コマンド実行後、以下のような出力を返します:

Processed: 12, Succeeded: 11, Failed (retry): 1, Gave up: 0, Skipped (backoff): 0
Success: Done. 11 succeeded.
06—Welcart

Welcart 連携ポイント

報助 は Welcart 内部の以下の拡張ポイントを利用しています。テーマ / 他プラグインの改造時にはこれらの互換性にご注意ください。

ボタン注入: usces_filters_single_sku_zaiko_message

Welcart 標準の「売切」ラベル出力フィルタに add_filter することで、売切ラベルの隣に通知ボタンを注入しています。テーマがこのフィルタを呼ばない独自実装の場合、ボタンは表示されません。

在庫検知の主軸: usces_action_save_product

Welcart 商品保存時のアクションです。ここで前回スキャン時の在庫数と比較し、0 → 1+ の遷移を検知した SKU に対して通知処理を発火させます。

在庫検知の補助: 注文フック

usces_action_reg_orderdata 経由で、注文成立に伴う在庫変動もリアルタイム検知します。

SKU 個別 AJAX 更新のフォールバック: admin_init + shutdown

Welcart レガシー編集画面 (admin.php?page=usces_itemedit) の SKU 個別 AJAX 更新は save_post や update_post_meta を経由しない直接 SQL の可能性が高いため、admin_init フックで wp_hosuke_stock_watch テーブルから pending > 0 な全 post_id を収集し、shutdown フックで再検証するフォールバック層があります。

会員情報の取得

登録者の Welcart 会員情報は $usces->get_member()['mailaddress1'] で取得しています (DB カラム名 mem_email ではなく mailaddress1 キー)。新旧 2 系統の会員 API (wel_* / usces_*) 両対応。

SKU の取得

商品の SKU 情報は wel_get_skus( $post_id, 'code' ) で取得しています。Welcart はカスタムテーブル wp_usces_master ではなく現行バージョンでは wp_postmeta に SKU 情報を格納しています。

07—Tables

カスタムテーブル

報助 は WordPress の $wpdb->prefix ベースで 2 つのカスタムテーブルを作成します。有効化時に dbDelta() で自動作成、アンインストール時にオプションで削除。

{prefix}hosuke_notifications

通知登録レコードのメインテーブル。

カラム型説明
idBIGINT UNSIGNED主キー
post_idBIGINT UNSIGNEDWelcart 商品の post_id
sku_codeVARCHAR(191)SKU コード
emailVARCHAR(191)通知先メールアドレス
member_idBIGINT UNSIGNEDWelcart 会員 ID (ゲストの場合 NULL)
statusVARCHAR(32)pending / queued / sent / unsubscribed / expired / failed
retry_countINT UNSIGNEDリトライ回数
last_errorTEXT直近の失敗理由
unsubscribe_tokenVARCHAR(64)解除リンク用トークン
created_atDATETIME登録日時 (UTC)
notified_atDATETIME通知送信日時 (UTC, NULL 可)
unsubscribed_atDATETIME解除日時 (UTC, NULL 可)

{prefix}hosuke_stock_watch

在庫の前回スキャン結果を保持する内部テーブル。0 → 1+ の遷移検知に利用。

カラム型説明
post_idBIGINT UNSIGNEDWelcart 商品の post_id (複合主キー)
sku_codeVARCHAR(191)SKU コード (複合主キー)
previous_stockINT前回スキャン時の在庫数
pendingINT UNSIGNEDこの SKU に登録中の pending 件数キャッシュ
last_checked_atDATETIME最終検査日時 (UTC)
last_restock_atDATETIME最終再入荷検知日時 (UTC, NULL 可)
注意 これらのテーブルへの直接 INSERT / UPDATE / DELETE はサポート対象外です。データ操作は必ず REST API・WP-CLI・管理画面 UI 経由でお願いします。
Support リファレンスに不明点がある場合は お問い合わせフォーム または WordPress.org サポートフォーラム からご相談ください。