EasySocialAutopilot · Bedienhandbuch

Dieses Handbuch begleitet dich durch Installation, Channel-Anbindung und Betrieb des Plugins EasySocialAutopilot v0.4.0 in der Ausbaustufe Phase 4 — Auto-Enqueue + 20 Channels. Es beschreibt den realen Funktionsumfang dieser Version — ohne Versprechungen, die der Code noch nicht einlöst.

Worum geht's?

Was EasySocialAutopilot heute tut, warum es existiert und für wen sich diese Phase-4-Version lohnt.

EasySocialAutopilot ist ein WordPress-Plugin, das deine Blog-Beiträge automatisiert an Social-Media-Plattformen verteilt. Die Architektur ist von Anfang an als Multi-Channel-Pipeline gebaut: jeder Kanal (Mastodon, Bluesky, Telegram, Discord, LinkedIn, Reddit, Pinterest, …) ist ein eigener Driver hinter einem stabilen ChannelDriver-Interface. Du verbindest beliebig viele Accounts pro Kanal, deine WordPress-Posts wandern in eine Queue, ein Cron-Worker greift sich pending Jobs alle fünf Minuten und ruft den jeweiligen Driver auf.

In der vorliegenden Version 0.4.0 sind 20 Channel-Driver registriert. Elf davon sind voll funktional und posten in Produktion (Mastodon, Bluesky, Telegram, Discord, Webhook, LinkedIn, Reddit, Pinterest, Tumblr, WordPress.com, Google Business Profile, Blogger). Fünf weitere haben einen funktionierenden OAuth-Connect, aber der Posting-Pfad ist bis zu einer externen Freigabe (App-Review oder Paid-Tier) blockiert — Facebook Pages, Instagram, Threads, TikTok, X (Twitter). YouTube läuft im description_update-Modus produktiv, video_upload und Community Posts geben eine ehrliche Failure zurück. Medium läuft per Integration-Token (kein OAuth-Onboarding mehr möglich). XING ist ein dokumentierter Platzhalter — die öffentliche API wurde 2022 abgeschaltet.

Phase 4 ist live: Der Hook auf transition_post_status legt beim Publish eines Posts automatisch Queue-Jobs für alle aktiven Channel-Accounts an. Per Post-Meta _esa_selected_accounts kannst du die Zielauswahl pro Post überschreiben, mit _esa_skip_distribution=1 ein einzelner Post komplett aus der Verteilung herausgenommen werden. Idempotenz ist eingebaut: QueueRepository::hasActiveJob verhindert Duplikate, wenn ein Post mehrfach gespeichert wird.

Die zentrale Designentscheidung bleibt: kein Phone-Home, kein Lizenz-Server, keine SaaS-Abhängigkeit. Tokens liegen AES-256-GCM-verschlüsselt in deiner WordPress-Datenbank. Wenn du das Plugin morgen ausschaltest, ist alles auf deinem Server — nichts auf einem fremden.

Zielgruppe der aktuellen Version sind Plugin-Entwickler, Self-Hoster, Agenturen und Power-User, die mit einer ehrlich beschriebenen Phase-4-Reife produktiv testen oder produktiv betreiben wollen. End-User mit Komfortanspruch sollten auf Phase 5 (Gutenberg-Sidebar-UI für die Per-Post-Selection) warten.

Voraussetzungen

Welche Plattform, welche WordPress-Konfiguration und welche externen Accounts du brauchst, bevor du startest.

Channel-spezifische Voraussetzungen

Für die meisten Channels brauchst du auf der Plattform-Seite mindestens ein normales Nutzerkonto. Manche Channels verlangen zusätzlich, dass du als Plugin-Betreiber eine eigene Developer-App registrierst (OAuth-Channels) — Channel-spezifische Setup-Schritte stehen in Kapitel 5b. Eine grobe Vorab-Übersicht:

Installation

Drei Wege zur Installation — wähle den, der zu deiner Umgebung passt.

Variante A: ZIP-Upload (Endnutzer)

Empfohlen, wenn du ein klassisches Managed-WordPress-Hosting nutzt.

