code-style

ActivityPub PHP 規約

ActivityPub プラグイン固有の規約とアーキテクチャパターンです。

最初のルール：書く前に再利用する。 新しい実装を追加するよりも、WordPress コア関数、次に既存のプラグインヘルパー（includes/functions*.php、Sanitize、src/shared/）を優先してください。また、コア関数を使ったチェックを独自ロジックに置き換えてはいけません。docs/php-coding-standards.md の「まずコア機能を再利用する」を参照してください。

クイックリファレンス

ファイル名

class-{name}.php         # Regular classes.
trait-{name}.php         # Traits.
interface-{name}.php     # Interfaces.

名前空間のパターン

namespace Activitypub;
namespace Activitypub\Transformer;
namespace Activitypub\Collection;
namespace Activitypub\Handler;
namespace Activitypub\Activity;
namespace Activitypub\Rest;

テキストドメイン

翻訳には常に 'activitypub' を使用してください：

\__( 'Text', 'activitypub' );
\_e( 'Text', 'activitypub' );

WordPress グローバル関数

名前空間内では、WordPress 関数の前に必ずバックスラッシュを付けてください：\get_option()、\add_action() など。

インポートとクラス参照

対称的なルールが2つあり、どちらもレビューで確認されます：

// Plugin classes: import with `use`, never reference inline.
use Activitypub\Collection\Outbox;

Outbox::add( $activity );          // ✅
\Activitypub\Collection\Outbox::add( $activity ); // ❌ no inline namespaces

// Global (WordPress/PHP) classes: reference inline with a backslash, never import.
$query = new \WP_Query( $args );   // ✅
class Command extends \WP_CLI_Command {} // ✅
use WP_Query;                      // ❌ no `use` for global classes

コメント

• 複数行のコメントには /* */、1行のコメントには // を使用してください。// を行ごとに連ねる形式は使わないでください。
• コメントはコードブロックの上にまとめて置くのではなく、説明する行に付けてください。詳しく説明してもかまいませんが、文ごとに分けてください。
• 行が必要になる、ひと目では分からない仕組みを説明してください。背後にあるバグやチケットについて説明してはいけません。見れば分かる行にはコメントを付けないでください。

プラグインの慣例

• try／catch や try／finally は使わないでください。呼び出しの前後でフィルターを add_filter → 呼び出し → remove_filter の順に設定し、失敗は戻り値（WP_Error、false）で報告してください。
• 識別子、ファイル名、コードコメントに「C2S」を使わないでください。正式名称は「ActivityPub API」で、利用側を指す場合は「client」でかまいません。
• サーバー外に出るもの（REST レスポンス、配信）には $activity->to_array( false, false ) を使用してください。各項目に @context を含めず、bto／bcc も含めません。保存時は往復変換できるように to_array( true, true ) を維持してください。
• 2か所の呼び出し元に数行重複するほうが、新しいヘルパーを追加するより適切です。一方、兄弟クラス間でメソッド本体全体を重複させてはいけません。

包括的な規約

WordPress のコーディング規約の全容は docs/php-coding-standards.md を参照してください。

ディレクトリ構成の詳細は docs/php-class-structure.md を参照してください。

ディレクトリ構成

includes/
├── class-*.php              # Core classes.
├── activity/                # Activity type classes.
├── collection/              # Collection classes.
├── handler/                 # Activity handlers.
├── rest/                    # REST API endpoints.
├── transformer/             # Content transformers.
└── wp-admin/                # Admin functionality.

integration/                 # Third-party integrations (root level).

ActivityPub のアーキテクチャパターン

トランスフォーマー

WordPress コンテンツを ActivityPub オブジェクトに変換します。

使用する場面： 投稿、コメント、ユーザー、またはカスタムコンテンツタイプを ActivityPub 形式に変換するとき。

基底クラス： includes/transformer/class-base.php

パターン：

namespace Activitypub\Transformer;

class Custom extends Base {
    /**
     * Transform object to ActivityPub format.
     *
     * @return array The ActivityPub representation.
     */
    public function transform() {
        $object = parent::transform();
        // Custom transformation logic.
        return $object;
    }
}

例：

• includes/transformer/class-post.php - 投稿の変換。
• includes/transformer/class-comment.php - コメントの変換。
• includes/transformer/class-user.php - ユーザー／アクターの変換。

ハンドラー

リモートサーバーから受信した ActivityPub アクティビティを処理します。

