Introduction

About this extension

fp_social_bridge is a lean library extension. It provides the data-transfer and response objects exchanged between the fixpunkt social server and TYPO3. The protocol (currently version 2) is encapsulated as typed PHP objects and is used, among others, by fp_social.

The extension deliberately contains no business logic of its own, no TCA and no plugins – only the shared classes, so that the server and client side use the same format.

Included classes

Class	Purpose
`SerializableInterface`	Contract: `fromJson()`, `fromArray()`, `toArray()`
`v2\Data\Post`	A single post (id, headline, message, url, date, hashtags, mentions, pictures)
`v2\Data\Posts`	Iterable, countable collection of `Post` objects
`v2\Response\SocialServerResponse`	Abstract base incl. version check and the `fromJson()` factory
`v2\Response\SocialServerPostResponse`	Response containing a single post
`v2\Response\SocialServerPostsResponse`	Response containing multiple posts + pagination (`previousPage`/`nextPage`)
`v2\Response\SocialServerErrorResponse`	Error response (code with prefix `5550`, message)

Installation

The extension is installed via Composer:

composer require fixpunkt/fp-social-bridge

Requirements

Component	Version
TYPO3	12.4 – 14.3
PHP	8.4 – 8.5

Usage

This extension describes the protocol between the fixpunkt social server (server side) and a TYPO3 instance such as fp_social (client side). Both sides use the same classes, so that creation and evaluation are guaranteed to use the same format.

Request flow

The client side (e.g. fp_social) requests posts from the social server.
The social server gathers the data and creates a response object. Which of the three types is created depends on the result:
- a single post → SocialServerPostResponse
- multiple posts (with pagination) → SocialServerPostsResponse
- an error → SocialServerErrorResponse
The server serializes the object via toArray() and json_encode() and sends the JSON to the client.
The client passes the JSON to the factory SocialServerResponse::fromJson() and receives the matching, typed object back.

Every response carries the fully qualified class name in the type field and the protocol version (currently 2) in the version field. Based on these two fields the factory decides which object to reconstruct and checks version compatibility.

Note

All of the following examples use anonymized sample data (example.com, fictional IDs). The format matches that of real responses.

Structure of a post object

Before we get to the responses, it is worth looking at the JSON of a single Post, since some fields have a particular format here:

Field	Format
`headline`	Headline. Empty (`""`) for many sources (e.g. Facebook).
`message`	HTML text. May contain `<br />` and `<a>` tags as well as emoji placeholders of the form `{emoji:9728}` (Unicode code point).
`update_time`	Serialized `\DateTime` object with the keys `date`, `timezone_type` and `timezone`.
`hashtags`	List of strings without a leading `#` (e.g. `"summer"`).
`mentions`	List of objects with `displayName` and `systemName`; empty when there are no mentions.
`pictures`	List of picture URLs.

Example 1: A single post (SocialServerPostResponse)

Server side – create and output as JSON:

use Fixpunkt\FpSocialBridge\v2\Data\Post;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$post = new Post(
    id: '100000000000001_200000000000001',
    headline: '',
    message: 'Summertime! Here is our favourite recipe for hot days.<br />'
        . "\n" . 'Have fun trying it out {emoji:9728} '
        . '<a href=\'https://social.example.com/hashtag/recipe\'>#recipe</a>',
    post_url: 'https://social.example.com/100000000000001/posts/200000000000001',
    update_time: new \DateTime('2026-06-27 08:00:38+00:00'),
    link: 'https://social.example.com/100000000000001/posts/200000000000001',
    hashtags: ['recipe', 'summer', 'drinks', 'tip'],
    mentions: [],
    pictures: ['https://cdn.example.com/media/image-1.jpg'],
);

$response = new SocialServerPostResponse(SocialServerResponse::version, $post);

echo json_encode($response->toArray());

The resulting JSON (values shortened):

