Back to Details

code-style

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ActivityPub PHP Conventions

ActivityPub PHP 开发规范

Plugin-specific conventions and architectural patterns for the ActivityPub plugin.
针对ActivityPub插件的专属规范和架构模式。

Quick Reference

快速参考

File Naming

文件命名

class-{name}.php         # Regular classes.
trait-{name}.php         # Traits.
interface-{name}.php     # Interfaces.
class-{name}.php         # 普通类文件
trait-{name}.php         # Trait文件
interface-{name}.php     # 接口文件

Namespace Pattern

命名空间规则

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

Text Domain

文本域

Always use 
'activitypub'
for translations:
php
\__( 'Text', 'activitypub' );
\_e( 'Text', 'activitypub' );
翻译时始终使用
'activitypub'
作为文本域：
php
\__( 'Text', 'activitypub' );
\_e( 'Text', 'activitypub' );

WordPress Global Functions

WordPress全局函数

When in a namespace, always escape WordPress functions with backslash: 
\get_option()
, 
\add_action()
, etc.
在命名空间内使用WordPress函数时，始终需要加反斜杠转义，例如
\get_option()
、
\add_action()
等。

Comprehensive Standards

完整规范

See 
docs/php-coding-standards.md
for complete WordPress coding standards.
See 
docs/php-class-structure.md
for detailed directory organization.
完整的WordPress编码规范请查看
docs/php-coding-standards.md
。
详细的目录组织结构请查看
docs/php-class-structure.md
。

Directory Structure

目录结构

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).
includes/
├── class-*.php              # 核心类文件
├── activity/                # 活动类型类目录
├── collection/              # 集合类目录
├── handler/                 # 活动处理器目录
├── rest/                    # REST API端点目录
├── transformer/             # 内容转换器目录
└── wp-admin/                # 管理后台功能目录

integration/                 # 第三方集成目录（根层级）

ActivityPub Architectural Patterns

ActivityPub 架构模式

Transformers

转换器（Transformers）

Convert WordPress content into ActivityPub objects.
When to use: Converting posts, comments, users, or custom content types into ActivityPub format.
Base class: 
includes/transformer/class-base.php
Pattern:
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;
    }
}
Examples:
  • includes/transformer/class-post.php
    - Post transformation.
  • includes/transformer/class-comment.php
    - Comment transformation.
  • includes/transformer/class-event.php
    - Event-specific transformation.
将WordPress内容转换为ActivityPub对象。
适用场景： 将文章、评论、用户或自定义内容类型转换为ActivityPub格式。
基类： 
includes/transformer/class-base.php
模式示例：
php
namespace Activitypub\Transformer;

class Custom extends Base {
    /**
     * 将对象转换为ActivityPub格式
     *
     * @return array ActivityPub格式的表示
     */
    public function transform() {
        $object = parent::transform();
        // 自定义转换逻辑
        return $object;
    }
}
示例：
  • includes/transformer/class-post.php
    - 文章转换逻辑
  • includes/transformer/class-comment.php
    - 评论转换逻辑
  • includes/transformer/class-event.php
    - 活动专属转换逻辑

Handlers

处理器（Handlers）

Process incoming ActivityPub activities from remote servers.
When to use: Processing incoming Follow, Like, Create, Delete, Update, etc. activities.
Pattern: Each handler processes one activity type from the inbox.
Examples:
  • includes/handler/class-follow.php
    - Process Follow activities.
  • includes/handler/class-create.php
    - Process Create activities.
  • includes/handler/class-delete.php
    - Process Delete activities.
  • includes/handler/class-like.php
    - Process Like activities.
处理来自远程服务器的传入ActivityPub活动。
适用场景： 处理传入的Follow、Like、Create、Delete、Update等类型的活动。
模式： 每个处理器对应处理收件箱中的一种活动类型。
示例：
  • includes/handler/class-follow.php
    - 处理Follow活动
  • includes/handler/class-create.php
    - 处理Create活动
  • includes/handler/class-delete.php
    - 处理Delete活动
  • includes/handler/class-like.php
    - 处理Like活动

Collections

集合（Collections）

Implement ActivityPub collections (Followers, Following, etc.).
When to use: Exposing lists of actors, activities, or objects via ActivityPub.
Examples:
  • includes/collection/class-followers.php
    - Followers collection.
  • includes/collection/class-following.php
    - Following collection.
实现ActivityPub集合（粉丝列表、关注列表等）。
适用场景： 通过ActivityPub对外暴露账号、活动或对象列表。
示例：
  • includes/collection/class-followers.php
    - 粉丝集合
  • includes/collection/class-following.php
    - 关注列表集合

REST API Controllers

REST API 控制器

Expose ActivityPub endpoints.
Namespace: 
ACTIVITYPUB_REST_NAMESPACE
Examples:
  • includes/rest/class-actors-controller.php
    - Actor endpoint.
  • includes/rest/class-inbox-controller.php
    - Inbox endpoint.
  • includes/rest/class-outbox-controller.php
    - Outbox endpoint.
  • includes/rest/class-followers-controller.php
    - Followers collection endpoint.
