Download the PHP package koh/semantic-delivery without Composer

Semantic Delivery — TYPO3 Extension

Schema.org enrichment and multi-channel content transformation for TYPO3. Delivers structured content across Website, AI Agent, Voice, and Social Media channels with automated distribution to external platforms.

Features

• Schema.org JSON-LD — Automatic structured data enrichment for TYPO3 content
• Multi-Channel Transformation — Optimized output for Website, AI Agent, Voice, and Social Media
• Direct Platform Distribution — Post directly to LinkedIn, X/Twitter, Instagram, Facebook, Bluesky, Medium, and Dev.to via native APIs
• Proxy Distribution — Push via Ayrshare, Buffer, webhooks, or n8n
• Per-Page Platform Selection — Editors choose which platforms each page is distributed to; only platforms with configured credentials are shown
• Blog Cross-Posting — Publish full articles to Medium (HTML) and Dev.to (Markdown) with canonical URL attribution
• Podcast Episode Detection — Automatic new-episode monitoring with multi-platform job creation
• Channel Detection — Middleware-based automatic detection of requesting channel
• OAuth Token Management — Encrypted per-platform token storage with refresh support
• Schema Caching — Performance-optimized schema generation with TYPO3 caching
• DDD 4-Layer Architecture — Strict layer separation enforced by deptrac

Installation

Requirements

• PHP 8.3+
• TYPO3 14.0

Architecture

Database Tables

Page Fields

The platform selector only shows platforms that have credentials configured in the current site's settings. This prevents editors from selecting targets that would fail.

Schema.org Generation

Each frontend response is enriched with one or more <script type="application/ld+json"> blocks. Generators are auto-discovered (semantic_delivery.schema_generator tag) and ordered by priority — every generator that returns true from canHandle() contributes one document.

Generator Priority Order

Article / WebPage Family Routing

Application/Service/SchemaTypeResolverService is the single source of truth for picking a schema type from the Article- or WebPage-family. Both ArticleSchemaGenerator (priority 50) and WebPageSchemaGenerator (priority 45) delegate their canHandle() to the resolver, so a page emits either an Article-family or a WebPage-family document — never both.

Resolution order (highest priority first):

1. Manual override — pages.tx_semanticdelivery_schema_type. Article-/WebPage-family values are honoured directly. Other values (e.g. Product, FAQPage) cause the resolver to return null so the dedicated generator owns the page.

2. Slug heuristic — language-stable index/section patterns only:

   Slug pattern	Schema Type
   /blog (root)	CollectionPage
   /blog/<sub>	BlogPosting
   /news, /press, /presse (root)	CollectionPage
   /news/<sub>, /press/<sub>, /presse/<sub>	NewsArticle
   /portfolio, /referenz* (root)	CollectionPage
   /portfolio/<sub>, /referenz*/<sub>	ItemPage

   Language-specific patterns (/kontakt, /ueber-uns, /about, /contact, /team, /profil) are not auto-detected — for these pages the editor sets the override in the backend (the dropdown shows a description per type).

3. Hero content block hint — first matching CType wins:

   Hero CType	Family	Schema Type
   moselwal_bloghero	article	BlogPosting
   moselwal_pagehero	article	Article
   moselwal_herocard	article	Article
   moselwal_teaser	article	NewsArticle
   moselwal_hero	webpage	WebPage
   moselwal_olehero	webpage	AboutPage
   moselwal_nozzlehero	webpage	WebPage

4. Keywords heuristic (pages.keywords substrings):

   Keyword contains	Schema Type
   tech, technical	TechArticle
   paper, study, research	ScholarlyArticle
   report	Report
   social	SocialMediaPosting
   blog	BlogPosting
   news, press	NewsArticle
   collection, index	CollectionPage

5. Default — Article for standard pages (doktype 1 or 2 with content), otherwise WebPage.

The resolver returns null (and the dedicated generator takes over) when the page contains FAQ / Service / Product / Podcast / PackagesGrid CTypes, or sits below /leistungen, /impressum, /datenschutz, /karriere, /podcasts.

Backend Override Dropdown

The page property dropdown is grouped via --div-- separators and every option carries a descriptive tooltip rendered by the TYPO3 backend:

The descriptions guide editors on when to pick each type — important for language-specific pages (/kontakt, /ueber-uns, /about …) that the resolver does not auto-detect. Values outside the Article/WebPage families let the dedicated generator (FAQ, Product, Organization, …) own the page.

Distribution

Supported Platforms

Social Media (short-form)

Blog Platforms (long-form)

Blog distributors include canonical URL attribution back to the original TYPO3 page.

Note: Medium has discontinued issuing new API integration tokens. The MediumDistributor has been removed.

Proxy Services

Setup

1. Enable distribution in site settings

2. Configure platform credentials

Credentials are configured per site in config/sites/<name>/config.yaml. Sensitive tokens use the %secret()% syntax (resolved by moselwal/secret-resolver, a separate, non-public extension), public identifiers go directly into the YAML.

Only platforms with a non-empty primary credential appear in the backend page editor. Platforms without credentials are hidden from the editor so they cannot select targets that would fail.

3. Run the database schema update

