DokuWiki Plugin Development

Andreas Gohr
CosmoCode GmbH

• Andreas Gohr
• 2004 Diplom an der FHTW Berlin in Angewandte Informatik
• DokuWiki lead developer
• splitbrain.org
• twitter.com/splitbrain
• github.com/splitbrain

• DokuWiki Überblick
• Development Setup
• Plugin Development (Praxis)
  • Syntax Plugin
    • Konfiguration, Translation, CSS, JavaScript, Unittests
  • Helper Plugin
  • Sicherheit
  • Admin Plugin
• Fragen

• wenn etwas unverständlich ist: bitte gleich fragen
• ich setze grundlegende Programmierkenntnisse voraus
  • der Code wird extrem simpel sein und sollte auch ohne vorherige PHP-Kenntnisse verständlich sein
• gerne nebenbei mitmachen, ausprobieren oder die Doku überfliegen
• die Folien sind online, Notizen aber eventuell trotzdem hilfreich

• Syntax nach HTML rendern
• Medieninhalte
• Organisation in Namensräumen
• Versionierung (Vorhalten älterer Kopien)
• Änderungsprotokolle global und pro Seite
• Suche

• Features nebenbei auf dokuwiki.org zeigen

• Nutzerverwaltung und Gruppen
  • intern und extern (Active Directory, LDAP, MySQL, etc)
• ACLs (READ, EDIT, UPLOAD, DELETE)
• Lokalisation
• Templates (aka. Skins aka. Themes)
• Plugins!!!
• keine Datenbank
• https://www.dokuwiki.org/features

• PHP 5.3+
  • libraries für JSON, INPUT handling, E-Mail sending, HTTP Client, RSS Parser und Writer, Form Generation, Security, Syntax Highlighting, Zip/TGZ archives…
• jQuery und jQuery UI
• Integrierter LESS compiler für CSS

• PHP
  • Windows: XAMPP etc. oder microapache von DokuWiki.org
  • Debian: apt-get install php5
  • Mac: *schulterzuck*
• Webserver
  • Windows: XAMPP etc. oder microapache von DokuWiki.org
  • Debian: apt-get install apache
  • Mac: *schulterzuck*
  • alternativ: php -S localhost:8000 index.php

• kurz zeigen wo der microapache runtergeladen werden kann

• Development Version von DokuWiki nutzen!
• git clone https://github.com/splitbrain/dokuwiki.git
• Wer microapache nutzen will, stable+webserver runterladen, dokuwiki ordner wegschmeissen und durch git checkout ersetzen!
• http://localhost/dokuwiki/install.php aufrufen und initiale Config anlegen
• Einloggen, Seite editieren, speichern

• checkout und install live zeigen

• bin - command line tools
• conf - Konfigurationsdateien
• data - Seiten, Medien, Historie, Suchindex, etc…
• inc - core files
• lib - templates, plugins, “static files”
• vendor - 3rd party libs
• _test - unittests - wer das nicht hat, hat keine devel Version!

• ls in die Verzeichnisse machen und erklären

• RTFM: https://www.dokuwiki.org/development

• Code um DokuWiki um Funktionalitäten zu erweitern (oder bestehende zu ändern)
• Fertige Plugins können über den Extension Manager installiert werden
• Einige Core-Funktionen wurden als Plugin implementiert
• Ordner in lib/plugins/<plugin>/
• self-contained. PHP, CSS/LESS, JavaScript, Grafiken, etc.
• nutzt core funktionen → GPLv2

• zeigen, dass es schon plugins gibt. zb. extension

• Syntax Plugins - neue Syntax im Editor
• Action Plugins - reagiert auf “Hooks” um sich in Standardfunktionalität einzuklinken
• Admin Plugins - neue Management Funktionalitäten im Admin Menü
• Helper Plugins - Funktionen für andere Plugins
• Renderer Plugins - neue Ausgabeformate
• Auth Plugins - neue Authentifizierungmethoden
• Remote Plugins - neue remote API Funktionen

