Cuerda-Feed-total Technical Specification

Supported Distribution Keys

実装上の配信先キーは def, ynf, yjt, goo, dcm, spb, snf, gnf, lnr, ldn, isn, ant, trl である。

Bootstrap Sequence

1. cuerda-feed-total.php がプラグインヘッダ、バージョン、主要パス定数を定義する。
2. 同ファイルで plugin_action_links_{plugin_basename} に設定リンクを追加する。
3. includes/admin/class-admin.php、includes/loader.php、includes/init.php の存在確認を行い、欠落時は管理画面通知を出して静かに停止する。
4. 管理画面系ファイルを読み込み、メニュー、設定登録、配信先別設定画面、ライセンス画面を構築する。
5. Cuerda_Loader::init() がプリロード対象クラス、関数ファイル、オートローダを初期化する。
6. includes/loader.php の末尾で init フックに Cuerda_YNF_Publisher::init() を登録する。
7. includes/init.php で do_feed_cuerda_total へコールバックを登録し、カスタムフィード入口を生成する。
8. 有効化・無効化時は、存在する場合に限り Cuerda_Installer::activate() / Cuerda_Installer::deactivate() へ委譲する。

Runtime Components

Primary Execution Flows

Endpoint Model

?feed=cuerda_total&{isp}

公開フィードの基本形。{isp} は GET パラメータの存在で判定される。

?feed=cuerda_total&ynf

例外経路。公開エンドポイントでは YNF XML 自体を返さず、Cuerda_YNF_Info_Endpoint による text/plain の配信結果情報ページを返す。

?feed=cuerda_total&{isp}&delta=1

差分配信モードの要求。実際に有効化するかは cuerda_total_enable_publish_delta フィルタが決める。

?admin=true

公開フィードでは HTML コメント形式の管理用デバッグ情報、YNF 情報エンドポイントでは配信状況の追記情報を出力する。

?cat=true / ?tag=true

管理用デバッグ情報を有効化した場合に、カテゴリ一覧またはタグ一覧を追加出力する。

ISP Matrix

注: ISP ごとの細かな要素差分は includes/rss/feed-config.php に集約され、本文変換差分は includes/rss/content/content-config.php および content-transform-map.php に集約される。

Options and Transients

Cuerda_Options_Helper は、get_option() 結果をリクエスト中キャッシュし、updated_option / added_option / deleted_option でピンポイントに無効化する。

Post Meta

cuerda_revision_status は REST 非公開かつ Custom Fields UI 非表示で扱われる。対して _cuerda_post_exclude_{isp} は Block Editor 連携のため REST 公開される。

Revision Status Shape

配信状態は投稿ごとに JSON として保持される。実装上の形は固定スキーマではなく、total 領域と ISP ごとの領域を浅く持つ連想配列である。

{
  "total": {
    "from": "draft",
    "to": "publish",
    "has_publish": 1,
    "updated": "2026-04-02 12:34:56"
  },
  "lnr": {
    "status": 2,
    "updated": "2026-04-02 12:35:01"
  },
  "ynf": {
    "status": 2,
    "rev": 3,
    "date_id": "20260402",
    "first_created_ts": 1775100000
  }
}

Uninstall Behavior

uninstall.php は、単一サイト・マルチサイトの両方を考慮しながら、cuerda_* 系 option / transient と関連 post meta を削除する。ブランド接頭辞のホワイトリストを使い、削除対象を明示的に絞っている。

Plugin-defined Hooks Fired via do_action() / apply_filters()

Custom Action Hook Names Used for Scheduling or Internal Routing

また、includes/functions-utils.php には cuerda_ynf_build_filenames と cuerda_ynf_should_handle_post に対する既定実装のフィルタ登録が含まれる。

WordPress Core Hooks Subscribed by the Plugin

有効化・無効化フローは register_activation_hook() / register_deactivation_hook() により登録される。

WordPress Core Hooks Consumed via Hook APIs

Global Functions

cuerda_feed_total_init()

定義: includes/init.php

引数: なし / 戻り値: void

役割: do_feed_cuerda_total のコールバックを登録し、Dispatcher を呼び出すカスタムフィード入口を作る。

cuerda_get_distribution_options()

定義: includes/functions-utils.php

引数: なし / 戻り値: array

