Write a specialized ActivityPub transformer for an Event-Custom-Post-Type

NOTE: This documentation is also likely to be useful for content types other than events.

The ActivityPub plugin offers a basic support for all post types out of the box, but it also allows the registration of external transformers. A transformer is a class that implements the abstract transformer class and is responsible for generating the ActivityPub JSON representation of an WordPress post or comment object.

How it works

To make the WordPress ActivityPub plugin use a custom transformer simply add a filter to the activitypub_transformer hook which provides access to the transformer factory. The transformer factory determines which transformer is used to transform a WordPress object to ActivityPub. We provide a parent event transformer, that comes with common tasks needed for events. Furthermore, we provide admin notices, to prevent users from misconfiguration issues.

Add your event plugin

First you need to add some basic information about your event plugin in the constant SUPPORTED_EVENT_PLUGIN in the file includes/class-setup.php:

    // Example from the Events Manager plugin.
    'events_manager' => array( // Choose any key you like.
        'plugin_file'       => 'events-manager/events-manager.php',
        'post_type'         => 'event',
        'settings_page'     => 'options-general.php?page=vsel',
        'transformer_class' => 'Events_Manager', // Points to the class in the file `includes/activitypub/transformer/class-events-manager.php`.
    ),

The Plugin takes care of applying the transformer, so you can jump right into implementing it.

Writing an event transformer class

If you are writing a transformer for a custom post type it is recommended to start by extending the provided event transformer. It is an extension of the default generic post transformer and inherits useful default implementations for generating the attachments, rendering a proper content in HTML from either blocks or the classic editor, extracting tags and more.

namespace Activitypub_Event_Extensions\Activitypub\Transformer;

/**
 * ActivityPub Transformer for my_event_post_type.
 */
class My_Event_Post_Type_Transformer extends Event; {

The main function which controls the transformation is to_object. This one is called by the ActivityPub plugin to get the resulting ActivityPub representation as an PHP-array. The conversion to JSON-LD takes place later, and you don't need to cover that. You might just want to start by applying the parent function, but the chances are high, you don't even need to extend this functions functionality.

/**
  * Transform the WordPress Object into an ActivityPub Event Object.
  *
  * @return Activitypub\Activity\Extended_Object\Event
  */
public function to_object() {
  $activitypub_object = parent::to_object();
  // ... your additions.
  return $activitypub_object;
}

The ActivityPub object classes contain dynamic getter and setter functions: set_<property-name> and get_<property-name>. Of course, the property with property-name must exist for these to work. The function transform_object_properties tries to set all properties known to the ActivityPub object where a function called get_<property-name> exists in the current transformer class.

How to add new properties

Adding new properties is not encouraged to do at the transformer level. It's recommended to create a proper target ActivityPub object first. The target ActivityPub object also controls the JSON-LD context via the constant JSON_LD_CONTEXT. Example.

Properties

NOTE: Within PHP all properties are snake_case, they will be transformed to the according CamelCase by the ActivityPub plugin. So if to you set start_time by using the ActivityPub objects class function set_start_time or implementing a getter function in the transformer class called get_start_time the property startTime will be set accordingly in the JSON representation of the resulting ActivityPub object.

You can find all available event related properties in the event class along documentation and with links to the specifications.

Mandatory Properties for an Event

In order to ensure your events are compatible with other ActivityPub Event implementations there are several required properties that must be set by your transformer.

type: if using the Activitypub\Activity\Extended_Object\Event class the type will default to Event without doing anything.
startTime: the events start time
name: the title of the event

Recommended properties for an Event in order to achieve good interoperability with other ActivityPub platforms

summary: Other ActivityPub platforms that don't natively support event should use the summary (and the name) to display it as a converted object type. For example Mastodon converts an Event object to a Note. It is recommended to write the summary as text-centered with minimal HTML markup and that it contains the most important event details like place, time, etc.
isOnline:

6 KiB Raw Permalink Blame History