Ob die Applikation an sich funktioniert kann man damit natürlich nicht herausfinden. Zum einen, weil ein Unit-Test ohne Sinn und Verstand geschrieben werden kann – Man sollte sich also nicht zu viel auf die hübsche Grüne Ausgabe einbilden – Zum anderen, weil ein Applikation (also die Summe mehrerer Komponenten (die evtl. alle fehlefrei funktionieren)) wiederum falsch zusammengesetzt worden sein kann.

Und dann gibt es da ja noch etwas, dass einem das Entwicklerleben immer wieder schwer macht:  Sonderfälle. Das sind die Dinge, die man nie mit einplant, die aber ständig auftreten und alles geplante gekonnt umschiffen. Diese kann man im Vorfeld einfach nicht mit Unit tests abfackeln (aber man kann prüfen, was passiert, wenn einer Eintritt …).

Daher: Unit tests sind und bleiben Unit tests (obwohl ich hierzu auch schon Interaktionstests zuzählen würde). Ein Systemtest kann nur schwer automatisiert durchgeführt werden. In Bezug auf Webapplikationen kommt man da mit Webtests schon recht weit, aber ums manuelle “durchklicken” wird man nie herum kommen. Sorry

Im letzten Teil habe ich erklärt, was Selenium ist, dass Webtests keine zu vernachlässigender Bestandteil eines profesionellen Deployments von Webapplikationen sind und wie man mithilfe der Selenium-IDE Tests erstellen kann.

Heute möchte ich euch zeigen, dass man verdammt schnell und sehr einfach einen Selenium Remote Control Server aufsetzen kann, und dieser mit einer ganzen Reihe von Sprachen direkt ansprechbar ist. In unserem Beispiel werden wir uns natürlich auf PHP konzentrieren.

Hier noch einmal die Artikelübersicht:

1. Sinnvolle Tests erstellen
2. Selenium Remote Control nutzen
3. Tests automatisieren und in Unittest-Frameworks einbinden

Testumgebung

Bevor man einen RC-Server aufsetzen kann, muss man sich entscheiden, welche Browser man überhaupt testen will. Verzichtet man auf Nieschenbrowser wie Konqueror und Camino, so wird ein Windows Server ausreichen.

Nachdem alo der Windows Server breit steht, kann man sich von der Selenium-Seite direkt das RC-Paket holen, entpacken und den Server starten. Der Server wird im Verzeichnis selenium-server-xx liegen. Starten kann man ihn einfach mit dem Befehl java -jar selenium-server.jar. Standardmäßig startet Selenium RC auf Port 4444. Wünscht man einen anderen Port, so kann man diesen mit dem Schalter -port <wunschport> beim Starten einstellen. Das war es dann auch eigentlich schon. Nun müssen wir den Server nur noch ansprechen.

Einen Test an den RC-Server senden

Da ich in hier vornehmlich PHP-Themen behandle, wollen wir Tests natürlich auch mit PHP an den RC-Server senden. Selenium bietet einen Treiber für PHPUnit an. Dieses UnitTest-Framework wird mit PEAR ausgeliefert. Evtl. muss es nachinstalliert werden – wie das funktioniert erfahrt ihr auf der PHPUnit-Seite. Dann sollte eigentlich alles automatisch passieren.

Bis hier die Theorie. Während ich das alles ausprobiert habe, ist nicht die Bohne automatisch passiert. Ich musste alles nachbearbeiten, anpassen, Pfade- und Klassennamen korrigieren. Wenigstens der Server hat keine Faxen gemacht. Einzig Safari wollte nicht testen, aber der wird offiziell unter Windows ja auch nur mit „may work” aufgeführt.

Dazu muss ich gestehen, dass ich kein großer Freund von PHPUnit bin. Das liegt in erster Linie daran, dass es so fest in PEAR eingebacken ist – was ich auch nicht mag. Wie dem auch sei. Ich will Selenium für SimpleTest benutzen. Dazu schnappt ihr euch einfach die im RC-Archiv vorhandenen Selenium-PHP-Dateien und passt sie ein bischen an. Zunächst erweitert die Exception nicht mehr die PEAR-Exception. Darüberhinaus erweitert die Klasse Testing_Selenium die Klasse UnitTestCase erweitert. Dann baut ihr noch eine neue Methode ein:

    public function run(SimpleReporter $reporter) {
    	$this->start();
    	$return = parent::run($reporter);
    	$this->stop();
    	return $return;
    }