役割: ISP キーと表示名の正本マップを返す。管理画面、ライセンス画面、フィード確認ボタンが共有利用する。

cuerda_get_general_settings( $code )

定義: includes/functions-utils.php

引数: string $code / 戻り値: array

役割: 設定 UI のラベル、説明、既定値、最小値・最大値などをまとめて返す。

cuerda_get_revision_status_array( $post_id )

定義: includes/functions-utils.php

引数: int $post_id / 戻り値: array

役割: cuerda_revision_status を配列化して返す。旧キー _cuerda_revision_status が残っていれば統合し、主キーへ寄せる。

cuerda_save_revision_status_array( $post_id, array $data )

定義: includes/functions-utils.php

引数: int $post_id, array $data / 戻り値: void

役割: revision 状態配列を JSON 化して保存する。空配列なら関連 meta を削除する。

cuerda_matches_distribution_policy( int $post_id, string $isp )

定義: includes/functions-utils.php

引数: 投稿 ID と ISP キー / 戻り値: bool

役割: 著者、カテゴリ、タグ、投稿 ID の include / exclude 条件を評価し、配信対象可否を判定する。

cuerda_get_status_codes( string $isp )

定義: includes/functions-utils.php

引数: ISP キー / 戻り値: array

役割: revision 状態コードの既定値を返し、cuerda_status_codes フィルタで上書きを許可する。

cuerda_withdraw_on_exclude( string $isp )

定義: includes/functions-utils.php

引数: ISP キー / 戻り値: bool

役割: 投稿除外を delete 相当に変換するかを返す。

cuerda_check_license_status( $isp )

定義: includes/functions-license.php

引数: ISP キー / 戻り値: string

役割: 利用可能なライセンス一覧と比較し、valid または invalid を返す。

cuerda_display_license_status_notice()

定義: includes/functions-license.php

引数: なし / 戻り値: void

役割: ライセンス API の応答状態に応じた管理画面 notice を出力する。

cuerda_output_admin_debug_comment( $isp, $request_uri )

定義: includes/functions-admin-debug.php

引数: ISP キー、リクエスト URI / 戻り値: void

役割: ?admin=true 指定時に、バージョン、リクエスト情報、カテゴリ・タグ一覧、オプション値などをコメントとして埋め込む。

Public Methods

Cuerda_Loader::init()

定義: includes/loader.php

引数: なし / 戻り値: void

役割: プリロード対象クラス、関数ファイル、PSR-4 風オートローダを初期化する。

Cuerda_Feed_API::fetch_controller_data()

定義: includes/admin/class-api.php

引数: なし / 戻り値: array<string,mixed>

役割: cuerda.org のライセンスコントローラ API を読み、短時間 transient にキャッシュする。

Cuerda_Post_Ctrl::init()

定義: includes/admin/class-post-ctrl.php

引数: なし / 戻り値: void

役割: 投稿編集画面の配信除外 UI、REST meta 登録、保存同期を必要時のみ起動する。

Cuerda_Post_Ctrl::is_allowed_for_isp( $post_or_id, $isp )

定義: includes/admin/class-post-ctrl.php

引数: 投稿 ID または WP_Post、ISP キー / 戻り値: bool

役割: 投稿単位の配信除外フラグを評価し、出力可否を返す。

Cuerda_Total_Feed_Dispatcher::dispatch()

定義: includes/rss/class-feed-dispatcher.php

引数: なし / 戻り値: void

役割: ISP 判定、YNF 特例分岐、フィード生成バッファリング、ヘッダ送信、最終 XML 出力を行う。

Cuerda_Total_Feed_Generator_Wrapper::generate()

定義: includes/rss/class-feed-generator-wrapper.php

引数: なし / 戻り値: void

役割: ライセンス判定後、ISP ごとの custom generator または Base Generator へ委譲する。

Cuerda_Total_Feed_Generator_Base::generate()

定義: includes/rss/class-feed-generator-base.php

引数: なし / 戻り値: void

役割: 共通 RSS 骨格、channel / item 出力、管理用デバッグ情報、利用ログ送信を行う。

Cuerda_Feed_Query_Builder::build( $isp_code )

定義: includes/rss/class-feed-query-builder.php

引数: ISP キー / 戻り値: WP_Query