4. Per-page platform selection

In the TYPO3 backend, each page has a Semantic Delivery tab:

1. Check Enable Distribution
2. Select target platforms (only configured platforms are shown)
3. Save and publish

The distribution system respects this selection — pages are only distributed to checked platforms.

Platform Credential Guides

Bluesky

Auth: App Password (no OAuth required) Scope: Full post access

1. Log in to bsky.app
2. Go to Settings → Privacy and Security → App Passwords
3. Click Add App Password, give it a name (e.g. "TYPO3 Distribution")
4. Copy the generated password

Token does not expire. Revoke at any time in App Passwords settings.

LinkedIn

Auth: OAuth 2.0 Access Token Modes: Personal posting (w_member_social) or Organization posting (w_organization_social)

Step 1 — Create a LinkedIn App:

1. Go to linkedin.com/developers/apps → Create app
2. Fill in App name, associate your LinkedIn Company Page, upload a logo
3. Under Products tab → enable Share on LinkedIn (instant access)
4. Under Auth tab → note your Client ID and Client Secret
5. Add a Redirect URL (e.g. https://yourdomain.com/linkedin-callback)

Step 2 — Get an Access Token:

Open this URL in a browser (replace placeholders):

After consent, the browser redirects to your redirect URL with ?code=AUTH_CODE. Exchange it:

The response contains access_token (valid for 60 days) and refresh_token.

Step 3 — Get your Person ID:

The sub field in the response is your Person ID.

Step 4 — Configure:

To post as a Company Page instead, set organizationId (requires w_organization_social scope via Community Management API product). When both are set, organizationId takes precedence.

Token expiry: LinkedIn tokens expire after 60 days. Refresh manually or automate via OAuthTokenService.

X / Twitter

Auth: OAuth 2.0 Bearer Token Scope: tweet.read, tweet.write, users.read

1. Go to developer.x.com/en/portal
2. Create a Project and an App within it
3. Under User authentication settings → enable OAuth 2.0
4. Set App permissions to Read and write
5. Under Keys and tokens → generate Bearer Token

Note: Free tier allows 1,500 tweets/month. The API requires a developer account with at least Basic access ($100/month) for tweet.write.

Facebook

Auth: Page Access Token (Long-Lived) Scope: pages_manage_posts, pages_read_engagement

Step 1 — Create a Facebook App:

1. Go to developers.facebook.com → Create App
2. Choose Business type
3. Add the Facebook Login product

Step 2 — Get a Page Access Token:

1. Open the Graph API Explorer
2. Select your App from the dropdown
3. Click Generate Access Token → grant pages_manage_posts permission
4. Select the Page from the User or Page dropdown at top
5. The token shown is now a Page Access Token
6. Exchange for a Long-Lived Token (60 days):

Step 3 — Get your Page ID:

The id field for your page is the Page ID.

Instagram

Auth: Instagram Graph API via Facebook Page Token Scope: instagram_basic, instagram_content_publish

Prerequisites: A Facebook Page linked to an Instagram Business/Creator account.

Step 1 — Get the Instagram Business Account ID:

The instagram_business_account.id is your Account ID.

Step 2 — Configure:

Note: Instagram posting via Graph API requires an image or video. Text-only posts are not supported. The InstagramTransformer handles this by including hashtags and truncating to 2,200 characters.

Dev.to

Auth: API Key (no OAuth)

1. Log in to dev.to
2. Go to Settings → Extensions (or dev.to/settings/extensions)
3. Under DEV Community API Keys → generate a new key
4. Copy the key

Token does not expire. Posts are published as Markdown with canonical URL pointing back to the TYPO3 page.

Complete Site Config Example

Secret vs. public values:

CLI Commands

Detect new podcast episodes

Cache key v3.0.4+: the episode detector reads from the content_blocks_collection_rssfeed cache with 'rssfeed_' . hash('sha256', $feedUrl). This must match the write key in moselwal/content-blocks-collection's PodcastFeedService::cacheIdentifierFor() (previously md5 — the mismatch meant the detector found no episodes). Its own podcast_hash_* / podcast_guids_* keys still use md5, because the detector maintains both sides itself.

Process pending jobs

Recommended cron schedule

Backend Module

Available under Content → Semantic Delivery (admin access):

• Preview — View transformed content per platform before publishing
• Queue — Manage pending distribution jobs
• Log — Review completed and failed distributions with external URLs

Adding a New Distributor

New distributors are auto-discovered via dependency injection:

1. Create a class implementing DistributorInterface in Classes/Infrastructure/Distribution/
2. Optionally create a TransformerInterface in Classes/Infrastructure/Transformer/
3. Add a credential key mapping in DistributionPlatformItemsProcFunc::CREDENTIAL_KEYS
4. Add the corresponding site setting in settings.definitions.yaml and settings.yaml

The platform automatically appears in the page editor once credentials are configured for the site.

OAuth Token Service

For platforms requiring OAuth 2.0 with token refresh:

Tokens are encrypted at rest using AES-256-CBC with the TYPO3 encryption key.

Configuration Reference

Site Settings

Development

Dependencies

License

MIT — see LICENSE for details.