Und fertig. Die TestCases die ihr mit der Selenium-IDE erstellt könnt ihr nun aus der IDE als PHP herauskopieren und in eure Tests einfügen. Der Konstruktor rist eigentlich selbsterklärend. Wie man nun UnitTests schreibt, werde ich hier aber nicht mehr erklären

Und nun?

Im letzten Teil werde ich erklären, wie man die in PHP überführten Tests in seinen Deploymentprozess integrieren kann, wie man schnell ordentliche Tests schreibt und mittels Selenium Grid dafür sorgt, dass man automatisiert und ohne Performanceverlust und Bottleneck testen kann.

Ich hoffe ich konnte euch Selenium näher bringen. Sollten noch Fragen offen sein, so scheut nicht, die Kommentarfunktion zu bemühen

Pekka kommt nicht mit Selenium klar, und auch sonst scheinen Frontend- bzw Webtests kein Thema zu sein. Entweder fahren viele Entwickler die Schiene “Geht eh nicht vernünftig” oder blenden die Problematik komplett aus. Da aber testgetriebene Entwicklung ist kein Buzzword sondern ein wichtiges Dogma ist, dass auch in Deutschland durchaus Einzug in den professionellen Entwickleralltag gefunden hat,  ist es nur konsequent die Benutzeroberfläche einzubeziehen. Wie man das mit Selenium machen kann, möchte ich in einer kleinen Artikelreihe erlätern. Sie wird aus folgenden Artikeln bestehen:

1. Sinnvolle Tests erstellen
2. Selenium Remote Control nutzen
3. Tests automatisieren und in Unittest-Frameworks einbinden

Vorbereitungen

Unter Zuhilfenahme der Selenium-IDE (ein Firefox-Plugin) lassen sich Tests angenehm schnell “aufnehmen & abspielen”, speichern, archivieren, weiterreichen. Diese also schnell installieren, einen Ordner “tests” irgendwo auf unserem Rechner anlegen und dann kann es auch schon losgehen.

Was testen?

Was genau man testet hängt in erster Linie von der Applikation ab. In der Regel sollte man Workflows innerhalb seiner Applikation testen. Dabei sollte darauf geachtet werden, bewusst ungültige Daten einzugeben und auf das Erscheinen der Fehlermeldungen zu prüfen. Selenium bietet die möglichkeit, den Seitentitel bei jedem Aufruf einer Seite direkt in den Test aufzunehmen und zu prüfen. Diese Option kann man aktivieren, wenn der Seitentitel stark an den Content gekoppelt ist.

Tests strukturieren

Es ist unerlässlich, seine Tests sauber zu strukturieren. Am besten teilt man diese in kleine thematisch zusammenhängende Häppchen auf. Vor allem aber sollten die einzelnen Tests selbstständig auf die Seite navigieren, von der sie starten. Darüber hinaus müssen die Tests in sich geschlossen sein, um eine Kettenreaktion von Fehlschlägen zu vermeiden.

Tipps & Kniffe

Es empfiehlt sich, seine Tests immer direkt einmal durchlaufen zu lassen. Dabei wird euch schnell auffallen, dass Selenium sich manchmal etwas zickig anstellt. Da wird sporadisch ein Link nicht gefunden, der eindeutig da ist, Eingaben können nicht gemacht werden und Textprüfungen schlagen fehl. In den meisten Fällen muss man dann einfach nur die Geschindigkeit etwas herunterdrehen. Ich habe gute Erfahrungen mit einer 2/3 Geschwindigkeit gemacht. Je nach Komplexität der Abfragen solltet Ihr das noch weiter minimieren. Sollte das immer noch nichts bringen, solltet ihr einen Blick auf die Befehle vor dem Fehlschlag werfen. Häufig steht dort ein “click” Befehl. Ersetzt diesen gegen einen “clickAndWait“, und das Problem verschwindet in der Regel wieder.

Und nun?

