WordPress のプラグインが公開停止になると、それを使っていたサイトが取り残されます。

止まった瞬間に動かなくなるわけではないので、しばらくは誰も困りません。困るのは、本体の更新で急に壊れたときか、乗り換えようとしたときです。**乗り換えるには、固定ページの中身を全部書き直す必要がある。**それが面倒で、そのまま置いてある。

移行先を作るなら、その書き直しを不要にできます。旧プラグインの記法をこちら側で認識すればいい。

ただ、他人の記法を引き取るのは、思っていたより判断が要りました。5つ決めたので、順に書きます。

検証環境：【WordPress・PHP のバージョンと確認日を入れる】

1. 相手が生きている間の、ショートコード

いちばん最初に踏んだのがこれです。

同じショートコード名を add_shortcode() で登録すると、**あとから登録したほうが勝ちます。**上書きされるだけで、警告も出ません。

旧プラグインと新プラグインが両方有効な状態だと、どちらが描画しているのか分からなくなります。片方を無効化するまで気づかない。

なので、登録の前に見ます。

add_action( 'init', function () {
    // 相手がすでに登録していたら、こちらは名乗り出ない
    if ( shortcode_exists( 'wp_sitemap_page' ) ) {
        return;
    }
    add_shortcode( 'wp_sitemap_page', 'rapls_sitemap_render_compat' );
}, 20 );

優先度を 20 にしているのは、相手が登録し終わったあとに確認したいからです。ショートコードは init で登録されることが多いので、既定の 10 だと、相手より先に走ることがあります。先に走ると shortcode_exists() は false を返して、こちらが登録してしまう。

wp_loaded まで待つ手もありますが、ショートコードの登録としては遅すぎる場面があるので、init の後ろにしました。

余談ですが、この「あとから登録したほうが勝つ」仕様は、add_shortcode() のドキュメントに書いてあります。読んでいたのに、実際に両方有効にするまで、意味が分かっていませんでした。

2. 引き取りを opt-in にする

引き取る機能そのものを、初期状態では無効にしました。

理由は、黙って他人の記法に反応するのは驚かせるからです。

新しいプラグインを入れたら、書いた覚えのないショートコードが急に描画を始める。動くぶんには問題ないように見えますが、サイトの持ち主からすると、何が起きているのか分かりません。

設定画面に「他のプラグインから移行する」という項目を作って、そこで自分でオンにしてもらう形にしました。

// 引き取りは opt-in。既定は false
$compat = get_option( 'rapls_sitemap_compat', [
    'wp_sitemap_page' => false,
    'ps_auto_sitemap' => false,
] );

便利さと、驚かせないこと。ここは驚かせないほうを取りました。

3. HTMLコメントは、content フィルタで置換する

PS Auto Sitemap は、ショートコードではなくHTMLコメントを目印にしていました。

<!-- SITEMAP CONTENT REPLACE POINT -->

固定ページの本文にこれを書いておくと、そこにサイトマップが差し込まれる。ショートコードと違って、エディタ上で何も表示されないのが特徴です。

引き取るには、the_content を通すときに置換します。

add_filter( 'the_content', function ( $content ) {
    $marker = '<!-- SITEMAP CONTENT REPLACE POINT -->';

    if ( false === strpos( $content, $marker ) ) {
        return $content;
    }

    return str_replace( $marker, rapls_sitemap_render(), $content );
}, 20 );

気をつけたのは2つです。

マーカーが無ければ、何もせずに返す。the_content は全記事で走るので、置換を試みる前に strpos() で抜けます。

優先度をショートコード展開より後ろにする。do_shortcode は the_content の優先度 11 に入っています。それより前に差し込むと、生成したHTMLの中のショートコードらしき文字列が、あとから展開される可能性がある。20 にして、後ろに置きました。

4. 旧設定の読み込み

PS Auto Sitemap の設定を、ボタン1つで取り込めるようにしました。

ここで決めたのは、相手のオプションには一切書き込まないことです。

// 読む。書かない
$old = get_option( 'ps_auto_sitemap_options' );

if ( is_array( $old ) ) {
    $new = rapls_sitemap_map_from_ps( $old );
    update_option( 'rapls_sitemap_settings', $new );
}

読むだけにすると、うまくいかなかったときに戻せます。旧プラグインを再度有効にすれば、元の設定がそのまま残っている。

もし正規化のつもりで旧オプションを書き換えると、**戻る場所がなくなります。**移行は片道になるべきではない、と思っています。

5. 移せないものの扱い

取り込みで、そのままにならない項目がありました。

デザインは、旧プラグインのものを再現していません。用意してあるプリセットのうち、いちばん近いものに寄せるだけです。再現ではなく近似なので、そう書きました。

表示モードも、対応する概念が無いものは別の形になります。こちらの場合、旧プラグインの「分割」表示が、カテゴリーだけの一覧に変わりました。

取り込んだ直後に「完了しました」とだけ出すこともできますが、それだと利用者は完全に移ったと思い込みます。近似したもの、変わったものを画面に並べて、確認を促す形にしました。

移行機能で怖いのは、失敗することより、成功したように見えて中身が違っていることです。

引き取るかどうかの判断

5つ書きましたが、そもそも引き取るべきかどうかから迷いました。

引き取らない、という選択もあります。移行手順を書いて、利用者に固定ページを直してもらう。実装は簡単ですし、他人の記法に依存しないぶん、あとの保守も楽です。

引き取ることにしたのは、書き直しが面倒だから乗り換えていない人が多いと思ったからでした。公開停止から時間が経っても代替が定着していないのは、機能の問題ではなく、移行のコストの問題に見えます。

ただ、引き取ると決めた時点で、相手のプラグインの仕様に縛られます。相手が更新されることはもう無いので、その意味では安定していますが、こちらのコードに他人の設計が一枚入ることにはなります。

この記事のまとめ

同名ショートコードは後勝ち。登録前に shortcode_exists() で確認し、init の優先度を後ろにする
引き取りは opt-in にする。黙って他人の記法に反応しない
HTMLコメントの置換は the_content の優先度 20 以降。マーカーが無ければ即 return
旧設定は読むだけ。書き込むと戻れなくなる
近似でしか移せないものは、そう書く。成功したように見えて中身が違うのがいちばん怖い

コードそのものは、どれも短いものでした。時間を使ったのは、引き取るかどうか、どこまで自動でやるか、という判断のほうです。

自分が使っているプラグインが明日公開停止になったとして、移行先は、どこまで面倒を見てくれると期待するでしょうか。作る側になってみると、その線引きが意外と難しいところでした。

ふだんはraplsworks.comで、WordPressプラグイン開発やClaude Codeまわりのことを書いています。