役割: 投稿タイプ、ステータス、author / term / post 条件、差分配信条件を最適化して最終クエリを返す。

Cuerda_Feed_Channel_Renderer::render( $isp, $config )

定義: includes/rss/class-feed-channel-renderer.php

引数: ISP キー、設定配列 / 戻り値: void

役割: channel 要素、ロゴ、日付、description、item 出力の入口を担う。

Cuerda_Feed_Item_Renderer::render( $query, $config, $isp )

定義: includes/rss/class-feed-item-renderer.php

引数: WP_Query、設定配列、ISP キー / 戻り値: void

役割: 各投稿の item 要素を組み立てる。除外トグル、future 扱い、削除通知、カテゴリ、動画、本文、関連記事の判定を含む。

Cuerda_Content_Config::get( $isp )

定義: includes/rss/content/class-content-config.php

引数: ISP キー / 戻り値: array

役割: content-config.php の global と ISP 個別設定をマージして返す。

Cuerda_Content_Processor::process( $html, $isp, $cfg = array(), $post = null )

定義: includes/rss/content/class-content-processor.php

引数: HTML、ISP キー、content 設定、投稿 / 戻り値: string

役割: 本文整形の中心。YouTube 追加、正規表現削除、埋め込み保全、タグ変換、allowed HTML 制御、画像・caption 補正などを一括実行する。

Cuerda_Content_Renderer::render( $post, $config, $isp, $ctx = array() )

定義: includes/rss/content/class-content-renderer.php

引数: 投稿、feed-config、ISP キー、出力コンテキスト / 戻り値: void

役割: the_content フィルタ済み本文または代替テンプレートを取り込み、最終 XML 要素へ出力する。

Cuerda_Feed_Generator_YNF::generate()

定義: includes/rss/class-feed-generator-ynf.php

引数: なし / 戻り値: void

役割: YNF 単票 XML を生成する。公開エンドポイントでは主にプレビューまたは空フィード返却用途で利用される。

Cuerda_Feed_Generator_YNF::build_single_post_xml( $post_id, $args = array() )

定義: includes/rss/class-feed-generator-ynf.php

引数: 投稿 ID、追加引数 / 戻り値: string

役割: YNF Publisher から再利用される単票 XML ビルダ。

Cuerda_YNF_Publisher::init()

定義: includes/ynf/class-ynf-publisher.php

引数: なし / 戻り値: void

役割: YNF 向けカスタムフック、コアフック、日次デバッグログクリアのスケジュールを登録する。

Important Internal Workflows

Cuerda_YNF_Publisher::maybe_handle_transition( $new, $old, $post )

主要トリガ: transition_post_status

役割: YNF 配信可否、delete 判定、republish-as-new、ロック、クールダウン、ハッシュ比較、FTP PUT 実行までを統括する中核処理。

Cuerda_YNF_Publisher::build_xml_for_post( $post_id, array $args )

役割: まず cuerda_ynf_build_xml_for_post フィルタを評価し、未提供なら Cuerda_Feed_Generator_YNF::build_single_post_xml() を呼ぶ。

Cuerda_YNF_Publisher::build_filenames( ... )

役割: DateId、MediaId、NewsItemId、Revision を基にファイル名を作り、cuerda_ynf_build_filenames で上書きを許可する。

Cuerda_YNF_Publisher::ftp_put_all( array $args )

役割: FTP/FTPS 接続、認証、パッシブモード化、画像 PUT、XML PUT を順番に実行する。

Cuerda_Feed_Query_Builder::maybe_apply_publish_delta_filters()

役割: ?delta=1 などの要求を解釈し、_cuerda_total_touched_ts と publish / demoted 条件に基づく差分抽出へ切り替える。

License and Telemetry

HTTP 通信は wp_remote_get() を使用し、ライセンス API の失敗時は fail-safe / fallback 挙動を持つ。ユーザーは cuerda_total_optout_log により利用ログ送信を抑止できる。

FTP / FTPS for YNF

YNF は、一般の公開フィードとは別に FTP または FTPS による push 配信を行う。接続先は cuerda_ynf_ftp_server, cuerda_ynf_ftp_user_name, cuerda_ynf_ftp_password, cuerda_ynf_ftp_remote_dir, cuerda_ynf_ftp_port, cuerda_ynf_ftp_secure で管理される。