Erstellt nun eine (oder mehrere) Testsuite(s) für eure Applikation. Lasst diese einfach mal nach ein paar Änderungen gegen eure Applikation testen. Ihr werdet feststellen, dass sich eure Applikation an den unmöglichsten stellen stark anders als zuvor verhält.

Im nächsten Teil werde ich dann erklären, wie man die Selenium Remote Control nutzen kann.

Welcher Webworker kennt das nicht: Man baut Super-Features mittles JavaScript in seine Webanwendung, die das Leben des Benutzers erleichtern, die Anwendung mehr und mehr wie eine Desktopsoftware wirken lässt. Man benutzt Bibliotheken, damit eine größtmögliche Browserkompatibilität erreicht wird. Aber irgendwie zickt der Internet Explorer immer rum und hält sich darüberhinaus auch noch sehr bedeckt wenn es ans Debugging geht.

Mehr als einmal wünschte ich mir, dass ich im IE ordentlich debuggen könnte. Doch den Firebug wird es wohl auf ewig nur für den Firefox geben. Denkste! Es gibt eine Lite Version für den Internet Explorer, Opera und Safari. Das ganze lässt sich einfach über ein Bookmarklet einbinden (dazu einfach diesen Link Bookmarken). Der Funktionsumfang ist natürlich eingeschränkt (wie man sich bei dem Zusatz “lite” schon denken konnte), aber es ist, jedenfalls was den IE betrifft, wesentlich mehr als man vom Hause Microsoft aus geliefert bekommt.

Wie man das Teil auch offline benutzen kann, wird auf der Seite des Lite Projektes erklärt: GetFireBug.com

Heute ein paar Gedanken zu Webhooks, deren Sinn und das man sie doch bitte so schnell wie möglich so häufig wie möglich anbieten solle.

Was sind Hooks?

In erster Linie ist ein Hook – wie man an meiner unglaublich kreativen Illustration erkennen kann – ein Haken. Allerdings nicht einer der Negativen, die man immer bei zu toll klingenden Sachen sucht, sondern ein durchaus Nützlicher und Brauchbarer. An diesen Haken hängen wir nämlich unseren Code.

Hooks kennt man zum Beispiel schon von SVN. Stellen wir uns folgende Situation vor: Nach jedem Commit in unser Repository soll das Team benachrichtigt werden, dass ein neuer Commit stattgefunden hat. Jetzt hätten die SVN-Entwickler eine solche Funktionalität direkt in die Software einbauen können. Würde auch Sinn ergeben, denn ein solcher Anwendungsfall ist durchaus üblich.

Stellen wir uns aber nun weiter vor, dass wir nach jedem Commit in den Hauptentwicklungszweig eine Version auf einem Testserver deployen wollen. Auch ein solcher Anwendungsfall ist ziemlich häufig anzutreffen. Spätestens wenn es darum geht, wie eine solche Deployroutine aussehen könnte, wäre den SVN-Entwickler aber aufgefallen, dass sie ja gar nicht wissen, um was für eine Programmiersprache es sich handelt. Schließlich könnte die Software statt in PHP genau so gut in Java, in ASP, in Perl oder in sonst einer Programmiersprache geschrieben worden sein. Oder ganz anders: Es handelt sich gar nicht um ein Webprojekt, sondern um eine Desktopsoftware.

Da haben sich die Entwickler von SVN einem Prinzip bedient, das alles andere als neu ist: Sie haben Haken in Ihre Software eingabaut, an die wir unsere Programmteile hängen können. In SVN sind das zum Beispiel post- oder pre-commit hooks. Scripte, die bei bestimmten Aktionen ausgeführt werden. Diese können in jeder beliebigen Sprache verfasst sein und dahingehend so ziemlich alles machen, was man sich vorstellen kann.

Wofür Hooks in Webdiensten?

Derzeit läuft alles im Netz nach einem ziemlich nervigen Prinzip ab. Im Fachjargon nennt man das Pull. Für den Laien ist es als das nervige Fragen der kleinen Gören auf dem Weg in den Familienurlaubsort bekannt.

Sind wir schon da?

Nein!

Sind wir schon da?

Nein!

Sind wir schon da?

Nein!

Sind wir schon da?

Ja, jetzt sind wir da!