{
    "type": "Fixpunkt\\FpSocialBridge\\v2\\Response\\SocialServerPostResponse",
    "version": 2,
    "post": {
        "id": "100000000000001_200000000000001",
        "headline": "",
        "message": "Summertime! ...<br />\n... <a href='...'>#recipe</a>",
        "post_url": "https://social.example.com/100000000000001/posts/200000000000001",
        "update_time": {
            "date": "2026-06-27 08:00:38.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
        "link": "https://social.example.com/100000000000001/posts/200000000000001",
        "hashtags": ["recipe", "summer", "drinks", "tip"],
        "mentions": [],
        "pictures": ["https://cdn.example.com/media/image-1.jpg"]
    }
}

Client side – evaluate:

use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$response = SocialServerResponse::fromJson($json);

if ($response instanceof SocialServerPostResponse) {
    $post = $response->getPost();
    echo $post->getMessage();

    foreach ($post->getHashtags() as $hashtag) {
        echo '#' . $hashtag; // the leading # is not part of the value
    }
}

Note

If a post contains mentions, the mentions field looks like this:

"mentions": [
    {"displayName": "Example Organization", "systemName": "300000000000001"}
]

Example 2: Multiple posts with pagination (SocialServerPostsResponse)

This is the most common response: a list of posts plus the cursors for paging. previousPage is empty on the first page; nextPage contains the full URL for the next fetch (or is empty when no further page exists).

Server side – create and output as JSON:

use Fixpunkt\FpSocialBridge\v2\Data\Post;
use Fixpunkt\FpSocialBridge\v2\Data\Posts;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostsResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$posts = new Posts([
    new Post(
        id: '100000000000001_200000000000001',
        headline: '',
        message: 'Summertime! Here is our favourite recipe for hot days.',
        post_url: 'https://social.example.com/100000000000001/posts/200000000000001',
        update_time: new \DateTime('2026-06-27 08:00:38+00:00'),
        link: 'https://social.example.com/100000000000001/posts/200000000000001',
        hashtags: ['recipe', 'summer', 'drinks', 'tip'],
        mentions: [],
        pictures: ['https://cdn.example.com/media/image-1.jpg'],
    ),
    new Post(
        id: '100000000000001_200000000000002',
        headline: '',
        message: 'We will soon present our new project – stay tuned!',
        post_url: 'https://social.example.com/100000000000001/posts/200000000000002',
        update_time: new \DateTime('2026-06-24 17:00:14+00:00'),
        link: 'https://social.example.com/100000000000001/posts/200000000000002',
        hashtags: ['project', 'news', 'outlook'],
        mentions: [],
        pictures: ['https://cdn.example.com/media/image-2.jpg'],
    ),
]);

$response = new SocialServerPostsResponse(
    SocialServerResponse::version,
    $posts,
    previous: '',
    next: 'https://social-server.example.com/networks/example/posts?tx_fpsocialserver_show%5Bafter%5D=QVFI...&tx_fpsocialserver_show%5Bversion%5D=2&cHash=0123456789abcdef0123456789abcdef',
);

echo json_encode($response->toArray());

The resulting JSON (posts and nextPage shortened):

{
    "type": "Fixpunkt\\FpSocialBridge\\v2\\Response\\SocialServerPostsResponse",
    "version": 2,
    "posts": [
        {
            "id": "100000000000001_200000000000001",
            "headline": "",
            "message": "Summertime! ...",
            "post_url": "https://social.example.com/100000000000001/posts/200000000000001",
            "update_time": {
                "date": "2026-06-27 08:00:38.000000",
                "timezone_type": 1,
                "timezone": "+00:00"
            },
            "link": "https://social.example.com/100000000000001/posts/200000000000001",
            "hashtags": ["recipe", "summer", "drinks", "tip"],
            "mentions": [],
            "pictures": ["https://cdn.example.com/media/image-1.jpg"]
        },
        {
            "id": "100000000000001_200000000000002",
            "headline": "",
            "message": "We will soon present our new project – stay tuned!",
            "...": "..."
        }
    ],
    "requests": {
        "previousPage": "",
        "nextPage": "https://social-server.example.com/networks/example/posts?tx_fpsocialserver_show%5Bafter%5D=QVFI...&tx_fpsocialserver_show%5Bversion%5D=2&cHash=0123456789abcdef0123456789abcdef"
    }
}

Client side – evaluate and iterate over the collection:

use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostsResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$response = SocialServerResponse::fromJson($json);

if ($response instanceof SocialServerPostsResponse) {
    foreach ($response->getPosts() as $post) {
        echo $post->getMessage();
    }

    // Cursors (URLs) for the next and previous page
    $next = $response->getNext();
    $previous = $response->getPrevious();
}

Note

Posts implements Iterator and Countable and can therefore be iterated directly with foreach and counted with count().

Example 3: Error response (SocialServerErrorResponse)

If an error occurs on the social server, it creates a SocialServerErrorResponse instead of a data response.

Server side – create and output as JSON:

use Fixpunkt\FpSocialBridge\v2\Response\SocialServerErrorResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$response = new SocialServerErrorResponse(
    SocialServerResponse::version,
    code: 42,
    message: 'The requested account does not exist.',
);

echo json_encode($response->toArray());

The resulting JSON:

{
    "type": "Fixpunkt\\FpSocialBridge\\v2\\Response\\SocialServerErrorResponse",
    "version": 2,
    "code": 555042,
    "message": "The requested account does not exist."
}

Note

The supplied error code is combined with the prefix 5550 in the constructor and stored as an int. So code: 42 becomes 555042.

Client side – evaluate:

use Fixpunkt\FpSocialBridge\v2\Response\SocialServerErrorResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;

$response = SocialServerResponse::fromJson($json);

if ($response instanceof SocialServerErrorResponse) {
    throw new \RuntimeException(
        $response->getMessage(),
        $response->getCode()
    );
}

Handling all types together

In practice the client side does not know in advance which type will come back. The factory always returns the matching object; instanceof is used to tell them apart:

use Fixpunkt\FpSocialBridge\v2\Response\SocialServerResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostsResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerPostResponse;
use Fixpunkt\FpSocialBridge\v2\Response\SocialServerErrorResponse;

$response = SocialServerResponse::fromJson($json);

if ($response instanceof SocialServerErrorResponse) {
    throw new \RuntimeException(
        $response->getMessage(),
        $response->getCode()
    );
}

if ($response instanceof SocialServerPostsResponse) {
    foreach ($response->getPosts() as $post) {
        echo $post->getMessage();
    }
    $next = $response->getNext(); // URL for the next page
}

if ($response instanceof SocialServerPostResponse) {
    $post = $response->getPost();
}

Note

fromJson() checks the protocol version and throws an \Exception if the data is corrupted or the version does not match. See SocialServerResponse.

Class reference

All classes live in the Fixpunkt\FpSocialBridge namespace. They fall into three types:

Interface – the shared serialization contract.
DTOs (data transfer objects) – the plain data carriers.
Responses – the typed response objects of the social server.

Interface

SerializableInterface

Shared contract of all data-transfer and response objects.

Method	Description
`fromJson(string $json): static`	Creates an object from a JSON string.
`fromArray(array $data): static`	Creates an object from an associative array.
`toArray(): array`	Serializes the object back into an array.

DTOs

The data transfer objects in the v2\Data namespace contain only data and accessor methods, no business logic.

v2\Data\Post

Represents a single post.

Method	Return value
`getId()`	`string` – unique ID of the post
`getHeadline()`	`string` – headline (empty for many sources)
`getMessage()`	`string` – message text as HTML (may contain `<br />`/`<a>` as well as emoji placeholders `{emoji:…}`)
`getPostUrl()`	`string` – URL of the post on the network
`getLink()`	`string` – linked URL
`getUpdateTime()`	`\DateTime` – time of last update (in JSON as `date` / `timezone_type` / `timezone`)
`getHashtags()`	`array` – hashtags as strings without a leading `#`
`getMentions()`	`array` – mentions as objects with `displayName` and `systemName`
`getPictures()`	`array` – picture URLs

v2\Data\Posts

Iterable, countable collection of Post objects. Implements Iterator and Countable, so it can be used directly with foreach and count().

Responses

The response objects in the v2\Response namespace represent the various response types of the social server. The base class factory turns a received JSON response into the matching object.

v2\Response\SocialServerResponse

Abstract base class of all server responses.

Method	Description
`fromJson(string $json): static`	Factory: checks the protocol version and returns the matching response object. Throws an `\Exception` on corrupted data or a mismatching version.
`getVersion(): int`	Protocol version of the response.

v2\Response\SocialServerPostResponse

Response containing a single post.

getPost(): Post – returns the contained post.

v2\Response\SocialServerPostsResponse

Response containing multiple posts including pagination.

Method	Description
`getPosts(): Posts`	Collection of the contained posts.
`getNext(): string`	Cursor for the next page (`nextPage`).
`getPrevious(): string`	Cursor for the previous page (`previousPage`).

v2\Response\SocialServerErrorResponse

Error response of the social server.

Method	Description
`getCode(): int`	Composite error code (prefix `5550`).
`getMessage(): string`	Error message.

Changelog

1.3.0

Added compatibility with TYPO3 14. The extension now supports TYPO3 12.4, 13.4 and 14.3.

Fixpunkt Social Bridge

Introduction

About this extension

Included classes

Installation

Requirements

Usage

Request flow

Structure of a post object

Example 1: A single post (SocialServerPostResponse)

Example 2: Multiple posts with pagination (SocialServerPostsResponse)

Example 3: Error response (SocialServerErrorResponse)

Handling all types together

Class reference

Interface

SerializableInterface

DTOs

v2\Data\Post

v2\Data\Posts

Responses

v2\Response\SocialServerResponse

v2\Response\SocialServerPostResponse

v2\Response\SocialServerPostsResponse

v2\Response\SocialServerErrorResponse

Changelog

1.3.0