使用する場面： Follow、Like、Create、Delete、Update などのアクティビティを処理するとき。

パターン： 各ハンドラーは、受信トレイから1種類のアクティビティを処理します。

例：

• includes/handler/class-follow.php - Follow アクティビティを処理。
• includes/handler/class-create.php - Create アクティビティを処理。
• includes/handler/class-delete.php - Delete アクティビティを処理。
• includes/handler/class-like.php - Like アクティビティを処理。

コレクション

ActivityPub のコレクション（Followers、Following など）を実装します。

使用する場面： ActivityPub を通じて、アクター、アクティビティ、オブジェクトの一覧を公開するとき。

例：

• includes/collection/class-followers.php - Followers コレクション。
• includes/collection/class-following.php - Following コレクション。

REST API コントローラー

ActivityPub エンドポイントを公開します。

名前空間： ACTIVITYPUB_REST_NAMESPACE

例：

• includes/rest/class-actors-controller.php - アクターエンドポイント。
• includes/rest/class-inbox-controller.php - 受信トレイエンドポイント。
• includes/rest/class-outbox-controller.php - 送信トレイエンドポイント。
• includes/rest/class-followers-controller.php - Followers コレクションエンドポイント。

プラグイン固有のヘルパー関数

// Get remote actor metadata.
$metadata = get_remote_metadata_by_actor( $actor_url );

// Convert ActivityPub object to URI string.
$uri = object_to_uri( $object );

// Enrich content with callbacks.
$content = enrich_content_data( $content, $pattern, $callback );

// Resolve WebFinger handle to actor URL.
$resource = Webfinger::resolve( $handle );

// Check whether a post is disabled for ActivityPub (the federation pipeline gate).
$disabled = is_post_disabled( $post );

実際のコードベースの例

主要なクラス：

• includes/class-activitypub.php - プラグインのメイン初期化。
• includes/class-dispatcher.php - フォロワーへのアクティビティのディスパッチ。
• includes/class-scheduler.php - 非同期タスク向けの WP-Cron 連携。
• includes/class-signature.php - フェデレーション向けの HTTP 署名。

アクティビティの種類：

• includes/activity/class-activity.php - アクティビティクラス（Create、Follow、Undo などは、このクラスから構築されます）。
• includes/activity/class-base-object.php - オブジェクトの基底クラス。
• includes/activity/extended-object/ - 拡張オブジェクトの種類（例：Event）。

連携（連携パターンを参照）：

• integration/class-buddypress.php - BuddyPress 連携。
• integration/class-jetpack.php - Jetpack 連携。
• integration/class-opengraph.php - OpenGraph 連携。

一般的な初期化パターン

静的初期化

class Feature {
    /**
     * Initialize the class.
     */
    public static function init() {
        \add_action( 'init', array( self::class, 'register' ) );
        \add_filter( 'activitypub_the_content', array( self::class, 'filter' ) );
    }
}

シングルトンパターン

class Manager {
    private static $instance = null;

    public static function get_instance() {
        if ( null === self::$instance ) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {
        $this->init();
    }
}

カスタムフックのパターン

アクション：

\do_action( 'activitypub_handled_create', $activity, $user_ids, $success, $result );
\do_action( 'activitypub_followers_pre_remove_follower', $follower, $user_id, $actor );

フィルター：

$array   = \apply_filters( 'activitypub_activity_object_array', $array, $class, $id, $object );
$content = \apply_filters( 'activitypub_the_content', $content, $post );
$types   = \apply_filters( 'activitypub_actor_types', $types );

バージョン番号

新しいコードのバージョン文字列には、必ず 'unreleased' を使用してください。 リリーススクリプトは、リリースプロセス中にこれらを実際のバージョン番号に自動的に置き換えます。

PHPDoc タグ：

/**
 * New function description.
 *
 * @since unreleased
 */
function new_feature() {}

/**
 * Old function.
 *
 * @deprecated unreleased Use new_feature() instead.
 */
function old_feature() {}

非推奨化関数：

\_deprecated_function( __METHOD__, 'unreleased', 'New_Class::new_method' );
\_deprecated_argument( __METHOD__, 'unreleased', \esc_html__( 'Message', 'activitypub' ) );
\_doing_it_wrong( __METHOD__, \esc_html__( 'Message', 'activitypub' ), 'unreleased' );

'5.1.0' のようなバージョン番号をハードコードしないでください。 必ず 'unreleased' を使用してください。