Für beide Seiten wäre es wesentlich entspannter, wenn man nicht ständig nachfragen würde, sondern bescheid gesagt wird, sobald man denn tatsächlich da ist. Und genau das ist das Prinzip der Webhooks. Es wird gepusht, sobald etwas passiert. Dazu hinterlasst man nicht anderes als eine Adresse, hinter der sich ein Script verbirgt, das genau das macht, was man will. Dieses kann in jeder beliebigen Sprache verfasst sein, und somit jede nur erdenkliche Erweiterung für den Service bieten.

Aber viele Services bieten APIs an! Warum nicht diese benutzen?

APIs sind in erster Linie dafür gedacht, auf bestimmte Funktionen des Programmes zuzugreifen. Dabei steuern aber auch wir wieder die API an und nicht die API unser Script. Bei Hooks läuft das genau anders herum.  So kann man Hooks also durchaus sinnvoll mit den klassischen APIs kombinieren und die herkömmliche Struktur um ein sinnvolles Feature ergänzen. Hooks sollen APIs also nicht ablösen. Im Gegenteil.

Das Foto stammt von Daniel Jaeger.

Im Endeffekt ist daraus ein kleines Projekt entstanden, mehr dazu am Ende des Artikels.

Ich habe versucht die Suite so flexibel wie möglich aufzubauen. So ist es möglich einen eigenen Logger zu definieren, der gefundene Regelverstöße auf beliebige Art und Weise festhält. Der Beispiellogger gibt einfach alles direkt aus. So ist es aber auch möglich, Verstöße in einer Datenbank festzuhalten oder in Dateien zu schreiben.

Die Meldungen werden inkl. Datei, Zeile und Autor gespeichert (wenn sich dieser über den DocBlock ermitteln lässt). So sind Verstöße direkt einem Autor zuzuordnen. Als Testregeln habe ich mir folgende ausgedacht:

• Klassennamen müssen mit Großbuchstaben beginnen
• Klassennamen müssen der Ordner- und Dateistruktur unterhalb des Include-Pfads entsprechen
• Properties und Methoden im private oder protected scope müssen mit einem Unterstrich beginnen
• Jede Klasse, jede Methode und jedes Property muss dokumentiert werden

Das erstellen von Regel-Klassen ist recht einfach. An die Methode “check” wird die zu checkende reflektierte Klasse übergeben. Der Tester erwartet als Rückgabe entweder “null” oder ein Result-Objekt. Ziemlich easy, eigentlich. Schauen wir, ob wir die Testfälle abdecken können.

Klassennamen müssen mit Großbuchstaben beginnen

	class Compliance_Rule_Class_Name extends Compliance_Rule  {
		protected $_deficitMessage = 'Class name must begin with an upper case letter.';

		public function check(ReflectionClass $class) {
			$result = null;

			if(!preg_match('/^[A-Z]/', $class->getName())) {
				$result = new Compliance_Rule_Result();
				$message = new Compliance_Rule_Result_Message(
					$class->getDocComment()->getAuthor(),
					$class->getName(),
					new Compliance_Tester_Directory_File($class->getFileName()),
					$class->getStartLine(),
					$this->_deficitMessage
				);
				$result->addMessage($message);
			}

			return $result;
		}
	}

Schuss und Treffer. Einmal runtergeschrieben funktionierte sofort. Wunderbar. Wir holen uns mit getName den Klassennamen aus der Reflection und prüfen mittels eines regulären Ausdrucks, ob dieser mit einem Großbuchstaben beginnt.

Klassennamen müssen der Ordner- und Dateistruktur unterhalb des Include-Pfads entsprechen

	class Compliance_Rule_Class_Path extends Compliance_Rule  {
		protected $_deficitMessage = 'Class name must express path to file.';

		public function check(ReflectionClass $class) {
			$result = null;

			$classname = $class->getName();
			$path = str_replace('_', DIRECTORY_SEPARATOR, $classname). '.php';
			if(substr($class->getFileName(), (strlen($path) * -1)) != $path) {
				$result = new Compliance_Rule_Result();
				$message = new Compliance_Rule_Result_Message(
					$class->getDocComment()->getAuthor(),
					$class->getName(),
					new Compliance_Tester_Directory_File($class->getFileName()),
					$class->getStartLine(),
					$this->_deficitMessage
				);
				$result->addMessage($message);
			}

			return $result;
		}
	}