1. Lade das Release-ZIP von GitHub (Releases-Tab) oder von einer Build-Pipeline.
2. WordPress-Admin → Plugins → Hochladen → ZIP wählen → Jetzt installieren.
3. Nach dem Upload Plugin aktivieren klicken.

Variante B: Git-Clone (Entwickler)

cd wp-content/plugins
git clone https://github.com/uh8888/easysocialautopilot.git
cd easysocialautopilot
composer install --no-dev --optimize-autoloader

Anschließend im WP-Admin aktivieren.

Variante C: Bind-Mount im Docker-Setup (Self-Hoster)

Wenn dein WordPress in einem Docker-Container läuft, mountest du das Plugin-Verzeichnis direkt ins wp-content/plugins-Volume. Beispiel-Snippet für docker-compose.yml:

services:
  wordpress:
    image: wordpress:latest
    volumes:
      - ./easysocialautopilot:/var/www/html/wp-content/plugins/easysocialautopilot:ro

Vorteil: Code-Updates sind ein git pull weit weg, ohne ZIP-Roundtrip.

Was bei der Aktivierung passiert

Der Activator (EasySocialAutopilot\Core\Activator::activate) führt folgende Schritte aus:

Die fünf Tabellen (Prefix wp_esa_ bei Standard-WP-Prefix):

Erster Login & Tour der UI

Was du nach der Aktivierung im Admin siehst — und welche Sidebar-Items in Phase 4 wirklich gefüllt sind.