• Ein Plugin kann mehrere Typen beinhalten
• Ein Plugin kann dieselben Typen mehrmals enthalten (components)
  • zum Beispiel mehrere Syntax Komponenten um verschiedene Syntax hinzuzufügen

• Neues Plugin “Kitty”
• Neue Syntax: {{kitty 200 150}}
  

• https://pluginwiz.dokuwiki.org/
• Stellt ein Plugin Grundgerüst zur Verfügung
• ZIP auspacken nach lib/plugins/

• Wizard nutzen und syntax, admin komponente hinzufügen
• translation, config, unit tests includieren

• check in often, check in early!
• Github repo aufmachen
• initialen commit pushen
• jede signifikante Änderung pushen
• Angebot: wenn ihr eure Projekte rechtzeitig pusht, schau ich drüber und geb Feedback
• https://try.github.io – git in 15 minutes

• repo aufmachen und init commit machen
  • git init
  • git add .
  • git commit
  • github kram

• zweistufiges caching
• instructions werden nur bei Änderung der sourcen neu geparst
• re-renderering normalerweise nach maximal einem tag
• re-rendering kann von Plugins beeinflusst werden
• ~~NOCACHE~~ erzwingt rerendering

• code and tell
• mehr unter https://www.dokuwiki.org/devel:syntax_plugins
  • Syntax kann andere Syntax wrappen
  • Plugins können default syntax überschreiben
  • Syntax Plugins haben direkten Zugriff auf den Renderer
  • Syntax Plugins können verschiedene Renderer unterstützen
  • Syntax nutzt Regular Expressions (keine capture groups!)
  • http://www.regular-expressions.info/

• simples substition plugin
• block mode
• sortmode 155 - good middle ground, before most of the other syntax
• \{\{kitty \d \d\}\}
• placekitten.com bild ausgeben

• code and tell
• mehr unter https://www.dokuwiki.org/devel:localization
  • Basis-Sprache ist immer Englisch!
  • Plugins können zur Übersetzung auf https://translate.dokuwiki.org/ angemeldet werden

• title tag “cat” hinzufügen und übersetzen

• code and tell
• mehr unter https://www.dokuwiki.org/devel:configuration
  • Config wird in conf/local.php gespeichert
  • Config Namen können übersetzt werden

• Option zum Umschalten zwischen grayscale und farbe implementieren
• placekitten.com/g/20/20

• code and tell
• mehr unter https://www.dokuwiki.org/devel:css
  • DokuWiki hat built-in LESS parser (unterstützt evtl. nicht alle Features von lesscss.org)
  • (screen|print|all).(less|css) für verschiedene Ausgabemodi
  • Media-Queries nur in all.(less|css)!

• farbigen Rahmen definieren

• code and tell
• mehr unter https://www.dokuwiki.org/devel:javascript
  • jQuery ist nur als jQuery() verfügbar, nicht als $()
  • go easy on jQuery plugins!
  • JS wird komprimiert! jshint hilft beim korrgieren

• onclick handler mit alert('Meow') hinzufügen

• code and tell
  • mehr auf https://www.dokuwiki.org/devel:unittesting
  • phpunit.phar von https://phpunit.de/
  • Unit Tests in in _test
  • ./phpunit.phar --group plugin_kitty um nur Plugin zu testen
  • https://travis-ci.org/ für automatisierte tests on commit

• simpler test für die render methode
• checken, dass placekittenurl in $renderer→doc vorkommt

• DokuWiki hat keine Datenbank - manchmal möchte man aber eine
• Einfachste Lösung: SQLite
  • Standard seit PHP5
  • auf Linux manchmal als extra Paket: apt-get install php5-sqlite
  • eventuell in php.ini nicht eingeschaltet
  • google it