Wow. Das war genau so einfach! Man könnte diese Regel noch verfeinern, aber in meinem Fall reicht sie voll und ganz aus. Ich wandle den Klassennamen in einen Pfad um, in dem ich die Unterstriche durch die DIRECTORY_SEPERATOR-Konstante ersetze und die Endung “.php” hinten dran setze. Dann prüfe ich einfach, ob die Datei, in der sich die reflektierte Klasse befindet von hinten an identisch ist mit dem generierten Pfad. Kommen wir also zur nächsten Regel.

Properties und Methoden im private oder protected scope müssen mit einem Unterstrich beginnen

Das habe ich in zwei Regeln aufgeteilt. Und hier bin ich nun auch auf die ersten Probleme gestoßen. Fangen wir also mit einer Regel an, die prüft, ob alle private/protected Properties mit einem Unterstrich beginnen bzw. ob alle mit einem Unterstrich beginnenden Properties private oder protected sind.

	class Compliance_Rule_Class_Property_Name extends Compliance_Rule {
		protected $_deficitMessage = 'Protected and public Attributes must begin with an underscore.';

		public function check(ReflectionClass $class) {

			$result = null;

			foreach($class->getProperties() as $property) {
				$return = $this->checkProperty($property);
				if($return !== null) {
					if($result === null) {
						$result = new Compliance_Rule_Result();
					}

					$result->addMessage($return);
				}
			}

			return $result;
		}

		public function checkProperty(ReflectionProperty $property) {
			if(!$property->getDeclaringClass()->isUserDefined()) {
				return;
			}

			if(($property->isPrivate() OR $property->isProtected())
					AND
				substr($property->getName(), 0, 1) != '_') {
				$message = new Compliance_Rule_Result_Message(
					$property->getDocComment()->getAuthor(),
					$property->getDeclaringClass()->getName(),
					new Compliance_Tester_Directory_File($property->getDeclaringClass()->getFileName()),
					$property->getLineNumber(),
					$this->_deficitMessage
				);

				return $message;
			}

			if((!$property->isPrivate() AND !$property->isProtected())
					AND
				substr($property->getName(), 0, 1) == '_') {
				$message = new Compliance_Rule_Result_Message(
					$property->getDocComment()->getAuthor(),
					$property->getDeclaringClass()->getName(),
					new Compliance_Tester_Directory_File($property->getDeclaringClass()->getFileName()),
					$property->getLineNumber(),
					$this->_deficitMessage
				);

				return $message;
			}
		}
	}

Zu unserem Problem: Um den Dateinamen in das Result-Objekt eintragen zu können muss ich mir zunächst wieder die Überklasse holen. Haben wir hier nun aber ein Property dass innerhalb einer Standard-PHP-Klasse definiert wurde, von einer erweiterten Klasse übernommen wurde und nicht unserer Regel entspricht, haben wir keinen Dateinamen. So oder so sind das Verstöße, gegen die man sich (als PHP-Entwickler) nicht wehren kann.

Hier dann noch die Regel für Methoden

	class Compliance_Rule_Class_Method_Name extends Compliance_Rule {
		protected $_deficitMessage = 'Protected and private methods must begin with an underscore.';

		public function check(ReflectionClass $class) {
			$result = null;

			foreach($class->getMethods() as $method) {
				$return = $this->checkMethod($method);
				if($return !== null) {
					if($result === null) {
						$result = new Compliance_Rule_Result();
					}

					$result->addMessage($return);
				}
			}

			return $result;
		}

		public function checkMethod(ReflectionMethod $method) {
			if(!$method->getDeclaringClass()->isUserDefined()) {
				return;
			}

			if(($method->isPrivate() OR $method->isProtected())
					AND
				substr($method->getName(), 0, 1) != '_') {
				$message = new Compliance_Rule_Result_Message(
					$method->getDocComment()->getAuthor(),
					$method->getDeclaringClass()->getName(),
					new Compliance_Tester_Directory_File($method->getDeclaringClass()->getFileName()),
					$method->getStartLine(),
					$this->_deficitMessage
				);

				return $message;
			}
		}
	}

