README

Ein Symfony-Bundle zur programmatischen Erstellung von ODT-Dokumenten gemäß OASIS OpenDocument 1.2 Spezifikation.

Vollständig ODF 1.2-konform - Erzeugt gültige ODT-Dateien, die von LibreOffice, OpenOffice und allen ODF-kompatiblen Anwendungen korrekt geöffnet und bearbeitet werden können.

🚀 Features

✅ ODF 1.2 konforme ODT-Dokumente - Vollständig kompatibel mit LibreOffice, OpenOffice und anderen ODF-Anwendungen
✅ Einfache API - Intuitive PHP-Objekte für Dokumentenstruktur
✅ YAML-zu-ODT Mapper - Konvertierung von YAML-Dateien in ODT-Dokumente
✅ Markdown-Unterstützung - CommonMark-Integration für Text-Formatierung
✅ Vollständige Test-Abdeckung - 126+ Tests, 346+ Assertions
✅ Symfony-Integration - Native Bundle-Integration mit Dependency Injection
✅ Code-Qualität - PHPStan Static Analysis und PHP-CS-Fixer konfiguriert
✅ Konfigurierbar - Bundle-Konfiguration über config/packages/supersonic.yaml
✅ Exception-Hierarchie - Strukturierte Custom Exceptions für besseres Error-Handling
✅ Logging-Integration - Optionales Logging für kritische Operationen
✅ Validierung - Umfassende Eingabeparameter-Validierung

🎯 Schnellstart

Einfaches Dokument erstellen

use Lindesbs\Supersonic\Odf\Model\Document;
use Lindesbs\Supersonic\Odf\Model\Meta;
use Lindesbs\Supersonic\Odf\Service\OdtGeneratorInterface;

class MyService
{
    public function __construct(
        private readonly OdtGeneratorInterface $odtGenerator
    ) {}

    public function createDocument(): void
    {
        $meta = new Meta();
        $meta->setTitle('Mein Dokument');
        $meta->setCreator('Mein Name');

        $document = new Document($meta);
        $document->addHeading('Überschrift', 1);
        $document->addParagraph('Dies ist ein Absatz.');

        $this->odtGenerator->generate($document, '/path/to/output.odt');
    }
}

YAML zu ODT konvertieren

php bin/console odt:from-yaml document.yaml --output=document.odt

Markdown-Formatierung

Das Bundle unterstützt Markdown-Formatierung in YAML-Paragraphs:

body:
  - type: paragraph
    text: "Dieser Text enthält **fett** und *kursiv* Formatierung."

Unterstützte Markdown-Features:

**text** oder __text__ → Fett
*text* oder _text_ → Kursiv
`code` → Code (als normaler Text)
Verschachtelte Formatierungen werden unterstützt

📚 Verwendung

Dokument-Struktur

Überschriften

$document->addHeading('Hauptüberschrift', 1);
$document->addHeading('Unterüberschrift', 2);

Absätze mit Formatierung

$paragraph = $document->addParagraph('');
$paragraph->addText('Normaler Text, ');
$paragraph->addText('fetter Text', true);
$paragraph->addText(' und ');
$paragraph->addText('kursiver Text', false, true);

Listen

// Ungeordnete Liste
$list = $document->addList(false);
$list->addItem('Punkt 1');
$list->addItem('Punkt 2');

// Nummerierte Liste
$orderedList = $document->addList(true);
$orderedList->addItem('Schritt 1');
$orderedList->addItem('Schritt 2');

Tabellen

$table = $document->addTable();
$table->addRow(['Header 1', 'Header 2']);
$table->addRow(['Daten 1', 'Daten 2']);

// Mit Spalten-Spanning
$row = $table->addRow();
$cell = $row->addCell('Überschrift über 2 Spalten');
$cell->setColumnSpan(2);

YAML-Format

meta:
  title: Dokument-Titel
  creator: Autor-Name
  date: 2024-12-07 10:00:00

body:
  - type: heading
    text: Überschrift
    level: 1

  - type: paragraph
    text: Absatz-Text

  - type: list
    ordered: false
    items:
      - Punkt 1
      - Punkt 2

  - type: paragraph
    text: "Markdown: **fett**, *kursiv*, `code`"

🧪 Tests

# Alle Tests ausführen
php vendor/bin/phpunit entwicklung/supersonic/tests/

# Mit Testdox-Output
php vendor/bin/phpunit entwicklung/supersonic/tests/ --testdox

Test-Statistik:

103+ Tests
284+ Assertions
Alle Tests erfolgreich ✅

📖 Beispiele

Das Bundle enthält umfassende Beispiele im examples/ Verzeichnis:

01-basic-document.php - Einfaches Dokument
02-formatted-text.php - Text-Formatierung
03-lists.php - Listen (geordnet/ungeordnet)
04-complete-document.php - Vollständiges Beispiel
05-yaml-to-odt.php - YAML-Konvertierung
06-tables.php - Tabellen

cd examples
php 01-basic-document.php

⚙️ Konfiguration

