WordPressでSVGアイキャッチを表示するプラグインを開発した（svg-eyecatch-iconプラグイン）

WordPressの投稿にSVGアイキャッチアイコンを表示したいと思いました。そこで、カスタムフィールドでSVGコードを管理し、投稿タイトル前に表示するプラグインを開発しました。

SVGアイキャッチを表示する
https://app.chiilabo.jp/wordpress-plugins/svg-eyecatch-icon-1.0.4.zip

開発の背景と要件

GeneratePressテーマを使用したWordPressサイトで、各投稿にSVGアイキャッチアイコンを表示したいと思います。

具体的な要件は以下の通りです。

投稿編集画面でSVGコード全体を直接入力し、投稿詳細ページと一覧ページの両方でタイトル前にアイコンを表示します。
また、SVGには自動的にeyecatch-svgクラスを付与し、CSSでスタイリングできるようにします。

通常の画像アップロード方式ではなく、SVGコードを直接管理する方式を選択したのは、サイズやカラーの調整が柔軟に行えるためです。

プラグインの基本構造

WordPressプラグインのフォルダ構成に従って作成し、圧縮ファイルでインストールできるようにしました。

フォルダ作成: svg-eyecatch-icon という名前のフォルダを作成
ファイル配置: 以下の2つのファイルをフォルダ内に配置
ZIP圧縮: フォルダを圧縮してZIPファイルを作成
WordPressにアップロード: 管理画面の「プラグイン」→「新規追加」→「プラグインのアップロード」からZIPファイルをアップロード

svg-eyecatch-icon/
├── svg-eyecatch-icon.php
└── readme.txt

メインのPHPファイルには、プラグイン情報をヘッダーコメントで記述すると、WordPress管理画面でプラグインとして認識されます。名前空間の競合を避けるために、プラグインの機能は、 SVGEyecatchIcon クラスにまとめています。コンストラクタでWordPressのアクションフックに関数を登録し、各機能を適切なタイミングで実行されるようにしました。これで管理画面からZIPファイルでインストールできるプラグインが完成します！

カスタムフィールドの実装

投稿編集画面にSVGコード入力用のメタボックス（カスタムフィールド）を追加しました。

WordPress標準のadd_meta_boxesアクションを使用します。add_meta_box関数を使い、投稿編集画面に新しい入力欄を作成できました。この関数では、表示位置や優先度を指定できます。今回はnormal位置にhigh優先度で配置し、目立つ場所に表示させました。

入力したSVGコードは、save_postアクションフックを使用して、投稿保存時にカスタムフィールドに保存します。セキュリティ対策として、nonceによる確認と権限チェックを実装しました。nonceは「一度だけ使用される数値」の略で、フォーム送信が正当なものかを確認するWordPressの仕組みです。これにより、意図しない投稿の改変を防げます。

SVGコードのサニタイズと許可タグの定義

SVGファイルにはJavaScriptコードが含まれる可能性があるため、セキュリティ対策が重要です

WordPressのwp_kses関数を使用して、許可されたタグと属性のみを残します。

SVGの基本要素であるsvg、path、circle、rect、gなどのタグと、それぞれに必要な属性を配列で定義しました。例えば、circleタグにはcx、cy、rなどの座標や半径を指定する属性を許可します。CSS定義を含む複雑なSVGファイルを扱えるように、<style>タグやCSS関連の属性、さらにアニメーション用の<animateTransform>タグも許可リストに追加しました。

SVGファイルには<?xml version="1.0" encoding="UTF-8"?>というXML宣言が含まれることがありますが、ブラウザでの表示には不要です。保存時に自動的に除去する処理を追加しました。

これらの要素を順次追加して、より実用的なSVGファイルに対応できるようになりました。

エラーハンドリングとXML宣言の処理

SVGファイルの柔軟性を保ちつつ、セキュリティリスクを最小限に抑える必要がありました。許可するタグと属性を段階的に拡張し、実用的なSVGファイルに対応できるよう調整しました。

SVGコードの入力ミスや不正なコードを検出するため、検証機能を実装しました。SVGタグの存在確認、閉じタグの確認、危険なスクリプトタグの検出を行います。これらの検証により、明らかに問題のあるコードを事前に防げます。

検証エラーが発生した場合は、管理画面にエラーメッセージを表示し、データの保存を中止します。具体的で分かりやすいエラーメッセージを表示することで、ユーザーが問題を特定しやすくしました。

フロントエンド表示の実装（the_title）

投稿タイトルの前にSVGアイコンを表示するため、the_titleフィルターフックを使用しました。

このフィルターは、タイトルが表示される際に自動的に実行されます。WordPressでは、コンテンツの表示前に様々なフィルターが実行されます。the_titleフィルターにカスタム関数を登録することで、タイトル文字列を変更できます。管理画面では表示を無効にし、投稿タイプがpostの場合のみSVGを追加するよう条件分岐を設けました。

保存されたSVGコードに対して、正規表現を使用してeyecatch-svgクラスを自動的に追加します。既にclass属性がある場合は既存クラスに追加し、ない場合は新規作成するようにしました。特別な設定をせずに、CSSでアイコンのスタイリングができます。

管理画面UIのタブ切り替えに

当初は単純なテキストエリアとプレビュー表示でしたが、より使いやすいインターフェースを目指してタブ切り替え式UIを実装しました。

WordPressの「カスタムHTML」ブロックと同様に、「コード」と「プレビュー」のタブで表示を切り替えられます。コード編集とプレビュー確認を効率よく行えます。CSSでタブボタンの見た目を整え、JavaScriptでタブの切り替え動作を実装しました。アクティブなタブは視覚的に区別され、ホバー効果も追加して操作感を向上させました。

「プレビュー」の表示は、テキストエリアの内容が変更されると、自動的に更新されます。この機能により、コード修正の結果をすぐに確認できます。JavaScriptのaddEventListenerでテキストエリアのinputイベントを監視し、変更を検知すると表示を更新する仕組みです。

完成したプラグインの機能

このプラグインでは、WordPressサイトでSVGアイキャッチアイコンを効率的に管理するために、カスタムフィールドとフィルターフックを組み合わせて実装しました。

最終的に完成したプラグインは、以下の機能を提供します。

投稿編集画面でSVGコードを直接入力でき、タブ切り替えでコードとプレビューを確認できます。
保存されたSVGは投稿詳細ページと一覧ページの両方でタイトル前に表示され、eyecatch-svgクラスが自動付与されるためCSSでのスタイリングが可能です。
セキュリティ面では、SVGコードのサニタイズ、検証機能、XSS攻撃対策を実装し、安全にSVGコンテンツを管理できます。

WordPress プラグイン開発者ハンドブック – WordPressプラグイン開発に関するすべてを網羅した公式ドキュメント
カスタムフィールドの使い方 – WordPress.org公式サポート – WordPressのカスタムフィールド機能に関する公式ガイド
WordPress カスタムフィールドの使い方 – Web Design Leaves – add_meta_box関数とnonce対策を含むカスタムフィールド実装の詳細解説
Safe SVG – WordPress.org公式プラグイン – SVGファイルの安全なアップロードを可能にするプラグインの公式ページ
wp_kses() – Function | Developer.WordPress.org – WordPressのSVGサニタイズ機能に関する公式リファレンス
WordPress フック add_action add_filter – the_titleフィルターフックなどWordPressフックシステムの詳細解説
Gutenbergでメタボックスとカスタムフィールドを追加する方法 – Kinsta – 現代的なWordPress開発におけるメタボックス実装手法