integrations

ActivityPub 集成

本技能提供了将 ActivityPub 插件与其他 WordPress 插件集成的指导。

快速参考

集成位置

所有集成都位于 integration/ 目录中。

文件命名： class-{plugin-name}.php（遵循 AGENTS.md 中的 PHP 约定）

命名空间： Activitypub\Integration

集成如何加载

在 integration/load.php 的 plugin_init() 中注册集成。每个集成都由检测条件保护，然后调用其类的静态 init() 方法：

// integration/load.php
if ( \defined( 'JETPACK__VERSION' ) ) {
    Jetpack::init();
}

现有集成

当前实际发布的集成（参见 integration/）：

akismet、buddypress、classic-editor、enable-mastodon-apps、jetpack、 litespeed-cache、multisite-language-switcher、nodeinfo、opengraph、 podlove-podcast-publisher、seriously-simple-podcasting、surge、webfinger、 wpml、yoast-seo。

一些示例：

• Akismet — 使用 Akismet 垃圾内容检查处理传入的评论和互动。
• OpenGraph — 通过 OpenGraph 插件添加 fediverse:creator 及相关元数据。
• Enable Mastodon Apps — 允许 Mastodon 客户端应用与站点通信。
• 缓存（LiteSpeed Cache、Surge） — 确保 ActivityPub 响应能够正确缓存或不被缓存。
• 多语言（WPML、Multisite Language Switcher） — 支持语言感知的角色和内容处理。

完整的目录结构和命名约定，请参见 docs/php-class-structure.md。

创建新集成

基本集成类

<?php
namespace Activitypub\Integration;

class Plugin_Name {
    /**
     * Initialize the class, registering WordPress hooks.
     */
    public static function init() {
        // Enable federation for the plugin's post type.
        \add_post_type_support( 'plugin_post_type', 'activitypub' );

        // Provide a custom transformer if the default Post transformer is not enough.
        \add_filter( 'activitypub_transformer', array( self::class, 'transformer' ), 10, 3 );
    }

    /**
     * Return a custom transformer for the plugin's objects.
     *
     * @param mixed  $transformer  The transformer to use. Default null.
     * @param mixed  $data         The object to transform.
     * @param string $object_class The class of the object to transform.
     * @return mixed
     */
    public static function transformer( $transformer, $data, $object_class ) {
        if ( 'WP_Post' === $object_class && 'plugin_post_type' === $data->post_type ) {
            require_once __DIR__ . '/class-custom-transformer.php';
            return new Custom_Transformer( $data );
        }
        return $transformer;
    }
}

然后在 integration/load.php 中注册：

if ( \defined( 'PLUGIN_VERSION' ) ) {
    Plugin_Name::init();
}

集成模式

为文章类型启用联邦

文章类型支持决定哪些内容会进行联邦发布。使用 add_post_type_support() — 没有 activitypub_post_types 过滤器：

\add_post_type_support( 'event', 'activitypub' );
\add_post_type_support( 'product', 'activitypub' );

已启用的文章类型存储在 activitypub_support_post_types 选项中（使用 \get_option( 'activitypub_support_post_types', array( 'post' ) ) 读取）。

自定义转换器

activitypub_transformer 过滤器接受 三个 参数 — ( $transformer, $data, $object_class ) — 并以优先级 10, 3 注册：

\add_filter( 'activitypub_transformer', function ( $transformer, $data, $object_class ) {
    if ( 'WP_Post' === $object_class && 'event' === $data->post_type ) {
        return new Event_Transformer( $data );
    }
    return $transformer;
}, 10, 3 );

修改 Activity 对象

要调整最终的 ActivityStreams 数组，请挂接 activitypub_activity_object_array — ( $array, $class, $id, $object )：

\add_filter( 'activitypub_activity_object_array', function ( $array, $class, $id, $object ) {
    if ( isset( $array['type'] ) && 'Note' === $array['type'] ) {
        // Adjust the outgoing object array here.
    }
    return $array;
}, 10, 4 );

测试集成

验证集成加载情况

// Check if integration is active.
if ( \class_exists( '\Activitypub\Integration\Plugin_Name' ) ) {
    // Integration loaded.
}

测试兼容性

1. 安装目标插件
2. 启用 ActivityPub
3. 检查是否存在冲突
4. 验证自定义文章类型是否进行联邦发布
5. 测试插件内容的联邦发布

常见集成问题

插件检测

// Multiple detection methods (match how integration/load.php guards each one).
if ( \defined( 'PLUGIN_VERSION' ) ) { }
if ( \function_exists( 'plugin_function' ) ) { }
if ( \class_exists( 'Plugin_Class' ) ) { }

钩子优先级

// Use appropriate priority.
\add_filter( 'hook', 'callback', 20 ); // After plugin's filter.

命名空间冲突

// Use fully qualified names.
$object = new \Plugin\Namespace\Class();

最佳实践

1. 始终先在 integration/load.php 中通过检测条件保护集成，再调用 init()。
2. 需要覆盖其他插件的默认设置时，为过滤器使用较晚的优先级。
3. 使用多个插件版本进行测试。
4. 记录兼容性要求。
5. 妥善处理插件停用的情况。