# config/packages/supersonic.yaml
supersonic:
    output_dir: '%kernel.project_dir%/var/output'
    default_creator: 'Meine Anwendung'
    default_title_prefix: 'Dokument: '
    markdown_enabled: true

🏗️ Architektur

Model-Layer (Value Objects)

Document - Root-Container
Meta - Metadaten
Paragraph, Heading, TextRun - Text-Elemente
OdfList, ListItem - Listen
Table, TableRow, TableCell - Tabellen

Writer-Layer

ContentXmlWriter - Erzeugt content.xml mit ODF 1.2 Elementen
StylesXmlWriter - Erzeugt styles.xml mit Style-Definitionen
MetaXmlWriter - Erzeugt meta.xml mit Dublin Core Metadaten
SettingsXmlWriter - Erzeugt settings.xml mit Dokument-Einstellungen
ManifestXmlWriter - Erzeugt META-INF/manifest.xml mit Paket-Manifest

Alle Writer verwenden die korrekten OASIS OpenDocument 1.2 Namespaces:

urn:oasis:names:tc:opendocument:xmlns:office:1.0
urn:oasis:names:tc:opendocument:xmlns:text:1.0
urn:oasis:names:tc:opendocument:xmlns:style:1.0
urn:oasis:names:tc:opendocument:xmlns:table:1.0
urn:oasis:names:tc:opendocument:xmlns:manifest:1.0
urn:oasis:names:tc:opendocument:xmlns:meta:1.0
http://purl.org/dc/elements/1.1/ (Dublin Core)

Service-Layer

OdtGenerator - Orchestriert die ODT-Generierung
YamlDocumentMapper - YAML-zu-Document Konvertierung
OdtPackageBuilder - Erstellt das ODT-ZIP-Paket

📋 OASIS OpenDocument 1.2 Konformität

Das Bundle erzeugt vollständig ODF 1.2-konforme Dokumente gemäß der OASIS OpenDocument 1.2 Spezifikation.

Paket-Format (ODF 1.2 Part 3)

✅ mimetype als erste Datei im ZIP, unkomprimiert (STORED)
✅ Korrekter MIME-Type: application/vnd.oasis.opendocument.text
✅ META-INF/manifest.xml mit manifest:version="1.2"
✅ Gültige ZIP-Struktur nach OASIS-Spezifikation

XML-Struktur (ODF 1.2 Part 1)

✅ Alle Root-Elemente mit office:version="1.2":
- office:document-content
- office:document-styles
- office:document-meta
- office:document-settings
✅ Korrekte Namespace-Deklarationen (OASIS URNs)
✅ Vollständige Dublin Core Metadaten

Unterstützte ODF-Elemente

Text-Elemente:

text:p - Absätze
text:h - Überschriften (H1-H6) mit text:outline-level
text:span - Formatierte Text-Runs (Bold, Italic)

Listen:

text:list / text:list-item - Geordnete und ungeordnete Listen
Verschachtelte Listen unterstützt

Tabellen:

table:table / table:table-row / table:table-cell
Spalten- und Zeilen-Spanning (table:number-columns-spanned, table:number-rows-spanned)

Styles:

office:automatic-styles - Automatisch generierte Text-Styles
office:styles - Dokument-Styles (Default, Heading)
XSL-FO kompatible Formatierungseigenschaften

Metadaten:

dc:title - Dokumenttitel
dc:creator - Autor/Ersteller
meta:creation-date - Erstellungsdatum (ISO 8601)

Validierung

Die generierten ODT-Dateien wurden erfolgreich getestet mit:

✅ LibreOffice (öffnet und bearbeitet korrekt)
✅ OpenOffice (kompatibel)
✅ Anderen ODF-kompatiblen Anwendungen

Referenzen:

🔧 Entwicklung

Dieses Bundle wurde mithilfe von Cursor entwickelt und basiert vollständig auf dem OASIS OpenDocument 1.2 Standard.

Voraussetzungen

PHP >= 8.1 (mindestens), PHP 8.4 empfohlen
Symfony >= 6.0 (mindestens), Symfony 8.0 empfohlen
Composer

Code-Qualität

Das Bundle verwendet verschiedene Tools zur Sicherstellung der Code-Qualität. Alle Commands sind als Composer-Scripts verfügbar:

ECS (Easy Coding Standard)

# Code-Style automatisch korrigieren
composer ecs-fix

# Code-Style prüfen (ohne Änderungen)
composer ecs-check

Rector

# Refactoring-Vorschläge anzeigen (Dry-Run)
composer rector

# Refactoring anwenden
composer rector-fix

PHP-CS-Fixer (Legacy)

# Code-Style automatisch korrigieren (Legacy)
composer cs-fix

# Code-Style prüfen (ohne Änderungen) (Legacy)
composer cs-check

PHPStan

# Static Analysis ausführen
composer phpstan

Tests

# Alle Tests ausführen
composer test

# Tests mit Coverage (benötigt Xdebug/PCOV)
composer test-coverage

Alle Quality-Checks

# Führt ECS, PHPStan und Tests aus
composer qa

