Download the PHP package vtinnovations/schema-org without Composer

Schema.org Structured Data

Deutsch (Standardsprache) · English version

Contao-Bundle, das für jede Frontend-Seite automatisch strukturierte Daten als JSON-LD erzeugt und als zusammenhängenden @graph direkt vor </head> einfügt. Ziel sind Suchmaschinen und KI-Antwortmaschinen, die strukturierte Daten für Rich Results und Zitationen auswerten.

Inhalt

• Projektübersicht
• Status
• Unterstützte Versionen
• Systemvoraussetzungen
• Installation
• Lizenz aktivieren
• Backend
• Konfiguration
• Ausgabe im Frontend
• Funktionsübersicht
• Berechtigungen
• Lizenz- und Berechtigungsverhalten
• Sicherheitsmodell
• Betriebssicherheit
• Laufzeitverzeichnisse
• Externe Kommunikation
• Protokollierung
• Deployment
• Cache leeren
• Tests
• Fehlerbehebung
• Bekannte Einschränkungen
• Lizenz und Urheberrecht
• Weiterführende Dokumente

Projektübersicht

Das Bundle baut je Seitenaufruf einen einzelnen, quervernetzten JSON-LD-Graphen auf. Die Knoten verweisen über @id aufeinander, statt mehrere unabhängige <script>-Blöcke auszugeben.

Beigetragen werden, abhängig von Konfiguration und installierten Contao-Bundles:

Die Einfügung erfolgt bewusst über die Antwort und nicht über TL_HEAD: eigene fe_page-Templates lassen den TL_HEAD-Insert-Tag häufig weg, wodurch die Ausgabe unbemerkt verloren ginge.

Status

Produktiv einsetzbar. Version 2.0.0 ist eine vollständige Neuimplementierung der Lizenzprüfung; die Ausgabe strukturierter Daten ist gegenüber 1.x unverändert.

Aktualisierung von 1.x: Die frühere lokale Lizenzablage wird nicht weiterverwendet. Ein vorhandener Schlüssel wird beim ersten Öffnen der Einstellungen serverseitig übernommen und muss einmalig erneut aktiviert werden. Bis dahin gibt das Bundle keine strukturierten Daten aus.

Unterstützte Versionen

Systemvoraussetzungen

• Contao Managed Edition oder eine gleichwertige Symfony-Anwendung mit Contao 5.3+
• PHP-Erweiterungen: json, sodium (zwingend), intl (empfohlen)
• Ausgehende HTTPS-Verbindungen zum Lizenzserver
• Beschreibbares var/-Verzeichnis der Installation
• Erreichbarkeit der Installation über HTTPS unter einem echten Hostnamen

sodium ist Pflicht: ohne diese Erweiterung lässt sich keine Lizenz prüfen und das Bundle bleibt inaktiv.

Installation

Über den Contao Manager das Paket vtinnovations/schema-org hinzufügen, oder auf der Kommandozeile:

Das Paket muss dabei über Packagist oder ein in composer.json konfiguriertes Repository erreichbar sein.

Anschließend Datenbank aktualisieren und Cache leeren:

Die Migration legt die zusätzlichen Felder in tl_page, tl_news, tl_calendar_events und tl_faq an.

Dateisystemberechtigungen

Das Bundle legt unterhalb von var/ ein eigenes Arbeitsverzeichnis an und erwartet dort Schreibrechte für den Webserver- und den CLI-Benutzer. Es wird mit eingeschränkten Rechten erzeugt (Verzeichnis 0700, Dateien 0600) und darf nicht über den Webserver erreichbar sein. Das Verzeichnis gehört nicht in die Versionsverwaltung.

Restriktive open_basedir- oder umask-Einstellungen müssen den Zugriff auf var/ erlauben.

Lizenz aktivieren

Die Lizenz wird unter System → Einstellungen im Abschnitt Schema.org Licence management verwaltet. Das ist die einzige Stelle im Backend, an der Lizenzdaten sichtbar sind oder verändert werden können.

1. Auf der Startseite (Seitentyp „Startpunkt einer Webseite“) im Feld Domainname die Domain eintragen, unter der die Website erreichbar ist.
2. Cache leeren, damit die Änderung wirksam wird.
3. System → Einstellungen öffnen, den Lizenzschlüssel eingeben und Lizenz prüfen und aktivieren wählen.

Nach erfolgreicher Aktivierung zeigt der Abschnitt den maskierten Schlüssel, das Paket, die Laufzeit, den aktiven Hostnamen, alle lizenzierten Hostnamen und die Lizenzversion.

Weitere Schaltflächen:

• Lizenz aktualisieren – holt den aktuellen Stand vom Lizenzserver. Schlägt der Aufruf fehl, bleibt die bisherige Lizenz unverändert bestehen.
• Lizenz entfernen – erfordert das Setzen des Bestätigungshakens und versetzt die Installation sofort in den unlizenzierten Zustand.

