README

Bindet Rechtstexte (Impressum, Datenschutzerklärung, Datenschutzerklärung Social Media) aus dem eRecht24 Projekt Manager als Inhaltselement in Sulu ein. Das Bundle läuft mit Sulu 2.6 und Sulu 3.

Es wird eine aktive eRecht24-Mitgliedschaft benötigt, um API-Schlüssel zu erzeugen. Dieses Bundle wird nicht von eRecht24 entwickelt.

Funktionsweise

Das Bundle liefert einen fertigen Block-Typ: Redakteure wählen den Rechtstext und tragen den Projekt-API-Schlüssel direkt am Element ein. Keine Server-Konfiguration je Kunde nötig.
Die Sprache folgt standardmäßig dem Sprachzweig der Seite: eRecht24 liefert Deutsch und Englisch, das Element rendert die Sprache des Requests. Am Element lässt sich stattdessen fest Deutsch oder Englisch wählen, etwa wenn die deutsche Fassung überall gelten soll.
Texte werden dauerhaft in der Datenbank gespeichert. Ein Ausfall der eRecht24-API leert also niemals die Impressumsseite.
Beim ersten Rendern eines API-Schlüssels registriert sich die Installation selbst als Push-Client: Ändert der Kunde einen Text im Projekt Manager, ruft eRecht24 den Push-Endpunkt auf und das Bundle holt sofort die neue Fassung.
Beim Aktualisieren werden die betroffenen Seiten gezielt aus dem HTTP-Cache entfernt (Cache-Tags über den Sulu-CacheManager, z. B. mit Varnish oder dem Symfony HttpCache).
Als Sicherheitsnetz gilt ein Aktualisierungsintervall (Standard: 24 Stunden): Ist ein gespeicherter Text älter, wird er beim nächsten Seitenaufruf nachgeladen.
Kann ein Text nicht geliefert werden, bleibt die Website stumm, im Sulu-Preview erscheint dagegen ein Hinweis mit dem Grund (kein Schlüssel, Text im Projekt nicht angelegt, API nicht erreichbar).

Installation

composer require kreativsoehne/sulu-erecht24-bundle

Bundle registrieren (config/bundles.php), falls Flex das nicht übernimmt:

KreativSoehne\SuluErecht24Bundle\SuluErecht24Bundle::class => ['all' => true],

Route für den Push-Endpunkt einbinden. Sie gehört in den Website-Kontext, also in Sulu 2.6 nach config/routes_website.yaml und in Sulu 3 nach config/routes/sulu_website.yaml:

sulu_erecht24:
    resource: '@SuluErecht24Bundle/Resources/config/routing.yaml'

Datenbanktabellen anlegen:

bin/console doctrine:schema:update --force
# oder per Migration:
bin/console doctrine:migrations:diff && bin/console doctrine:migrations:migrate

Konfiguration

Nur der Entwickler-Schlüssel ist Pflicht (config/packages/sulu_erecht24.yaml):

sulu_erecht24:
    # Entwickler-Schlüssel (Plugin-Key). Wird von eRecht24 an Plugin-Autoren
    # vergeben (api@e-recht24.de) und identifiziert das Plugin, nicht das Projekt.
    developer_key: '%env(ERECHT24_DEVELOPER_KEY)%'

Alle Optionen:

Option	Standard	Beschreibung
`developer_key`	–	Entwickler-Schlüssel (Plugin-Key) von eRecht24
`default_api_key`	`null`	Optionaler Fallback-Schlüssel, falls ein Element keinen eigenen trägt
`auto_register`	`true`	Push-Client beim ersten Rendern eines Schlüssels automatisch registrieren
`author_mail`	`null`	Kontaktadresse, die bei der Push-Registrierung mitgesendet wird
`push_uri`	`null`	Feste URL des Push-Endpunkts; sonst wird sie über den Router erzeugt
`fetch_on_demand`	`true`	Texte beim Rendern nachladen, wenn nichts gespeichert oder der Stand veraltet ist
`refresh_interval`	`86400`	Sekunden, nach denen ein Text auch ohne Push aufgefrischt wird (`0` = nie)
`base_url`	`https://api.e-recht24.de/v2`	Basis-URL der API
`timeout`	`10.0`	Timeout für API-Anfragen in Sekunden

Das Inhaltselement einbinden

Der mitgelieferte Block-Typ wird per xi:include in die Blockliste einer Seitenvorlage aufgenommen (Pfad relativ zur XML-Datei anpassen):

