DokuWiki Plugin Development

Ein Crashkurs

Andreas Gohr
CosmoCode GmbH

Über mich

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

Agenda

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

vorab

  • 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

DokuWiki Features

  • 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

DokuWiki Features

  • 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

Technologien

  • 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

Development Setup

  • 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

DokuWiki

  • checkout und install live zeigen

DokuWiki Directory Struktur

  • 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

Development

DokuWiki Plugins

  • 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

Plugin Typen

  • 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

Plugin Typen

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

Kitty Syntax Plugin

  • Neues Plugin “Kitty”
  • Neue Syntax: {{kitty 200 150}}
    placekitten.com_200_150_.jpg

Plugin Wizard

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

Git & GitHub

  • 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

Intermission - DokuWiki Parser

  • 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

Kitty Syntax Plugin

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

Translation

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

Konfiguration

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

Adding Styles

  • 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

Adding JavaScript

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

Unittests

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

Datenbanken

  • 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

Kitty Names

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

Kitty Names DB

  • 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

Intermission: Security!

  • 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

Security: XSS

  • 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);

Security: SQL-Injection

  • 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));

Security: CSRF

  • 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

Security: $INPUT

  • 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

Kitty Admin

  • Admin Interface um neue Namen in die Datenbank zu schreiben
  • Nutzung des Form-Mechanismus
  • Wir machen ein paar Sicherheitsfehler und beheben sie

Kitty Admin

  • 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

Offene Fragen

  • Fragen?
  • Was soll ich noch zeigen?

Learn more