对外暴露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
    - 粉丝集合端点

Plugin-Specific Helper Functions

插件专属辅助函数

php
// 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 );

// Get user's ActivityPub actor URL.
$actor_url = get_author_posts_url( $user_id );

// Check if a post type is enabled for ActivityPub.
$enabled = \is_post_type_enabled( $post_type );
php
// 获取远程账号元数据
$metadata = get_remote_metadata_by_actor( $actor_url );

// 将ActivityPub对象转换为URI字符串
$uri = object_to_uri( $object );

// 通过回调丰富内容数据
$content = enrich_content_data( $content, $pattern, $callback );

// 将WebFinger句柄解析为账号URL
$resource = Webfinger::resolve( $handle );

// 获取用户的ActivityPub账号URL
$actor_url = get_author_posts_url( $user_id );

// 检查某篇文章类型是否启用了ActivityPub支持
$enabled = \is_post_type_enabled( $post_type );

Real Codebase Examples

实际代码库示例

Core Classes:
  • includes/class-activitypub.php
    - Main plugin initialization.
  • includes/class-dispatcher.php
    - Activity dispatching to followers.
  • includes/class-scheduler.php
    - WP-Cron integration for async tasks.
  • includes/class-signature.php
    - HTTP Signatures for federation.
Activity Types:
  • includes/activity/class-activity.php
    - Base activity class.
  • includes/activity/class-follow.php
    - Follow activity.
  • includes/activity/class-undo.php
    - Undo activity.
Integrations (see Integration Patterns):
  • integration/class-woocommerce.php
    - WooCommerce integration.
  • integration/class-buddypress.php
    - BuddyPress integration.
  • integration/class-jetpack.php
    - Jetpack integration.
核心类：
  • includes/class-activitypub.php
    - 插件主初始化逻辑
  • includes/class-dispatcher.php
    - 向粉丝分发活动的逻辑
  • includes/class-scheduler.php
    - 对接WP-Cron实现异步任务
  • includes/class-signature.php
    - 用于联邦通信的HTTP签名逻辑
活动类型：
  • includes/activity/class-activity.php
    - 活动基类
  • includes/activity/class-follow.php
    - 关注活动
  • includes/activity/class-undo.php
    - 撤销活动
集成（参见 集成模式）：
  • integration/class-woocommerce.php
    - WooCommerce集成
  • integration/class-buddypress.php
    - BuddyPress集成
  • integration/class-jetpack.php
    - Jetpack集成

Common Initialization Patterns

通用初始化模式

Static Initialization

静态初始化

php
class Feature {
    /**
     * Initialize the class.
     */
    public static function init() {
        \add_action( 'init', array( self::class, 'register' ) );
        \add_filter( 'activitypub_activity_object', array( self::class, 'filter' ) );
    }
}
php
class Feature {
    /**
     * 初始化类
     */
    public static function init() {
        \add_action( 'init', array( self::class, 'register' ) );
        \add_filter( 'activitypub_activity_object', array( self::class, 'filter' ) );
    }
}

Singleton Pattern

单例模式

php
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();
    }
}
php
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();
    }
}

Custom Hook Patterns

自定义钩子模式

Actions:
php
\do_action( 'activitypub_before_send_activity', $activity );
\do_action( 'activitypub_after_send_activity', $activity, $response );
\do_action( 'activitypub_inbox_received', $activity );
Filters:
php
$activity = \apply_filters( 'activitypub_activity_object', $activity, $post );
$content = \apply_filters( 'activitypub_the_content', $content, $post );
$actor = \apply_filters( 'activitypub_actor_data', $actor, $user_id );
动作钩子：
php
\do_action( 'activitypub_before_send_activity', $activity );
\do_action( 'activitypub_after_send_activity', $activity, $response );
\do_action( 'activitypub_inbox_received', $activity );
过滤器钩子：
php
$activity = \apply_filters( 'activitypub_activity_object', $activity, $post );
$content = \apply_filters( 'activitypub_the_content', $content, $post );
$actor = \apply_filters( 'activitypub_actor_data', $actor, $user_id );

Version Numbers

版本号规范

Always use 
'unreleased'
 for version strings in new code. The release script automatically replaces these with the actual version number during the release process.
PHPDoc tags:
php
/**
 * New function description.
 *
 * @since unreleased
 */
function new_feature() {}

/**
 * Old function.
 *
 * @deprecated unreleased Use new_feature() instead.
 */
function old_feature() {}
Deprecation functions:
php
\_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' );
Never hardcode version numbers like 
'5.1.0'
— always use 
'unreleased'
.
新代码中的版本号字符串必须始终使用
'unreleased'
，发布脚本会在发布流程中自动将其替换为实际的版本号。
PHPDoc 标签：
php
/**
 * 新功能函数说明
 *
 * @since unreleased
 */
function new_feature() {}

/**
 * 旧函数
 *
 * @deprecated unreleased 请使用new_feature()替代
 */
function old_feature() {}
弃用相关函数：
php
\_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'
。