Composer-Scripts

Das Bundle enthält folgende Composer-Scripts:

composer test - Führt Tests aus
composer test-coverage - Führt Tests mit Coverage aus
composer ecs-fix - Fixiert Code-Style mit ECS
composer ecs-check - Prüft Code-Style mit ECS
composer rector - Zeigt Refactoring-Vorschläge (Dry-Run)
composer rector-fix - Wendet Refactoring an
composer phpstan - Führt PHPStan Static Analysis aus
composer cs-fix - Fixiert Code-Style mit PHP-CS-Fixer (Legacy)
composer cs-check - Prüft Code-Style mit PHP-CS-Fixer (Legacy)
composer qa - Führt alle Quality-Checks aus (ECS, PHPStan, Tests)

Projekt-Struktur

src/
├── Odf/
│   ├── Model/          # Value Objects
│   ├── Writer/         # XML-Writer
│   ├── Package/        # ZIP-Builder
│   └── Service/        # Services
├── Command/            # Console Commands
├── DependencyInjection/ # Bundle-Konfiguration
├── Resources/          # Bundle-Ressourcen
└── SupersonicBundle.php # Bundle-Klasse

🔧 Error-Handling und Logging

Exception-Hierarchie

Das Bundle verwendet eine strukturierte Exception-Hierarchie für besseres Error-Handling:

SupersonicException (Basis-Exception)
├── OdtGenerationException      // Fehler bei ODT-Generierung
├── InvalidDocumentException    // Ungültige Dokument-Daten
├── YamlMappingException        // Fehler bei YAML-zu-Document Konvertierung
├── PackageBuilderException     // Fehler bei ZIP-Paket-Erstellung
└── ValidationException         // Validierungsfehler

Verwendung:

use Lindesbs\Supersonic\Exception\OdtGenerationException;
use Lindesbs\Supersonic\Exception\ValidationException;
use Lindesbs\Supersonic\Odf\Service\OdtGeneratorInterface;

try {
    $odtGenerator->generate($document, '/path/to/output.odt');
} catch (ValidationException $e) {
    // Validierungsfehler (z.B. ungültiger Pfad)
    echo "Validierungsfehler: " . $e->getMessage();
} catch (OdtGenerationException $e) {
    // Fehler bei der ODT-Generierung
    echo "Generierungsfehler: " . $e->getMessage();
}

Logging

Das Bundle unterstützt optionales Logging über LoggerInterface (PSR-3). Wenn ein Logger im Service-Container verfügbar ist, wird er automatisch injiziert:

use Psr\Log\LoggerInterface;

class MyService
{
    public function __construct(
        private readonly OdtGeneratorInterface $odtGenerator,
        private readonly LoggerInterface $logger
    ) {}
    
    public function createDocument(): void
    {
        // Logger wird automatisch von OdtGenerator verwendet
        $this->odtGenerator->generate($document, '/path/to/output.odt');
    }
}

Geloggte Operationen:

ODT-Generierung (Start, Erfolg, Fehler)
YAML-zu-Document Konvertierung
ZIP-Paket-Erstellung
Validierungsfehler

Log-Level:

info: Erfolgreiche Operationen
debug: Detaillierte Schritte während der Generierung
error: Fehler bei kritischen Operationen

Validierung

Das Bundle validiert automatisch Eingabeparameter:

OdtGenerator: Prüft, ob targetPath gültig ist und das Verzeichnis beschreibbar ist
YamlDocumentMapper: Prüft, ob Markdown-Converter vorhanden ist, wenn Markdown aktiviert ist
OdtPackageBuilder: Prüft ZIP-Archive-Fehler und gibt aussagekräftige Fehlermeldungen

📝 Lizenz

MIT License - siehe LICENSE Datei für Details.

📞 Support

Bei Fragen oder Problemen erstellen Sie bitte ein Issue im Repository.

Version: 0.5.0
Letzte Aktualisierung: 2025-12-06

lindesbs / supersonic-bundle

Maintainers

Details

README

🚀 Features

🎯 Schnellstart

Einfaches Dokument erstellen

YAML zu ODT konvertieren

Markdown-Formatierung

📚 Verwendung

Dokument-Struktur

Überschriften

Absätze mit Formatierung

Listen

Tabellen

YAML-Format

🧪 Tests

📖 Beispiele

⚙️ Konfiguration

🏗️ Architektur

Model-Layer (Value Objects)

Writer-Layer

Service-Layer

📋 OASIS OpenDocument 1.2 Konformität

Paket-Format (ODF 1.2 Part 3)

XML-Struktur (ODF 1.2 Part 1)

Unterstützte ODF-Elemente

Validierung

🔧 Entwicklung

Voraussetzungen

Code-Qualität

ECS (Easy Coding Standard)

Rector

PHP-CS-Fixer (Legacy)

PHPStan

Tests

Alle Quality-Checks

Composer-Scripts

Projekt-Struktur

🔧 Error-Handling und Logging

Exception-Hierarchie

Logging

Validierung

📝 Lizenz

📞 Support