パスワードは復号ヘルパー cuerda_decrypt_password() または cuerda_decrypt_value() を通じて取り扱われる。

WP-Cron

YNF では WP-Cron を二段階で利用する。ひとつは新規公開直後のデバウンス送信、もうひとつは日次のデバッグログクリアである。

WP-CLI

WP-CLI 環境では以下のコマンドが登録される。

• wp cuerda validate-feed: 公開フィードの XML 妥当性検査
• wp cuerda ynf-related: YNF 関連リンクブロックの検査
• wp cuerda ynf-scan: 複数投稿の YNF 関連リンクルール検査
• wp cuerda post-ctrl: 投稿単位の配信除外状態の確認・補助

Theme / Template Override

本文生成はテーマ側の代替テンプレート出力を取り込める設計であり、Cuerda_Content_Processor::get_alternate_template_output() が入口となる。これにより、WordPress テーマ側で本文の供給元を差し替えられる。

Bootstrap and Feed Fail-soft Behavior

Developer-facing Debug Features

• ?admin=true でフィードへ管理情報を追記できる。
• ?cat=true と ?tag=true でカテゴリ / タグ一覧を出力できる。
• YNF 情報エンドポイントは接続設定、done ディレクトリ、ログ状態を確認するための text/plain 画面を提供する。
• cuerda_ynf_debug_info と cuerda_ynf_result_info に配信ログを保持する。
• WP-CLI バリデータにより XML 整形式や YNF 関連リンク仕様を検査できる。

Operational Safeguards

• YNF には lock、cooldown、activity guard、XML hash 正規化による冪等性制御がある。
• 差分配信では _cuerda_total_touched_ts と _cuerda_total_demoted により削除系の取りこぼしを抑える。
• 内部 meta は REST 非公開または protected 扱いにして誤編集を避ける。

Appendix A: Class Index

以下は主要クラスの索引である。本文に詳細がないものも、クラス名と所在ファイルの対応をここで追跡する。

• Cuerda_Loader - includes/loader.php
• Cuerda_Options_Helper - includes/helpers/class-options-helper.php
• Cuerda_CLI_Validators - includes/cli/class-cli-validators.php
• Cuerda_Feed_Admin - includes/admin/class-admin.php
• Cuerda_Feed_Admin_Settings - includes/admin/class-admin-settings.php
• Cuerda_Feed_Admin_Distribution - includes/admin/class-admin-distribution.php
• Cuerda_Feed_Admin_License - includes/admin/class-admin-license.php
• Cuerda_Feed_Admin_Options - includes/admin/class-admin-options.php
• Cuerda_Feed_Admin_Mapping - includes/admin/class-admin-mapping.php
• Cuerda_Feed_API - includes/admin/class-api.php
• Cuerda_Post_Ctrl - includes/admin/class-post-ctrl.php
• Cuerda_Total_Feed_Dispatcher - includes/rss/class-feed-dispatcher.php
• Cuerda_Total_Feed_Generator_Wrapper - includes/rss/class-feed-generator-wrapper.php
• Cuerda_Total_Feed_Generator_Base - includes/rss/class-feed-generator-base.php
• Cuerda_Feed_Generator_YNF - includes/rss/class-feed-generator-ynf.php
• Cuerda_Feed_Query_Builder - includes/rss/class-feed-query-builder.php
• Cuerda_Feed_Channel_Renderer - includes/rss/class-feed-channel-renderer.php
• Cuerda_Feed_Item_Renderer - includes/rss/class-feed-item-renderer.php
• Cuerda_Content_Config - includes/rss/content/class-content-config.php
• Cuerda_Content_Renderer - includes/rss/content/class-content-renderer.php
• Cuerda_Content_Processor - includes/rss/content/class-content-processor.php
• Cuerda_Content_Pipeline - includes/rss/content/class-content-pipeline.php
• Cuerda_Content_Steps - includes/rss/content/class-content-steps.php
• Cuerda_Content_Embeds - includes/rss/content/content-embeds.php
• Cuerda_YNF_Publisher - includes/ynf/class-ynf-publisher.php
• Cuerda_YNF_Info_Endpoint - includes/ynf/class-ynf-info-endpoint.php

Appendix B: Global Function Index

本文に詳細を載せない関数群は、ファイル単位の索引として追跡する。