Dipper fast YAML Parser - YAML Files lesen und schreiben

Download Dipper

Dipper ist ein open Source PHP Programm nach BSD3-License, um YAML-Dateien lesen oder schreiben zu können. Bei Dipper handelt es sich um ein einziges PHP Programm, welches nützliche Funktionen für den YAML-Standard bereit hält. Sie können Dipper von GitHub herunterladen. Der Link (oben in der Seite) bringt Sie sofort zum Projektverzeichnis von Dipper und Sie können dort auch die englische Dokumentation nachlesen.

Download Yaml Dipper

Für den Download des YAML-Parsers von GitHub, wählen Sie bitte den grünen Code-Button (rechts oben) und nutzen den ZIP-Download.

Dipper installieren

Dipper ist wirklich simpel installiert. Die PHP-Datei (master.zip zuvor bitte entpacken) von GitHub kann am besten in einem separatem Ordner Ihres Projektes abgespeichert werden, z.B.:

/dipper/Dipper.php

Es handelt sich dabei um ein einziges praktisches PHP-Script, das alle Funktionen kapselt. Alternativ können Sie Dipper.php auch in der root Ihres Programmverzeichnis ablegen, müssen dann jedoch den Befehl require('Dipper.php') wie gezeigt anpassen.

Dipper einbinden

Binden Sie Dipper in Ihr PHP Programm ein, dabei sollte der Befehl require('dipper/Dipper.php') Dipper aus dem Verzeichnis laden, in dem Sie das PHP-Script abgelegt haben (in diesem Beispiel aus dem Ordner dipper).

001  require('dipper/Dipper.php');
002  use secondparty\Dipper\Dipper as Dipper;
003  $config = file_get_contents('config.yaml');
004  $ymlconfig = Dipper::parse($config);

Hinweis: Die Methode parse() ist in Dipper als static definiert und wird daher nicht mit new Dipper(); verwendet bzw. gerufen.

YAML Datei lesen

Mit diesem Codeschnipsel liest Dipper die Datei config.yaml ein und bereitet den Inhalt als PHP-Objekt auf. Die YAML-Datei liegt dabei im selben Ordner wie auch Ihr PHP-Programm.

001  title:       Das ist der Titel
002  description: Eine Beschreibung
003  author:      CMSWorkbench
004  date:        2022-03-11

Hätte die config.yaml beispielsweise den obigen Inhalt, dann können Sie diesen aus der Variablen $ymlconfig wie folgt auslesen:

001  echo $ymlconfig['title'];          // ergibt: Das ist der Titel
002  echo $ymlconfig['description'];    // ergibt: Eine Beschreibung
003  echo $ymlconfig['author'];         // ergibt: CMSWorkbench
004  echo $ymlconfig['date'];           // ergibt: 2022-03-11

und würden das entsprechende value zum Key title erhalten.

YAML-Dateien können Sie manuell mit fast jedem ASCII Editor selbst erstellen. Für die Strukturierung der Daten in YAML ist die Einrücktiefe entscheidend, als Standard werden 2 Leerzeichen bis 4 Leerzeichen erwartet. Grundsätzlich sollen sich Strukturen bzw. Ebenen durch identische Einrückungen identifizieren.

YAML Datei strukturieren (Dictionary Style, Object Mapping)

Das vorangegangene Beispiel ist wenig strukturiert. Wollten Sie jedoch Unterstrukturen entwickeln, können Sie sich an dem folgenden Beispiel einer YAML-Datei orientieren.

001  title:        Das ist der Titel
002  description:  Eine Beschreibung
003  author:
004    first-name: Oliver
005    last-name:  Lohse
006  date:         2022-03-11

Wollen Sie erneut das Value zu author ermitteln, dann müssen Sie den folgenden PHP-Befehl nutzen, um die YAML-Struktur zu lesen.

001  echo $ymlconfig['author']['first-name'];        // ergibt: Oliver
002  echo $ymlconfig['author']['last-name'];         // ergibt: Lohse