Der vollständige Schlüssel wird nach der Aktivierung nicht mehr im Backend angezeigt und nicht in das Eingabefeld zurückgeschrieben.

Ausführliche Beschreibung: Documentation/Lizenzierung.md

Backend

Das Modul Schema.org ist reine Anzeige: Es erzeugt keine Daten, speichert nichts und enthält keine Lizenzfunktionen. Ohne gültige Lizenz zeigt es einen Hinweis mit Verweis auf die Einstellungen.

Konfiguration

Startseite – websiteweite Angaben

Einzelseite – Übersteuerungen

Nachrichten, Termine, FAQ

Eigenes JSON-LD wird ohne @context erwartet; ein mitgegebener @context wird entfernt. Ungültiges JSON wird stillschweigend übergangen und bricht die Seite nicht ab.

Ausgabe im Frontend

Ausgegeben wird ausschließlich, wenn alle folgenden Punkte zutreffen:

• gültige Lizenz für den aufgerufenen Hostnamen,
• Frontend-Anfrage mit aufgelöster Seite,
• Antwort ist HTML und enthält </head>,
• weder die Website noch die Seite ist deaktiviert,
• mindestens ein Knoten wurde erzeugt.

Trifft eine Bedingung nicht zu, verhält sich Contao exakt wie ohne dieses Bundle. Es werden keine Inhalte verändert, entfernt oder umgeleitet.

Funktionsübersicht

Berechtigungen

Jede lizenzverändernde Aktion prüft serverseitig zuerst die Modulberechtigung und anschließend das Contao-Anfrage-Token, bevor irgendetwas geschieht.

Lizenz- und Berechtigungsverhalten

Das Produkt wird als dauerhaft kostenfreie Ausgabe verteilt, benötigt aber eine ausgestellte und aktivierte Lizenz. Es gibt keinen anonymen Betrieb, keinen automatisch startenden Testzeitraum und keine lokal erzeugbare Lizenz.

Die Zuordnung erfolgt exakt je Hostname. example.com und www.example.com sind unterschiedliche Hosts; beide müssen lizenziert sein, wenn die Website unter beiden erreichbar ist.

Gespeicherte Konfiguration bleibt in jedem Zustand erhalten. Wird eine Lizenz später wieder aktiviert, sind alle Einstellungen unverändert vorhanden.

Sicherheitsmodell

• Lizenzentscheidungen fallen serverseitig. Die Ausgabe wird an mehreren Stellen unabhängig voneinander geprüft, nicht an einer zentralen Stelle freigeschaltet.
• Lizenzdaten liegen außerhalb des öffentlichen Verzeichnisses mit eingeschränkten Dateirechten.
• Empfangene Lizenzdaten werden auf Echtheit und Unverändertheit geprüft, bevor sie übernommen werden. Nachträglich veränderte lokale Daten werden erkannt und führen zum unlizenzierten Zustand.
• Der Austausch mit dem Lizenzserver erfolgt ausschließlich über feste HTTPS-Adressen mit Zertifikatsprüfung, ohne Weiterleitungen und mit begrenzten Zeitlimits und Antwortgrößen.
• Der öffentlich erreichbare Endpunkt für serverseitig ausgelöste Aktualisierungen akzeptiert nur kryptografisch authentifizierte Anfragen. Herkunftsangaben wie Origin, Referer oder Absender-IP gelten nicht als Nachweis.
• Wiederholt eingespielte oder veraltete Aktualisierungen werden abgewiesen; eine ältere Lizenz kann eine neuere nicht ersetzen.
• Das Paket enthält keinerlei Signaturschlüssel und keine wiederverwendbaren Zugangsdaten.
• Es gibt keine Umgebungsvariable und keine Einstellung, mit der sich die Prüfung abschalten lässt.

Ausführliche Darstellung: Documentation/Sicherheit.md

Kein Schutzmechanismus ist unumgehbar. Die beschriebenen Maßnahmen erschweren Manipulation und machen sie erkennbar; sie sind keine Garantie.

Betriebssicherheit

• Änderungen am Lizenzzustand erfolgen unter einer Sperre und werden erst wirksam, nachdem das Ergebnis erneut eingelesen und geprüft wurde. Schlägt diese Nachprüfung fehl, wird der vorherige Zustand zurückgeschrieben.
• Ein nicht erreichbarer Lizenzserver, eine Zeitüberschreitung oder eine fehlerhafte Antwort verändern eine funktionierende Lizenz nicht.
• Fehler einzelner Knotenlieferanten werden abgefangen; eine Seite wird dadurch nie unvollständig ausgeliefert oder abgebrochen.
• Das Bundle löscht, verschiebt und überschreibt keine Inhalte, Dateien oder Einstellungen der Installation.

Laufzeitverzeichnisse