Ich habe hier den eigentlichen Check gegen die Regel in eine weitere Methode ausgelagert. Das hat einen ziemlich einfachen Grund: Ich bin faul. Ich kann in der neuen Methode Type Hinting auf die Properties/Methoden machen und kann so mein Auto-Complete in Eclipse benutzen.

Jede Klasse, jede Methode und jedes Property muss dokumentiert werden

Im Grunde ist das nun auch nur eine Zusammenführung von dem, was wir in den Regeln zuvor schon gemacht haben. Hier der Code:

	class Compliance_Rule_Class_Documentation extends Compliance_Rule  {
		protected $_deficitMessage = 'All classes, methods and attributes must be documentated.';

		public function check(ReflectionClass $class) {
			$result = null;

			if(($return = $this->checkClass($class)) !== null) {
				if($result === null) {
					$result = new Compliance_Rule_Result();
				}

				$result->addMessage($return);
			}

			foreach($class->getMethods() as $method) {
				$return = $this->checkMethod($method);
				if($return !== null) {
					if($result === null) {
						$result = new Compliance_Rule_Result();
					}

					$result->addMessage($return);
				}
			}

			foreach($class->getProperties() as $property) {
				$return = $this->checkProperty($property);
				if($return !== null) {
					if($result === null) {
						$result = new Compliance_Rule_Result();
					}

					$result->addMessage($return);
				}
			}

			return $result;
		}

		public function checkMethod(ReflectionMethod $method) {
			if(!$method->getDeclaringClass()->isUserDefined()) { return; }

			if($method->getDocComment()->__toString() == '') {
				$message = new Compliance_Rule_Result_Message(
					$method->getDocComment()->getAuthor(),
					$method->getDeclaringClass()->getName(),
					new Compliance_Tester_Directory_File($method->getDeclaringClass()->getFileName()),
					$method->getStartLine(),
					$this->_deficitMessage. ' method'
				);

				return $message;
			}
		}

		public function checkProperty(ReflectionProperty $property) {
			if(!$property->getDeclaringClass()->isUserDefined()) { return; }

			if($property->getDocComment()->__toString() == '') {
				$message = new Compliance_Rule_Result_Message(
					$property->getDocComment()->getAuthor(),
					$property->getDeclaringClass()->getName(),
					new Compliance_Tester_Directory_File($property->getDeclaringClass()->getFileName()),
					$property->getLineNumber(),
					$this->_deficitMessage. ' property'
				);

				return $message;
			}
		}

		public function checkClass(ReflectionClass $class) {
			if($class->getDocComment()->__toString() == '') {
				$message = new Compliance_Rule_Result_Message(
					$class->getDocComment()->getAuthor(),
					$class->getName(),
					new Compliance_Tester_Directory_File($class->getFileName()),
					$class->getStartLine(),
					$this->_deficitMessage. ' class'
				);

				return $message;
			}
		}
	}

Probleme

Wer bis hierhin aufgepasst hat, wird festgestellt haben, dass Zeilennummern von Properties sich nicht über die Reflection ermitteln lassen. Auch der Autor ist noch nicht automatisiert aus dem DocBlock auszulesen. Hier sind leider ein paar Erweiterungen der Reflection-API notwendig. Glücklicherweise kann man die Reflection-Klassen problemlos extenden. Bauen wir uns also zunächst eine Möglichkeit um die Zeilennummer eines Properties zu ermitteln. Auf Anhieb fiel mir nichts besseres ein, als die Datei, in der sich die Klasse befindet auszulesen. Aber auch hier wieder direkt zwei Probleme: Was, wenn sich in einer Datei zwei Klassen befinden, die beide ein Property mit dem selben Namen und den selben Eigenschaften besitzen? Und dazu kommt dann noch das Dilemma, dass man protected/private/public und static in beliebiger Reihenfolge notieren kann. Wird also doch nicht so einfach.

Reflection-API ergänzen: Zeilennummern von Properties ermitteln