• DokuWiki hat das SQLite Plugin
  • abstrahiert SQLite2 und SQLite3
  • führt Migrationen durch
  • braucht eigentlich mal ein rewrite, tut aber was es soll

• Neue Syntax: {{kitty charly}}
• sucht in der DB nach dem Namen und zeigt die richtige Katze an
• sqlite Plugin via Extensionmanager installieren

• Plugin installieren

• code and tell
  • mehr auf https://www.dokuwiki.org/plugin:sqlite
  • plugin_load('helper', 'sqlite') liefert instanz
  • migrationen nur aufwärts (keine downgrades)
  • queries mit Platzhaltern (übernimmt korrektes Escaping)

• Anpassung der Syntax - keine unterstützung der alten syntax, .+?
• simples schema (name,width,height) und insertion von einigen Katzennamen

• CREATE TABLE kittens (
      name PRIMARY KEY,
      width  INT,
      height INT
  );

• public static function getDB() {
          /** @var helper_plugin_sqlite $sqlite */
          $sqlite = plugin_load('helper', 'sqlite');
          $sqlite->init('kitty', __DIR__.'/db/');
          return $sqlite;
      }

• übergeben der gefundenen width,height an den bisherigen renderer

• PHP hat einen schlechten Ruf was Sicherheitslücken angeht
• Nicht weil PHP per se unsicher ist, aber es ist besonders einfach sich in den Fuß zu schießen!
• https://www.dokuwiki.org/devel:security hat einige Tips und Beispiele

• Cross-Site-Scripting (jemand schiebt euch JavaScript unter)
• niemals Nutzereingaben unescaped ins HTML schreiben!
• Nutzereingaben kommen von: URL-Parametern, Wiki-Syntax, DB-Einträgen, etc.
• htmlspecialchars() steht in DokuWiki unter hsc() zur Verfügung
• $renderer->doc .= hsc($data);

• SQL-Injection (jemand schiebt eigenen Code in eure SQL-Abfragen)
• Daten müssen korrekt escaped werden
• sqlite Plugin macht das bei der Nutzung der ? Platzhalter
• $sqlite→query('SELECT * FROM foo WHERE bar = ?', array($data));

• Cross-Site-Remote-Forgery (jemand bringt euch dazu privilegierten Code auszuführen)
• DokuWiki's Form Mechanismus erzeugt einen Sciherheits-Token
• Token mit checkSecurityToken() prüfen bevor privilegierte Aufgaben durchgeführt werden

• PHP's Duck-Typing ermöglicht Angriffe die ihr nicht vorhergesehen habt
  • ihr erwartet ein Array, aber bekommt einen String oder umgekehrt
• DokuWiki hat ein globales $INPUT object für den Zugriff auf request Variablen
• $INPUT->post->str('foo'); gibt immer einen String zurück
• https://www.dokuwiki.org/devel:request_vars

• Admin Interface um neue Namen in die Datenbank zu schreiben
• Nutzung des Form-Mechanismus
  • https://www.dokuwiki.org/devel:form
• Wir machen ein paar Sicherheitsfehler und beheben sie

• code and tell
  • https://www.dokuwiki.org/devel:admin_plugins

• simples Form mit Name, height, width, submit
• REPLACE INTO kitten (name, width, height) VALUES ('$name', '$width', '$height');
• msg(“Inserting $name”)
• kein CSRF token check
• vulnerabilities zeigen (XSS wird von chrome abgefangen)
• fixen

• Fragen?
• Was soll ich noch zeigen?

• https://www.dokuwiki.org/development – Development Manual
• https://www.dokuwiki.org/mailinglist – Mailingliste hilft bei Fragen
• https://xref.dokuwiki.org/ – DokuWiki source code cross-reference
• http://stackoverflow.com/questions/tagged/dokuwiki – StackOverflow
• http://php.net/manual/en/index.php – PHP Dokumentation
• http://notes.splitbrain.org/s5:dwplugins – Folien