Das Verzeichnis muss beschreibbar, privat und von Sicherungen erfasst sein. Bei mehreren Anwendungsservern muss es auf gemeinsam genutztem Speicher liegen, damit Sperren und Wiederholungsschutz installationsweit greifen.

Externe Kommunikation

Das Bundle kommuniziert ausschließlich mit dem Lizenzdienst von V&T Innovations unter www.v-t.one über HTTPS. Die Adressen sind fest im Code hinterlegt und lassen sich nicht per Konfiguration umlenken.

Meldungen werden erst nach dem Senden der Antwort ausgeführt und beeinflussen weder die Auslieferung noch die Lizenzgültigkeit. Ein Fehlschlag bleibt folgenlos und wird innerhalb derselben Sitzung nicht wiederholt.

Für Firewalls: ausgehend muss www.v-t.one über HTTPS erreichbar sein. Eingehend muss der öffentliche Aktualisierungs-Endpunkt des Bundles erreichbar bleiben. Sein genauer Pfad lässt sich in der Installation ermitteln:

Protokollierung

Protokolliert werden ausschließlich betriebliche Angaben: Vorgang, technische Anfragekennung, HTTP-Status, Dauer, Ergebniskategorie und die übernommene Lizenzversion.

Nicht protokolliert werden Lizenzschlüssel, Prüfsummen, Signaturen, übertragene Daten, Antwortinhalte oder daraus abgeleitete Werte. Der Lizenzschlüssel erscheint weder in der Browserausgabe noch in Fehlermeldungen oder Diagnosen.

Deployment

Zusätzlich sicherstellen:

• var/schema-org/ ist beschreibbar und wird nicht zwischen Installationen kopiert,
• der Contao-Cron läuft (Weberoberfläche oder contao:cron),
• ausgehende HTTPS-Verbindungen sind erlaubt,
• bei Reverse-Proxy-Betrieb sind trusted_proxies und trusted_hosts in Symfony korrekt gesetzt, da der Hostname der Installation daraus abgeleitet wird.

Der Lizenzzustand ist an den Hostnamen gebunden. Beim Klonen einer Installation auf eine andere Domain wird die kopierte Lizenz dort nicht anerkannt; sie muss für den neuen Hostnamen ausgestellt werden.

Cache leeren

Im Contao Manager steht dafür ebenfalls die Funktion zum Leeren des Anwendungs-Caches zur Verfügung.

Tests

Das Paket bringt eine Testsuite mit. Mit installierten Entwicklungsabhängigkeiten läuft sie über PHPUnit:

Für Umgebungen ohne Entwicklungsabhängigkeiten steht ein eigenständiger Testlauf bereit, der nur PHP benötigt:

Erstellen eines auslieferbaren Pakets samt Prüfungen und SHA-256-Manifest:

Der Erstellungslauf bricht ab, wenn die Testsuite fehlschlägt oder das Paket keine gültigen Prüfdaten enthält.

Fehlerbehebung

Bekannte Einschränkungen

• Installationen unter einer IP-Adresse oder einem einteiligen Hostnamen wie localhost können nicht lizenziert werden und geben keine strukturierten Daten aus.
• Die Zuordnung erfolgt exakt je Hostname; Unterdomains und die Form mit www sind eigenständige Hosts.
• Ist auf keiner Startseite ein Domainname hinterlegt, wird der aktuelle, von Symfony geprüfte Hostname der Anfrage verwendet. Für ein vorhersagbares Verhalten sollte der Domainname gesetzt sein.
• Bei mehreren Anwendungsservern ohne gemeinsam genutztes var/ wirken Sperre und Wiederholungsschutz nur je Server.
• Auf lizenzierten Seiten wird nach dem Ausliefern der Antwort je Aufruf eine Nutzungsmeldung gesendet. Auf stark frequentierten Websites ist das bei der Kapazitätsplanung zu berücksichtigen.
• Eigenes JSON-LD wird nicht gegen schema.org validiert.
• Die Backend-Vorschau erzeugt für einzelne Seitentypen keine absolute URL und kann diese daher nicht darstellen.
• Es gibt genau eine Lizenzstufe. Eine Unterscheidung zwischen Free und Pro existiert in diesem Produkt nicht.

Lizenz und Urheberrecht

Paket: vtinnovations/schema-org Lizenz: LGPL-3.0-or-later Copyright: V&T Innovations

Die Softwarelizenz nach LGPL und die produktseitige Lizenzierung sind zwei verschiedene Dinge: Die LGPL regelt die Rechte am Quellcode, der Lizenzschlüssel schaltet die Ausgabe strukturierter Daten für einen bestimmten Hostnamen frei.

Weiterführende Dokumente

• English version
• Documentation/Lizenzierung.md – Lizenzverwaltung im Detail
• Documentation/Sicherheit.md – Sicherheitsmodell