ショートコード
報助 は 3 つのショートコードを提供します。固定ページ・投稿・ウィジェット・テーマテンプレートのいずれでも利用できます。
[hosuke_restock_list]
直近に再入荷した商品の一覧を表示します。
| 属性 | 型 | デフォルト | 説明 |
|---|---|---|---|
days | int | 7 | 過去何日分の再入荷を表示するか (1〜365) |
per_page | int | 20 | 1 ページあたりの表示件数 (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 マイページへの自動注入も設定画面から有効化できます (表示とカスタマイズ > 会員マイページ統合)。
フィルタフック
報助 は 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 );
アクションフック
報助 は 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 );
REST API
報助 は hosuke/v1 名前空間で 2 つのエンドポイントを提供します。
POST /wp-json/hosuke/v1/send-queue
送信キューを手動で処理します。manage_options 権限が必要 (認証付き)。
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
limit | int | 任意 | 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
直近の再入荷商品一覧を返します。認証不要 (公開)。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
days | int | 7 | 過去何日分の再入荷を返すか (1〜365) |
per_page | int | 20 | 1 ページあたりの件数 (1〜100) |
curl https://example.com/wp-json/hosuke/v1/restock-list?days=14&per_page=30
WP-CLI コマンド
wp hosuke send-queue
送信キューを手動で処理します。cron や systemd timer からの定期実行に。
| オプション | 型 | 説明 |
|---|---|---|
--limit=<number> | int | 1 回に処理する最大件数。未指定なら 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.
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 情報を格納しています。
カスタムテーブル
報助 は WordPress の $wpdb->prefix ベースで 2 つのカスタムテーブルを作成します。有効化時に dbDelta() で自動作成、アンインストール時にオプションで削除。
{prefix}hosuke_notifications
通知登録レコードのメインテーブル。
| カラム | 型 | 説明 |
|---|---|---|
id | BIGINT UNSIGNED | 主キー |
post_id | BIGINT UNSIGNED | Welcart 商品の post_id |
sku_code | VARCHAR(191) | SKU コード |
email | VARCHAR(191) | 通知先メールアドレス |
member_id | BIGINT UNSIGNED | Welcart 会員 ID (ゲストの場合 NULL) |
status | VARCHAR(32) | pending / queued / sent / unsubscribed / expired / failed |
retry_count | INT UNSIGNED | リトライ回数 |
last_error | TEXT | 直近の失敗理由 |
unsubscribe_token | VARCHAR(64) | 解除リンク用トークン |
created_at | DATETIME | 登録日時 (UTC) |
notified_at | DATETIME | 通知送信日時 (UTC, NULL 可) |
unsubscribed_at | DATETIME | 解除日時 (UTC, NULL 可) |
{prefix}hosuke_stock_watch
在庫の前回スキャン結果を保持する内部テーブル。0 → 1+ の遷移検知に利用。
| カラム | 型 | 説明 |
|---|---|---|
post_id | BIGINT UNSIGNED | Welcart 商品の post_id (複合主キー) |
sku_code | VARCHAR(191) | SKU コード (複合主キー) |
previous_stock | INT | 前回スキャン時の在庫数 |
pending | INT UNSIGNED | この SKU に登録中の pending 件数キャッシュ |
last_checked_at | DATETIME | 最終検査日時 (UTC) |
last_restock_at | DATETIME | 最終再入荷検知日時 (UTC, NULL 可) |
INSERT / UPDATE / DELETE はサポート対象外です。データ操作は必ず REST API・WP-CLI・管理画面 UI 経由でお願いします。