Styleguide: Ext. Programmierung

Aus Imperia Support Wiki

Sie wollen für BerlinOnline ein Softwareprojekt umsetzen und wollen dies direkt auf den Servern von BO betreiben? Dann sind gewisse Richtlinien bei der Programmierung zu beachten.

Grundsätzlich

Ihre Anwendung erzeugt valides (X)HTML, verwendetet valides CSS für das Layout und ggf. noch Javascript für nicht-relevante Zusatzfunktionen. Als Programmiersprache verwenden Sie PHP, und als Datenbank verwenden Sie MySQL. Für das Schreiben von DB-Zugriffen sollten Sie aber einen Abstraktionslayer wie z.B. PDO verwenden, um ggf. später die DB wechseln zu können.

Ihr PHP erzeugt auch im Strict-Mode keine Meldungen, also weder Errors noch Notices.

SVN Versionierung

Ihre Programmierung wird in ein SVN-System eingecheckt. BO wird Ihnen dafür eine SVN-Adresse zur Verfügung stellen.

Bitte beachten Sie, dass alle für das Projekt relevanten Dateien in das SVN eingecheckt werden müssen. Dies beinhaltet auch die DB-Struktur. Sollten Sie nachträglich Änderungen an der DB-Struktur vornehmen, so legen Sie bitte dafür zwei Dateien an.

  1. JJJJ-MM-TT_DBNAME.patch.sql für die Änderungen, und
  2. JJJJ-MM-TT_DBNAME.data.sql für den Gesamtzustand der DB.

Damit ist es allen Entwicklern möglich, den aktuellsten Stand der Datenbank wiederherzustellen.

Dateisystem

Für die Basiseinrichtung Ihres Programmierprojekts existiert ein Demo-ZIP, in dem beispielhaft die Ordnerstruktur zu sehen ist.

 + _bin/ (Ordner für Programmbibliotheken, nicht via HTTP zugreifbar)
 + _css/ (Ordner für Stylesheets und Grafiken, die von Stylesheets verwendet werden)
 + _img/ (Ordner für Bilder, die im Content verwendet werden)
 + _inc/ (Ordner für (HTML)-Schnipsel, die von Templates verwendet werden)
 + _tmpl/ (Ordner für Templates, nicht via HTTP zugreifbar)
 + . (Ordner für PHP, HTML, JS)

Neben den bekannten Dateiendungen existieren folgende Spezialendungen:

  • .phplib für PHP-Bibliotheken
  • .inc für (HTML)-Schnipsel
  • .tmpl für HTML-Templates - ggf. kann aber aber auch als Dateiendung .html etc. verwendet werden.

Programmierung

BO setzt folgende Frameworks ein, für die Sie sich entscheiden müssen:

  • Agavi
  • Zend Framework
  • Das BO-eigene Framework

In dem BO-eigenen Framework stehen Ihnen viele vorgefertigten Klassen bei der Entwicklung zur Seite. Eine Übersicht über alle unsere PHP-Funktionen finden Sie unter http://support.berlin.de/doc/php/files/debug-class-phplib.html. Besonders wichtig sind folgende Klassen:

  • toolshed für grundlegende Funktionen
  • debug für das Anzeigen von Debugging-Meldungen
  • messages für das Sammeln und Anzeigen von Meldungen in Applikationen
  • easy_db für DB-Zugriffe
    • table__base für Basiszugriffe auf Tabellen mit RO- / RW-Verbindungen
  • form2 für das Erzeugen von Formularen
  • easy_pager für das Erzeugen von Elementen zum Blättern in Ergebnissen
  • table zur Anzeige von Ergebnissen in Tabellen
  • xml_api für Zugriffe auf eine XML-API
  • reqcache für requires mit Cache
  • captcha für das Erzeugen von Captchas

Alle Funktionen innerhalb Ihrer Anwendungen müssen Klassen-Methoden sein - außer, es gibt einen besonderen Grund, dies nicht zu tun. Generell empfehlen wir zur Verbesserung der Lesbarkeit / Nachvollziehbarkeit sowieso einen objektorientierte Aufbau.

Die Benennung von Funktionen / Variablen sowie die Kommentare muss in Englisch gehalten sein.

Alle Ihre Klassen sind zu Abschluss des Projekts nach Maßgabe der Natural Docs Inline-Dokumentaion (http://www.naturaldocs.org/documenting.html) gepflegt. Keine Bange, dies ist relativ einfach und für Sie nur mit minimalen Mehraufwand verbunden. Als Sprache kann Englisch gewählt werden.

Testing

Für wichtige Klassen schreiben Sie bitte Unit-Tests, um die Funktionsweise der Klasse überprüfbar zu machen. BO setzt bei PHP für diese Aufgabe phpUnit ein.

Datenbankzugriffe

Für Datenbankzugriffe empfehlen wir die Verwendung unserer hauseigenen DB-Klasse. So oder so müssen Sie bestimmte Randbedingungen beachten.

Da BO für alle Datenbanken eine Replikation aufgesetzt hat, ist es notwendig, Lese- von Schreibzugriffen zu trennen. Readonly-Zugriffe werden von einem anderen Host abgearbeitet als Read/Write-Zugriffe.

In der Regel wird für jede Datenbank ein eigener Host verwendet - Sie können sich also nicht darauf verlassen, mit localhost eine erfolgreiche Verbindung zu Ihrer DB aufbauen zu können.

Templates

Es gibt in einer Applikation nur einem Ort, an dem HTML erzeugt wird: Das Template! Keine Ihrer Funktionen darf HTML bzw. entsprechend gequoteten Output liefern. Dies geschieht alles im Template. Ausnahmen erfordern einen zwingenden Grund.

Um Quoting-Probleme zu umgehen, sollten Sie standardmäßig an Stelle von echo() die hauseigene Funktion _echo(); (Bestandteil der toolshed.class.phplib) verwenden. Auf diese Weise vermeiden Sie XSS-Lücken bzw. Zeichensatzprobleme.

Wir empfehlen folgende Art und Weise, um Templates zu erzeugen:

 <!-- Beispiel -->
  <h4>Liste</h4>
  <ul>
    <?php foreach($array as $i): ?>
    <li><?php _echo($i['text']);?></li>
    <?php endforeach; ?>
  </ul>

Bei der Gestaltung erhalten Sie Hilfestellung durch den Layout-Server. Die genaue Funktion wird unter Styleguide:Techn. Integration via Durchschleifung erläutert. Kurz gefasst bedeutet dies aber, dass Sie sich um das Basislayout keine Gedanken machen müssen, weil es automatisch um Ihre Applikation herumgewickelt wird.

Javascript

Bitte bündeln Sie soweit möglich alle JS-Funktionen in einer zentralen, separaten JS-Datei. Damit erlauben Sie Caching und vermeiden gleichzeitig, dass Nicht-JS-UAs das JS runterladen müssen.