<block name="blocks" default-type="text">
    <types>
        <xi:include href="../../../vendor/kreativsoehne/sulu-erecht24-bundle/src/Resources/config/blocks/legal_text.xml"
                    xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:properties/sulu:block/sulu:types/sulu:type)"/>
        <!-- eigene Block-Typen … -->
    </types>
</block>

Das Element bietet im Backend, jeweils in einer eigenen Zeile:

Rechtstext: Impressum, Datenschutzerklärung oder Datenschutzerklärung Social Media
Sprache: „Automatisch (Sprache der Seite)", „Deutsch" oder „Englisch"
Überschrift ausblenden: Schalter, der die H1 des eRecht24-Textes entfernt, wenn die Seite bereits eine eigene Überschrift hat
Einstellungen anzeigen: Schalter, der den eRecht24 API-Schlüssel ein- und ausblendet

Der Schlüssel steckt damit hinter einem Toggler und stört die redaktionelle Ansicht nicht. Technisch sitzt er in einer unbeschrifteten <section> des Block-Typs, die nur die Trennlinie beisteuert, gesteuert über visibleCondition="__parent.erecht24_show_settings". Das __parent ist nötig, weil Sulu Bedingungen innerhalb eines Blocks gegen die Formulardaten auswertet und erst der parentConditionDataProvider die Daten des Elements bereitstellt.

Wer den Schlüssel gar nicht im Backend pflegen möchte, hat zwei Alternativen:

Eigenes Einstellungsformular: Wer ohnehin ein projektweites settings_form_key-Formular pflegt, ergänzt darin ein text_line-Feld erecht24_api_key. Das Bundle liest es automatisch (content.settings.erecht24_api_key hat Vorrang vor dem Feld am Element). Achtung: Ein solches Formular gilt für alle Block-Typen der Eigenschaft und ersetzt deren Standard-Einstellungen.
Zentral konfigurieren: default_api_key in der Bundle-Konfiguration setzen, dann taucht im Backend gar kein Schlüsselfeld auf.

Gerendert wird der Block mit dem mitgelieferten Template oder mit eigenem Markup:

{# im Block-Dispatcher des Projekts #}
{% include '@SuluErecht24/blocks/legal_text.html.twig' with { content: block } only %}

{# oder direkt: #}
<div class="article">
    {{ erecht24_legal_text(
        block.erecht24_type,
        block.erecht24_api_key,
        null,
        block.erecht24_hide_headline ?? false
    ) }}
</div>

Eigener Seitentyp statt Inhaltselement

Für Seiten, auf denen ohnehin nie etwas anderes steht, ist ein eigener Seitentyp die robustere Wahl: Redakteure können nichts verschieben oder löschen. Das Bundle liefert dafür eine Kopiervorlage, keinen fertigen Seitentyp. Grund ist die Ansicht: Sie muss das base.html.twig des Projekts erweitern, und das kann ein Bundle nicht kennen. Ein mitgelieferter Seitentyp würde außerdem in jeder Installation in der Vorlagenauswahl auftauchen.

Zwei Dateien kopieren und anpassen:

cp vendor/kreativsoehne/sulu-erecht24-bundle/src/Resources/skeleton/pages/legal.sulu-3.0.xml config/templates/pages/legal.xml
cp vendor/kreativsoehne/sulu-erecht24-bundle/src/Resources/skeleton/pages/legal.html.twig templates/pages/legal.html.twig

Für Sulu 2.6 stattdessen legal.sulu-2.6.xml nehmen. Die beiden XML-Fassungen unterscheiden sich in genau zwei Zeilen, dem Controller und dem Typ der url-Eigenschaft, weil Sulu 3 dort route statt resource_locator verwendet. Die Twig-Ansicht ist für beide Versionen dieselbe.

Der Seitentyp bietet dieselben Felder wie das Element, dazu Titel, Adresse und einen optionalen Ergänzungstext. Element und Seitentyp lassen sich problemlos parallel verwenden: Beide greifen auf denselben gespeicherten Text zu, ein Push aktualisiert beide.

Ein Unterschied im XML ist beabsichtigt: Auf Seitenebene lautet die Bedingung visibleCondition="erecht24_show_settings == true", im Block dagegen __parent.erecht24_show_settings. Sulu wertet Bedingungen gegen die Formulardaten aus, und die sind auf Seitenebene die Seite selbst.

Twig-Funktionen

{# erecht24_legal_text(type, api_key = null, locale = null, hide_headline = false) #}
{{ erecht24_legal_text('imprint', content.erecht24_api_key) }}

{# Sprache übersteuern (Standard: Sprache des Requests) #}
{{ erecht24_legal_text('privacyPolicy', content.erecht24_api_key, 'en') }}

{# Metadaten, z. B. für eine Stand-Angabe #}
{% set info = erecht24_legal_text_info('privacyPolicy', content.erecht24_api_key) %}
{% if info.modified_at %}
    <p>Stand: {{ info.modified_at|date('d.m.Y') }}</p>
{% endif %}

Typen: imprint, privacyPolicy, privacyPolicySocialMedia (auch impressum, datenschutz, social-media werden verstanden).

Push-Registrierung

Beim ersten Rendern eines Elements registriert sich die Website selbst bei eRecht24 (maximal drei Clients je Projekt; das Bundle legt genau einen an und aktualisiert diesen). Der Push-Endpunkt /_erecht24/push prüft jede Anfrage gegen das dabei erhaltene Secret.

Für Sonderfälle gibt es Kommandos:

Kommando	Zweck
`sulu:erecht24:status [--test-push]`	Registrierungen und gespeicherte Texte anzeigen, optional Ping anfordern
`sulu:erecht24:sync [api-key] [--type=imprint]`	Texte abrufen; ohne Argument alle bekannten Schlüssel
`sulu:erecht24:register <api-key> [--push-uri=…]`	Registrierung vorab oder nach Domain-Wechsel auffrischen
`sulu:erecht24:unregister <api-key>`	Registrierung löschen, z. B. bei Stilllegung der Website

Läuft register auf der Kommandozeile, muss der Router die Live-Domain kennen: framework.router.default_uri konfigurieren, sulu_erecht24.push_uri setzen oder --push-uri übergeben.

Sprachen

Sprache der Rechtstexte

Bei „Automatisch" bestimmt der Sprachzweig der Seite die Ausgabe: de* liefert Deutsch, jede andere Sprache Englisch. Pflegt das eRecht24-Projekt die gewünschte Fassung nicht, wird die jeweils andere ausgegeben, damit eine Impressumsseite nie leer bleibt. Wer das nicht dem Zufall überlassen will, stellt am Element fest „Deutsch" oder „Englisch" ein.

Sprache der Oberfläche

Das Modul selbst spricht Deutsch und Englisch.

Im Backend folgen alle Feldbeschriftungen des Elements der eingestellten Sprache des Sulu-Nutzers, über <title lang="de"> und <title lang="en"> im Block-XML.
Auf der Kommandozeile und in Fehlermeldungen greift der Symfony-Übersetzer mit der Sprache der Anwendung (framework.default_locale). Die Kataloge liegen unter src/Resources/translations/sulu_erecht24.<locale>.yaml und werden von Symfony automatisch geladen.
Fehlermeldungen der eRecht24-API kommen zweisprachig zurück; das Bundle wählt die passende Fassung anhand derselben Sprache.

Eine weitere Sprache braucht nur eine zusätzliche Katalogdatei, etwa sulu_erecht24.fr.yaml, sowie <title lang="fr">-Einträge in einer eigenen Kopie des Block-XML.

Kompatibilität

Sulu	Symfony	PHP	Getestet mit
2.6	5.4 / 6.4 / 7.x	≥ 8.2	Sulu 2.6.25, Symfony 6.4, PHP 8.4
3.0	6.4 / 7.x	≥ 8.2	Sulu 3.0.8, Symfony 7.4, Doctrine ORM 3.6, PHP 8.5

Beide Versionen sind mit einer echten Installation geprüft: Container-Lint, Doctrine-Schema, Backend-Metadaten des Elements in beiden Sprachen, Abruf der Rechtstexte über die eRecht24-API, Rendering inklusive Sprachwahl und Überschriften-Schalter sowie der Push-Endpunkt.

Ein Unterschied betrifft nur die Einbindung der Route: Sulu lädt Dateien mit dem Suffix _website ausschließlich im Website-Kontext. In Sulu 2.6 gehört der Eintrag deshalb in config/routes_website.yaml, in Sulu 3 in config/routes/sulu_website.yaml. In beiden Fällen taucht die Route in bin/console debug:router nicht auf, weil die Konsole im Admin-Kontext läuft — das ist richtig so, der Push-Endpunkt gehört auf die Website.

Block-XML, Twig-Funktionen und Push-Endpunkt funktionieren in beiden Sulu-Generationen identisch, weil das Bundle die Content-Architektur nicht berührt. Das offizielle eRecht24-PHP-SDK wird nicht benötigt; die API v2 wird direkt über den Symfony-HTTP-Client angesprochen.

Lizenz

MIT

kreativsoehne / sulu-erecht24-bundle

Maintainers

Package info

Statistics

Security