Dieser Style wird im übrigen Dictionary- oder Mapping-Style genannt, denn mit author erhalten Sie ein so genanntes iterierbares Objekt in PHP, welches Sie mit foreach weiter verarbeiten können. Der Key author muss für diesen Zweck leer bleiben, da sein Value ein weiteres Array ist!

Zeilenumbruch und Mehrzeiligkeit in YAML

Zunächst können Sie den Content innerhalb einer einzelnen Zeile unterbringen, für wenige Inhalte durchaus ausreichend. Haben Sie jedoch mehr Inhalt, kann eine Zeile etwas unübersichtlich werden. YAML bietet die Möglichkeit den Inhalt über mehrere Zeilen aufzuteilen.

001  title:        Das ist der Titel
002  description:  Eine Beschreibung
003  author-bio: >
004    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
005    tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
006  date:         2022-03-11

Leiten Sie mehrzeiligen Content mit dem > Zeichen oder mit der | Pipe ein und tragen in der folgenden Zeile den Inhalt eingerückt darunter.

Als Einrücktiefe setzt die YAML-Syntax mindestens 2 Leerzeichen voraus. Wichtig ist jedoch, das alle Objekte und Elemente einer Strukturebene die gleiche Einrück-Tiefe aufweisen, sonst quittiert der YAML-Parser diesen Fehler mit einem Abbruch.

YAML Datei schreiben mit Dipper

Der YAML Parser Dipper ist natürlich auch in der Lage eine YAML-Datei zu erzeugen und diese auf die Festplatte zu schreiben. Im folgenden Beispiel wird ein YAML-File für ein Affiliate-Modul durch Dipper erzeugt, zunächst mit lediglich zwei Inhalten: Produkt A und Produkt B.

001  require('dipper/Dipper.php');
002  use secondparty\Dipper\Dipper as Dipper;
003  $affiliate = 
004      [
005          'affiliate'=>
006          [
007              'produkt-a'=>
008              [
009                  'title'         =>'Affiliate Produkt A',
010                  'description'   =>'Eine Beschreibung des Affiliate-Produkts A',
011                  'logo'          =>'img/produkt-a.png',
012                  'label'         =>'kaufen...',
013                  'link'          =>'www.amazon.de'
014              ],
015              'produkt-b'=>
016              [
017                  'title'         =>'Affiliate Produkt B',
018                  'description'   =>'Eine Beschreibung des Affiliate-Produkts B',
019                  'logo'          =>'img/produkt-b.png',
020                  'label'         =>'kaufen...',
021                  'link'          =>'www.amazon.de'
022              ]
023          ]
024      ];
025  
026      file_put_contents('affiliate.yaml', Dipper::make($affiliate));

Starten Sie den obige Programm-Code, erzeugt Dipper die entsprechende YAML Datei affiliate.yaml im root-Verzeichnis des PHP Programms.

001  ---
002  affiliate:
003    produkt-a:
004      title: Affiliate Produkt A
005      description: Eine Beschreibung des Affiliate-Produkts A
006      logo: img/produkt-a.png
007      label: kaufen...
008      link: 'www.amazon.de'
009    produkt-b:
010      title: Affiliate Produkt B
011      description: Eine Beschreibung des Affiliate-Produkts B
012      logo: img/produkt-b.png
013      label: kaufen...
014      link: 'www.amazon.de'

Die so entstandene Datei können Sie dann natürlich wie in den vorangegangenen Beispielen leicht erneut mit Dipper einlesen.

Die automatische Erzeugung von YAML Files ist für Installationsroutinen ideal. Dipper führt zudem automatisch einen mehrzeiligen Content mit > ein, wenn er erkennt, das der Inhalt zu lang für die einzeilige Darstellung wird.

Weiterführende Links

• opensource.org: BSD-3-Clause
• yaml.org: Yaml 1.2 Syntax
• yamlCMS.de: yamlCMS