Zunächst der Code, den ich benutzt habe:

		public function getLineNumber() {
			$file = $this->getDeclaringClass()->getFileName();
			$startLine = $this->getDeclaringClass()->getStartLine();
			$endLine = $this->getDeclaringClass()->getEndLine();

			$contents = file_get_contents($file);
			$contents = explode("\n", $contents);

			$classCode = '';

			for($i = $startLine -1; $i < $endLine; $i++) {
				$classCode.= $contents[$i]. "\n";
			}

			$pattern = $this->_getPattern();

			$replaced = preg_replace($pattern, 'START_LINE_COMPLIANCE$1END_LINE_COMPLIANCE', $classCode);

			$classCode = explode("\n", $replaced);

			foreach($classCode as $lineNumber => $line) {
				if(substr(trim($line), 0, strlen('START_LINE_COMPLIANCE')) == 'START_LINE_COMPLIANCE') {
					$startLineProperty = $lineNumber + $startLine;
				}

				if(substr(trim($line), (strlen('END_LINE_COMPLIANCE') * -1)) == 'END_LINE_COMPLIANCE') {
					$endLineProperty = $lineNumber + $startLine;
				}

			}

			return $startLineProperty;
		}

Zunächst ermittle ich die Datei, in der sich die Klasse befindet und die Start- und Endzeile, zwischen der sie definiert wird. Ich lese die Datei aus, packe die Zeilen in Arrayelemente und baue mir ein neues nur aus den Zeilen, in der sich die Klasse befindet. Diese führe ich wieder als einen zusammenhängenden Text zusammen und suche nach einem Ausdruck, den ich mit Schlüsselwörtern ergänze. So kann ich die Zeile ermitteln, berücksichtige das Offset und gebe das ganze aus.

Wie der Ersetzungsausdruck generiert wird erspare ich euch, das ist einfach nur langweilig . Wen es doch interessiert, der kann im Source nachsehen.

Jetzt fragen sich sicherlich einige, warum ich einige Sachen nicht anders/einfacher gelöst habe:

Warum nicht fopen/fread?

Das Problem bei fread ist, dass es entweder eine Menge an Bytes einliest oder bis zum Zeilenende. Da wir tatsächlich Zeilen brauchen, bringt uns eine Menge Bytes überhaupt nichts. Je nach kodierung der Quelldatei liest fread einfach mal die komplette Datei (bzw. bis zur maximalen Byte-Grenze) ein, und glaubt, das war nun eine Zeile. Unbrauchbar also.

Warum nicht direkt die Array-Elemente nach dem Property durchsuchen?

Es könnte durchaus möglich sein, dass das Property über mehrere Zeilen definiert wurde. Ich entschloss mich daher, das Property zu markieren um später die Anfangs und Endzeile ermitteln zu können. Das war insofern erst einmal vergebene Liebesmüh, weil ich es derzeit nichtmal ausgeben

DocBlock-Object

Hier habe ich mich bei Martin Kuckert bedient, der vor einiger Zeit eine DocParser-Klasse geschrieben hat. Die Methode “getDocComment” gibt also keinen String mehr zurück, sondern liefert ein DocBlock-Objekt. Dieses hat, in meiner Fassung, derzeit nur die Methode “getAuthor” implementiert.

Aber: Wir haben in unserem Regelset ja die Anweisung, dass alles Dokumentiert sein muss. Ist etwas nun nicht dokumentiert, so kann man auch schlecht einen Autor aus dem DocBlock ermitteln. Aus diesem Grund gibt es den Parameter “assume”, der standardmäßig auf true ist. Damit kann man den Author “vermuten”. Das Prinzip ist simple: Ist ein Property oder eine Methode nicht dokumentiert, so wird der DocBlock der Klasse genommen.

Let’s roll

Nachdem ich die Suite gegen sich selbst rennen ließ, wurde mir klar, dass ich selbst noch ein paar Kommentare schreiben muss. Das sagt mir direkt, dass das nicht ganz unnützlich ist, ein solches Tool in der Hinterhand zu haben.

Das Projekt

Ich habe jetzt ein paar Tage mit der Test Suite und den Regeln verbracht und habe richtig Spaß daran gehabt. Ich habe die Test-Suite gegen das Zend Framework testen lassen und bin über ein paar Fallstricke gestolpert – allen vorran das Memory Limit. Daher habe ich mich beim schreiben der letzten Absätze dazu entschlossen das ganze als Projekt weiterzuverfolgen. Daher hier eine kleine Projektseite für den Compliance Suite. Dort könnt ihr das ganze auch runterladen und selbst mal ausprobieren.