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