Nach der Aktivierung erscheint im linken WordPress-Sidebar-Menü der Eintrag Social Autopilot. Klick darauf — du landest auf einer einseitigen React-SPA mit Hash-Router (#/dashboard, #/channels, …) im klassischen ContentForge-Schwarz mit Lime-Akzenten.

Die SPA hat sechs Pages, die du oben über die Sub-Navigation erreichst:

Die SPA lädt ihre Daten ausschließlich über den REST-Namespace esa/v1. Jeder Request trägt einen X-WP-Nonce-Header, der von der RestApi::authorize-Permission-Callback gegen die wp_rest-Action verifiziert wird. Capability-Check: manage_options — also nur Administratoren.

Bundle-Loading-Hinweis

Das React-Bundle wird als ESM-Modul geladen, um die WordPress-wp-Global-Kollision zu umgehen. Vite ist mit base: './' gebaut — so funktionieren auch relative Font-Pfade in Subdirectory-Installationen. Wenn du dein eigenes Bundle baust: npm run build im Plugin-Root.

Channels verbinden — der gemeinsame Flow

Das Hauptkapitel: Schritt-für-Schritt durch den Connect-Flow, den die meisten Channels gemeinsam haben. Channel-spezifische Setup-Schritte stehen direkt danach in Kapitel 5b.

Was technisch passiert (Kurzfassung)

Der Connect-Flow folgt einem stabilen Muster, egal ob OAuth, App-Password oder Token:

Schritt für Schritt im Browser

1. Öffne die Channels-Page. Sidebar → Social Autopilot → Tab Channels. Du siehst 20 Karten, jeweils mit Channel-Logo, Status (verbunden / nicht verbunden), Account-Counter und einem Connect-Button.

2. Klick auf Connect. Es öffnet sich ein modaler Dialog (ConnectModal) mit den Feldern, die der jeweilige Driver verlangt — von einer einzigen Instance-URL (Mastodon) bis zu drei Feldern (Bluesky: Handle, App-Password, optional PDS).

3. Fülle aus & sende ab. Bei OAuth-Channels wirst du auf die Plattform redirected. Bei Token-Channels macht der Driver eine Live-Verifizierung — wenn das Token nicht stimmt, siehst du sofort einen Fehler im Dialog.

4. Erfolg. Du landest auf #/channels?connected=1&account_id=<neue-id>, ein Success-Toast erscheint, die Account-Karte rendert sich mit Avatar, Anzeigename und Aktiv-Pill.

Mehrere Accounts pro Channel

Du kannst pro Channel beliebig viele Accounts verbinden — auch über mehrere Instanzen / Pages / Subreddits / Bot-Identitäten hinweg. Der Connect-Button heißt nach dem ersten verbundenen Account Weiteren Account verbinden. Jeder Account hat eine eigene account_id, einen eigenen Credential-Blob und kann einzeln getrennt werden.

Was passiert beim Trennen?

Trennen heißt: Row in wp_esa_channel_accounts wird gelöscht. Externe App-Autorisierungen bleiben in der Regel bestehen — sauber widerrufen kannst du sie auf der jeweiligen Plattform (Mastodon: Authorized Apps; Google: Drittanbieter-Apps mit Zugriff; Meta: Business-Einstellungen → Verbundene Apps; etc.). Pending Queue-Jobs, die auf den gelöschten Account verweisen, schlagen beim nächsten Cron-Run mit "account not found" terminal fehl.

Channels im Detail

Pro Channel: kurze Beschreibung, Setup-Schritte als Tabelle und Verweis auf die ausführliche README im Repo unter src/Channels/<Name>/README.md. Wo eine Plattform-seitige Freigabe fehlt, ist das ehrlich als "blockiert pending external approval" markiert.

5b.1 Simple Auth — kein Developer-Account nötig

Diese fünf Channels sind die schnellsten zum Verbinden: keine eigene App-Registrierung, keine Developer-Subscription, kein Verifizierungsprozess.

Mastodon

Voll funktional. Die OAuth-App wird beim ersten Connect dynamisch via POST /api/v1/apps auf der gewählten Mastodon-Instance registriert — du musst weder bei Mastodon noch beim Plugin-Hersteller etwas einrichten. Der Driver normalisiert Instance-Eingaben (Schema-Strip, Lowercase, Pfad weg), unterstützt Featured-Image-Upload und sendet Idempotency-Key-Header zur Doppel-Post-Vermeidung.

Per-Post-Optionen: visibility (public/unlisted/private/direct), language, sensitive, spoiler_text.

Bluesky

Voll funktional. Authentifiziert mit einem App-Password (nicht dem Account-Passwort). Der Driver speichert accessJwt (~1 h) und refreshJwt (~2 Monate), rotiert den Access-Token automatisch, und fällt bei Doppel-Expire auf erneutes createSession zurück. Link-Facets werden automatisch erkannt, Featured Image als app.bsky.embed.images mit max. 1 MB eingebettet.

Per-Post-Optionen: langs (Default en). Hard-Limit: 300 Zeichen. Details: src/Channels/Bluesky/README.md.

Telegram

Voll funktional. Nutzt einen Bot-Token statt OAuth. Mit Featured Image wird sendPhoto mit Caption gesendet (1024-Zeichen-Limit), ohne wird sendMessage mit HTML-formatiertem Body gesendet (4096-Zeichen-Limit).

Per-Post-Optionen: chat_id (Override), parse_mode (HTML/MarkdownV2), disable_link_preview. Details: src/Channels/Telegram/README.md.

Discord

Voll funktional. Postet via Channel-Webhook — kein Bot-Account, kein OAuth-Scope. Sendet pro Post einen Rich-Embed mit Title, Description, URL, Featured-Image und Discord-Blurple als Farbe.

Per-Post-Optionen: content (Message über dem Embed, max. 2000 Zeichen). Details: src/Channels/Discord/README.md.

Webhook

Voll funktional. Generischer JSON-POST an einen beliebigen HTTPS-Endpoint — perfekt für Zapier, n8n, Make, Custom-CRMs, Log-Aggregatoren. Optional mit HMAC-SHA256-Signatur per Shared-Secret.

Payload-Schema enthält id, title, content, excerpt, link, featured_image, published_at, author. Bei gesetztem Secret kommt ein X-ESA-Signature: sha256=<hex> Header mit. Details: src/Channels/Webhook/README.md.

5b.2 OAuth 2.0 Standard — User registriert eigene App

Sechs Channels mit klassischem OAuth-2-Authorization-Code-Flow. Du brauchst pro Channel eine eigene Developer-App beim Provider und musst Client-ID/Secret als WP-Konstanten setzen.

LinkedIn

Voll funktional. Postet auf Member-Feeds und optional auf Company Pages via REST Posts API (/rest/posts, Version 202405).

Scopes: openid profile w_member_social (Member) bzw. zusätzlich w_organization_social r_organization_social rw_organization_admin (Pages). Per-Post: visibility (PUBLIC/CONNECTIONS), reshare_disabled. Details: src/Channels/LinkedIn/README.md.

Reddit

Voll funktional. Submitted Link- oder Self-Posts via POST /api/submit auf oauth.reddit.com mit duration=permanent (Refresh-Token).

Scopes: identity submit flair mysubreddits read. Per-Post: subreddit (Pflicht, ohne r/-Prefix), kind (link/self), text, flair_id, nsfw, spoiler. Reddit verlangt einen unique User-Agent — der Driver sendet EasySocialAutopilot/<version> by <reddit-username>. Details: src/Channels/Reddit/README.md.

Pinterest

Voll funktional. Erzeugt Pins via Pinterest API v5 (POST /v5/pins). Pinterest erfordert ein Bild pro Pin — Posts ohne Featured Image failen mit klarer Fehlermeldung.

Scopes: boards:read,pins:read,pins:write,user_accounts:read. Per-Post: board_id, section_id, alt_text. Access-Token ~30 Tage, Refresh ~60 Tage (Driver refreshed automatisch). Details: src/Channels/Pinterest/README.md.

Tumblr

Voll funktional. Nutzt OAuth 1.0a HMAC-SHA1 (historisch bedingt). Postet als Tumblr-Text-Post auf den Primary-Blog.

Per-Post: state (published/draft/queue/private), format (html/markdown), tags. Driver nutzt die stabile Legacy-form-encoded-Variante, nicht NPF. Details: src/Channels/Tumblr/README.md.

WordPress.com

Voll funktional. Postet auf WordPress.com-Blogs oder Jetpack-verbundene Self-Hosted-Sites via REST API v1.1.

Per-Post: status, tags, categories, sticky. Achtung: Bearer-Tokens haben ~2 Wochen TTL, kein Refresh-Token — bei Expire status='expired', User muss neu autorisieren. Details: src/Channels/WordPressCom/README.md.

Medium

Funktional via Integration-Token-Pfad (OAuth ist seit März 2023 für neue Partner geschlossen und das API-Repo archiviert). Wenn POST /v1/users/{id}/posts mal 404/410 zurückgibt, zeigt der Driver einen ehrlichen "Medium API is no longer publicly accessible"-Fehler.

Per-Post: publish_status (public/draft/unlisted), tags (max. 5), canonical_url (Default true, gut für SEO-Credit), license, notify_followers. Details: src/Channels/Medium/README.md.

5b.3 Google Ecosystem — ein Cloud-Projekt, drei Channels

Google Business Profile, YouTube und Blogger teilen sich einen Google-Cloud-Projekt und einen OAuth-Client. Du registrierst einmal, aktivierst dann pro Channel die passende API. Konstanten in wp-config.php:

define( 'ESA_GOOGLE_APP_ID',     '...apps.googleusercontent.com' );
define( 'ESA_GOOGLE_APP_SECRET', '...' );

Gemeinsames Google-Setup

Google Business Profile

Voll funktional. Postet in den Location-Feed (eine ChannelAccount pro Location).

Scope: https://www.googleapis.com/auth/business.manage. Per-Post: language_code, cta_action_type (LEARN_MORE/BOOK/ORDER/SHOP/SIGN_UP/CALL), cta_url. Limits: Summary max. 1500 Zeichen, Featured Image als media[0].sourceUrl (muss öffentlich erreichbar sein), Posts laufen nach 7 Tagen automatisch ab (GBP-Policy). Details: src/Channels/GoogleBusinessProfile/README.md.

YouTube

description_update-Modus voll funktional — perfekt um z. B. Show-Notes oder Affiliate-Links automatisiert aus einem WP-Post-Update an ein bestehendes Video anzuhängen. video_upload und community_post returnen ehrlich SendResult::failure.

Scope: https://www.googleapis.com/auth/youtube. Per-Post: mode (description_update Default), video_id (Pflicht), prepend (Bool — Default ist Append). Warum die anderen Modi blockiert sind: video_upload braucht den sensitiven youtube.upload-Scope + Google-Branding-Verification + Resumable-Multipart-Upload; community_post hat keine öffentliche API, nur YouTube Studio. Details: src/Channels/YouTube/README.md.

Blogger

Voll funktional. Postet einen WordPress-Post als neuen Blogger-v3-Post. Eine ChannelAccount pro Blogger-Blog — eine Google-Identität kann mehrere Blogs haben, jeden separat verbinden.

Scope: https://www.googleapis.com/auth/blogger. Per-Post: labels (Tags), draft (Bool), title (Override). post_content läuft durch the_content-Filter, Blogger nimmt HTML direkt an. Details: src/Channels/Blogger/README.md.

5b.4 Meta + Paid Tier — OAuth klappt, Posten blockiert

Fünf Channels mit funktionierendem OAuth-Connect, aber blockiertem Posting-Pfad. Du kannst jetzt schon die Accounts verbinden und in der UI sehen — sobald die externe Freigabe da ist, wird der POSTING_BLOCKED-Stub in send() entfernt und das Posten geht live.

Drei davon (Facebook Pages, Instagram, Threads) teilen sich eine Meta-Developer-App. Konstanten:

define( 'ESA_META_APP_ID',     '...' );
define( 'ESA_META_APP_SECRET', '...' );

Facebook Pages

Connect funktional. Posten BLOCKIERT pending Facebook App Review für pages_manage_posts.

Setup: Meta Developer Portal → App → Scopes pages_show_list, pages_read_engagement, pages_manage_posts, business_management anfordern → in Live-Mode + App Review schicken. OAuth: Short-Lived-User-Token → Long-Lived-User-Token (~60 d) → GET /me/accounts liefert pro Page einen perpetual Page-Access-Token. Pro Page ein ChannelAccount. Posting-Flow (vorbereitet, aber blockiert): POST graph.facebook.com/v21.0/{page-id}/feed. Details: src/Channels/Facebook/README.md.

Instagram

Connect funktional. Posten BLOCKIERT pending Instagram Business Account + Facebook App Review für instagram_content_publish.

Voraussetzung: User verwaltet mindestens eine FB-Page, die mit einem Instagram-Business-Konto verknüpft ist. Scopes: pages_show_list, pages_read_engagement, business_management, instagram_basic, instagram_content_publish. Discovery: GET /me/accounts?fields=instagram_business_account. Posting-Flow (geplant): 2-Step Create-Media → Publish-Media. Details: src/Channels/Instagram/README.md.

Threads

Connect funktional. Posten BLOCKIERT pending Threads-API-Access (derzeit Limited Rollout).

OAuth läuft über threads.net/oauth/authorize (nicht facebook.com), Token-Exchange auf graph.threads.net. Long-lived-Exchange ?grant_type=th_exchange_token ergibt ~60-Tage-Token. Scopes: threads_basic, threads_content_publish. Posting-Flow analog Instagram (2-Step). Details: src/Channels/Threads/README.md.

TikTok

Connect funktional. Posten BLOCKIERT pending TikTok Developer Sandbox + Production Review für video.publish.

TikTok hat keine Text-only Posts — jeder Publish braucht ein Video. Der Driver fail-fast auf fehlendes options['video_url'] (auch vor dem Posting-Block). Konstanten: ESA_TIKTOK_CLIENT_KEY + ESA_TIKTOK_CLIENT_SECRET. Scopes: user.info.basic, video.publish. Refresh-Token-Flow implementiert. Posting-Flow (geplant): Async 3-Step Init → PUT-Upload → Status-Poll. Details: src/Channels/TikTok/README.md.

X (Twitter)

Connect funktional. Posten BLOCKIERT pending X API v2 Basic-Tier ($100+/Monat).

OAuth 2.0 mit PKCE. Konstanten: ESA_X_CLIENT_ID (optional ESA_X_CLIENT_SECRET für Confidential-Client). Scopes: tweet.read, tweet.write, users.read, offline.access. PKCE: code_verifier (64 random Bytes, base64url), code_challenge = SHA256(verifier) (S256). Refresh-Token-Flow implementiert. Posting-Flow (geplant): POST /2/tweets mit max. 280 Zeichen Free / 25.000 Premium. Details: src/Channels/X/README.md.

5b.5 Discontinued — XING

XING

Platzhalter — nicht funktional. XING hat seine öffentliche Developer-API (dev.xing.com) 2022 abgeschaltet. Der OAuth 1.0a Flow und der /v1/users/me/status_message-Endpoint sind nicht mehr erreichbar, kein Ersatz wurde veröffentlicht.

Was der Driver tut: Er registriert den Channel in der Connector-Liste, alle anderen Methoden werfen einen klaren RuntimeException mit "XING public API was discontinued in 2022; this channel is a placeholder pending an alternative integration path." refreshIfNeeded() markiert Accounts als status='expired'.

Manueller Workaround: XING Business Manager für Company-Page-Scheduling nutzen, persönliche Status-Updates aus WordPress per Copy-Paste übertragen. Wenn die API zurückkommt: der Stub-Code in src/Channels/Xing/ ist so gebaut, dass man die Real-Implementierung 1:1 austauschen kann (OAuth 1.0a kann von \EasySocialAutopilot\Channels\Tumblr\TumblrOAuth1 recycelt werden). Details: src/Channels/Xing/README.md.

Einen Post veröffentlichen (Phase-4-Flow)

Wie ein WordPress-Post automatisch in die Queue kommt — und welche Hebel du pro Post hast.

Auto-Enqueue ist live

Phase 4 liefert das Stück, das in Phase 3 noch gefehlt hat: einen Listener auf transition_post_status. Sobald du einen Post von draft auf publish setzt (egal ob im Block-Editor, Classic-Editor, per REST-API oder per WP-CLI), passiert Folgendes:

Per-Post-Override via Post-Meta

Zwei Post-Meta-Keys steuern die Verteilung pro Post:

Heute setzt du diese Meta-Keys per Code (z. B. ACF, add_post_meta, REST-API, wp post meta add). Eine UI-Meta-Box / Gutenberg-Sidebar dafür kommt in Phase 5 — bis dahin ist die Verteilung "alle aktiven Accounts kriegen alles, außer du sagst per Meta explizit was anderes".

Skip-Distribution-Beispiel

# Diesen Post nicht verteilen
wp post meta add 123 _esa_skip_distribution 1

# Nur an Mastodon-Account #5 und Bluesky-Account #8
wp post meta update 123 _esa_selected_accounts '[5,8]' --format=json

Cron jetzt ausführen — der manuelle Trigger

Wenn du nicht 5 Minuten warten willst, gibt es auf der Queue-Page einen Button Cron jetzt ausführen. Klick → POST /wp-json/esa/v1/cron/run triggert QueueProcessor::run synchron im Request-Kontext. Im Toast siehst du Before/After-Counts (z. B. "3 jobs processed: 7 → 4 pending"). Praktisch beim Testen, Demos und für ungeduldige Redakteure. Capability-geschützt: nur manage_options.

Alternativ über WP-CLI:

wp cron event run esa_process_queue

Oder per curl gegen den WP-Cron-Endpoint:

curl https://<deine-site>/wp-cron.php?doing_wp_cron

Was geschieht beim Send

Pro Queue-Job ruft QueueProcessor den passenden ChannelDriver::send($post, $account, $payload). Was der Driver pro Channel tut, steht in Kapitel 5b. Erfolg → Job-Eintrag in wp_esa_jobs mit remote_post_id + remote_post_url. Misserfolg → Retry mit Backoff (siehe nächstes Kapitel).

Queue verstehen

Was die Queue-Page zeigt, wie Retry funktioniert und welche Backoff-Strategie der Cron-Processor fährt.

Die Queue-Page (#/queue) liest defaultmäßig pending Jobs (Status-Filter via REST-Query-Param status=processing|done|failed). Tabellen-Spalten:

Status-Werte

Retry- und Backoff-Strategie

Konstanten: QueueProcessor::BACKOFF = [1=>300, 2=>900, 3=>3600, 4=>10800], QueueRepository::MAX_ATTEMPTS = 4.

Retry-Button

Setzt manuell status='pending', attempts=0, last_error=NULL, scheduled_for=now(). Auch terminal failed-Einträge können so reanimiert werden — sinnvoll, wenn z. B. eine API kurzfristig down war.

Cancel-Button

Löscht den Queue-Eintrag. Keine History-Spur in wp_esa_jobs.

Batch-Größe

Pro Cron-Tick verarbeitet QueueProcessor::run maximal BATCH_SIZE = 10 Jobs. Größere Backlogs werden seriell über mehrere Ticks abgearbeitet — das schont Remote-Rate-Limits.

Mehrere Channels gleichzeitig

Der typische Phase-4-Workflow: ein Post fließt automatisch an alle aktiven Accounts.

Standard-Workflow

1. Du verbindest in Kapitel 5/5b z. B. einen Mastodon-Account, einen Bluesky-Account, einen LinkedIn-Account und einen Telegram-Bot.
2. Du veröffentlichst einen WP-Post.
3. PostHookListener legt vier Queue-Jobs an — einen pro aktivem Account.
4. Der nächste Cron-Tick (oder Button-Klick) dispatcht alle vier parallel an die jeweiligen APIs.
5. Im History-Tab siehst du vier Outcome-Einträge mit Links auf den jeweiligen Remote-Post.

Mit Per-Post-Override

Wenn du nur einen Channel pro Post willst:

wp post meta update 999 _esa_selected_accounts '[12]' --format=json

Nur Account 12 kriegt einen Job. Die anderen aktiven Accounts werden für diesen Post übersprungen.

Performance-Hinweise

Bei großen Backlogs (z. B. nach Mass-Republish): mehrfach Cron jetzt ausführen drücken oder per WP-CLI wp cron event run esa_process_queue schleifen lassen.

History

Was in wp_esa_jobs landet, was bewusst nicht geloggt wird und wie du Remote-Posts wiederfindest.

Die History-Page (#/history) listet alle Jobs aus wp_esa_jobs — also Einträge mit Status success oder terminal failed. Retries werden bewusst NICHT in History geschrieben, nur das finale Outcome. Das hält die History rauscharm.

Spalten

Datenfelder, die in wp_esa_jobs landen

Bei terminal failed-Einträgen ist remote_post_id leer und response_data enthält den letzten Fehlerkontext.

Logs & Debugging

Wo du nachschaust, wenn etwas klemmt.

Logs-Page

#/logs zeigt den Application-Log-Stream aus wp_esa_logs. Filter-Pills oben (All / Debug / Info / Warn / Error). Limit 200 Einträge pro Reload. Wird von HTTP-Schicht (HttpClient) und Channel-Driver-Code populated.

Apache-Error-Log

Das eigentlich interessante Log liegt im Web-Server-Container:

docker exec wp-esa tail -f /var/log/apache2/error.log

Suche nach Prefixes:

Häufige Fehler

Sicherheit

Wie das Plugin mit Tokens, Permissions und Nonces umgeht.

Token-Verschlüsselung

Access-Tokens / Refresh-Tokens / App-Passwords / Bot-Tokens / Webhook-URLs / HMAC-Secrets — alles wird nie im Klartext gespeichert. Helpers\Encryption nutzt AES-256-GCM mit einem zur Laufzeit aus drei WordPress-Salts abgeleiteten Schlüssel:

Wichtige Konsequenz: Wenn du deine wp-config.php-Salts rotierst, werden alle vorhandenen Token-Blobs unentschlüsselbar. Bei der nächsten Validierung fliegt Cannot decrypt credentials und der Account muss neu verbunden werden. Bewusstes Sicherheitsfeature, kein Bug.

Capability-Checks

Alle Admin-Pages und alle REST-Endpoints prüfen current_user_can('manage_options'). Editoren, Autoren oder Subscribers haben keinerlei Zugriff. Eine Custom-Capability-Filter (z. B. damit Editoren auch posten dürfen) ist in Phase 4 nicht eingebaut.

Nonces

Alle mutierenden REST-Routen verlangen einen X-WP-Nonce-Header mit der Action wp_rest. Die React-SPA bekommt den Nonce beim Admin-Asset-Enqueue und sendet ihn automatisch mit.

Kein Phone-Home, kein Tracking

• Keine Aktivierungs-Beacons.
• Keine Lizenz-Server-Checks.
• Keine Telemetrie über genutzte Channels.
• Keine externen JS-Bundles (alles wird mit der React-SPA gebundled und ausgeliefert).
• Outbound-Traffic geht ausschließlich zu Channel-APIs, mit denen du dich aktiv verbunden hast.

Idempotency-Keys

Wo die Plattform es unterstützt (Mastodon prominent), sendet der Driver einen Idempotency-Key-Header der Form esa-<account_id>-<post_id>-<md5_prefix>. Damit verhindert der Remote-Server, dass identische Posts bei einem versehentlichen Retry doppelt erscheinen. Auf der ESA-Seite tut zusätzlich QueueRepository::hasActiveJob denselben Dienst.

Roadmap (Phase 5+)

Was als Nächstes kommt.

Phase 5 — Per-Post-UI

Phase 6 — Scheduling

Phase 7 — White-Label

Phase 8 — Bulk-Ops & Analytics

Technische Referenz

Architektur, DB-Schema, REST-Endpoints — für Entwickler, die eigene Driver oder Integrationen bauen wollen.

Architektur in Stichworten

• Autoload: PSR-4 unter EasySocialAutopilot\ aus src/ (siehe composer.json).
• Bootstrap: Plugin::boot() läuft auf plugins_loaded, registriert Loader, AdminMenu, OAuthHandler, RestApi, QueueProcessor, PostHookListener.
• Channel-Driver-Contract: abstrakter ChannelDriver mit acht abstract methods — getId, getName, getIcon, getOAuthStartUrl, handleOAuthCallback, refreshIfNeeded, validate, send. Jeder neue Channel ist eine konkrete Subklasse.
• Registry-Singleton: Channels\Registry::getInstance() feuert beim ersten Zugriff die Action esa_register_channels, an die sich Built-ins (via Channels\Bootstrap) und Drittanbieter ihre eigenen Drivers hängen können. Das ist der offizielle Extension-Point.
• HttpClient: zentraler Wrapper um wp_remote_*. Eingebaute Retry-Semantik für 429 und 5xx (Honoring Retry-After), Multipart-Upload, JSON-Body.
• PostHookListener: Hook auf transition_post_status. Honoriert _esa_skip_distribution und _esa_selected_accounts. Idempotent via hasActiveJob.
• DTOs: ChannelAccount, SendResult — immutable, mit fromDbRow / toPublicArray / success / failure-Factories.
• Migrations: dbDelta-basiert, idempotent, versioniert über wp_options['esa_db_version'].

Wie der Bootstrap die 20 Driver registriert

Channels\Bootstrap::registerBuiltins hängt sich an esa_register_channels und instanziiert die mitgelieferten Drivers. Vereinfacht:

Bedingung für einen Custom-Driver: extends ChannelDriver, alle acht abstract methods implementiert, getId() returnt einen global eindeutigen Slug. Beim nächsten UI-Reload erscheint die Karte im Channels-Grid.

DB-Schema (kompakt)

REST-Endpoints (Namespace esa/v1)

Browser-Callback-Endpoint (keine REST-Route, sondern admin-post.php):

Cron

Glossar

Kurzdefinitionen der wichtigsten Begriffe aus diesem Handbuch.

Über dieses Plugin

EasySocialAutopilot ist eine Open-Source-Initiative, getragen von Uwe Hiltmann (Internet-Unternehmensberater & KI-Consultant) und Contributors. Ziel: eine WordPress-Social-Distribution-Pipeline, die ohne Phone-Home, ohne Lizenz-Server und ohne SaaS-Abhängigkeit funktioniert.

Feedback, Bug-Reports und Pull-Requests sind willkommen — nutze dafür den Issue-Tracker im GitHub-Repository.

Stand dieses Handbuchs: Phase 4. Auto-Enqueue produktiv, 20 Channel-Drivers registriert, 11 davon voll funktional posting-fähig, 5 Posting-blockiert pending external approval, 1 description-only (YouTube), 1 token-only (Medium), 1 Platzhalter (XING). Phase 5 bringt das Per-Post-UI im Gutenberg-Editor.