notes.splitbrain.org

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
~~SLIDESHOW~~
====== 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 =====

  * 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

===== 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 =====

  * RTFM: https://www.dokuwiki.org/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}}%%''\\ {{http://placekitten.com/200/150?.jpg?nocache}}

===== Plugin Wizard =====

  * 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

===== 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 =====

{{ :s5:parser.png?400}}

  * 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 =====

  * //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

===== Translation =====

  * //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

===== Konfiguration =====

  * //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
===== 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 =====

  * //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! [[http://jshint.com/|jshint]] hilft beim korrgieren

----

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

===== Unittests =====

  * //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

===== 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
  * <code sql>CREATE TABLE kittens (
    name PRIMARY KEY,
    width  INT,
    height INT
);</code>
  * <code php>public static function getDB() {
        /** @var helper_plugin_sqlite $sqlite */
        $sqlite = plugin_load('helper', 'sqlite');
        $sqlite->init('kitty', __DIR__.'/db/');
        return $sqlite;
    }</code>
  * ü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
    * https://www.dokuwiki.org/devel:form
  * Wir machen ein paar Sicherheitsfehler und beheben sie

===== Kitty Admin =====

  * //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


===== Offene Fragen =====

  * Fragen?
  * Was soll ich noch zeigen?

===== Learn more =====

  * 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