In diesem Artikel wird erklärt, wie der Trinitäts-Operator (engl. Ternary Operator, auch Fragezeichenoperator oder dreifach konditionaler Operator genannt) funktioniert, und wie man ihn richtig anwendet.

Funktionsweise

Der Trinitäts-Operator stellt im Grunde eine Fallunterscheidung in Verbindung mit einer Zuweisung oder einem Funktionsaufruf dar. Man möchte einer Variablen entweder Wert 1, oder Wert 2 zuweisen, abhängig von einer Bedingung. Oder: Man möchte, abhängig von einer Bedingung entweder Funktion X oder Funktion Y aufrufen. Dadurch, dass man sich das if/else sparen kann, und den Variablennamen nur einmal schreiben muss, wird das ganze nicht nur kürzer, sondern auch übersichtlicher.

Abfrage/Zuweisung mit if

Würde man eine solche Zuweisung mit einer normalen if/else-Abfrage realisieren, bräuchte man 5 Zeilen. Das sähe wie folgt aus:

if (<Bedingung>) {
    <Variable> = <Wert 1>;
} else {
    <Variable> = <Wert 2>;
}

Abfrage/Zuweisung mit if (verkürzt)

Eine solche if-Abfrage lässt sich natürlich noch verkürzen. Die geschweiften Klammern können weggelassen werden, und man kann alles in eine Zeile quetschen.

if (<Bedingung>) <Variable> = <Wert 1>; else <Variable> = <Wert 2>;

Abfrage/Zuweisung mit dem Trinitäts-Operator.

Mit dem Trinitäts-Operator wird die Zuweisung dann noch kürzer, und wenn man den Trinitäts-Operator kennt, ist auch sofort ersichtlich, was diese Zeile tut.

<Variable> = (<Bedingung>) ? <Wert 1> : <Wert 2>;

Beispiel

Und noch ein Beispiel, mit richtigen Werten.

// Normale Form
 
if ($antwort1 == 42 && $antwort2 == 1337) {
    $allesrichtig = true;
} else {
    $allesrichtig = false;
}
 
// Verkürzte Form
 
if ($antwort1 == 42 && $antwort2 == 1337) $allesrichtig = true; else $allesrichtig = false;
 
// Trinitäts-Operator
 
$allesrichtig = ($antwort1 == 42 && $antwort2 == 1337) ? true : false;

Man schreibt also zuerst die Bedingung (in Klammern), dann ein Fragezeichen und den Wert den die Variable annehmen soll, wenn die Bedingung wahr ist, dann einen Doppelpunkt, und den Wert für den Fall das die Bedingung unwahr ist.

Noch kürzer

Seit PHP 5.3 gibt es noch eine weitere Form des Trinitäts-Operators, mit der sich manche Zuweisungen noch weiter verkürzen lassen.

<Variable> = <Variable/Bedingung> ?: <Wert>;

Dabei wird ausgewertet ob die Bedingung wahr ist, bzw. die Variable den booleschen Wert true hat (oder dazu umgewandelt werden kann). Ist das der Fall, bekommt die Variable den Wert der Bedingung zugewiesen, ansonsten den anderen Wert.

Hier noch ein Beispiel, welches das ganze vielleicht etwas besser verdeutlicht:

$id = @$_GET['id'] ?: 0;

Wenn $_GET['id'] gesetzt, und ungleich 0 ist, nimmt $id den Wert von $_GET['id'] an. Ansonsten bekommt $id den Wert 0. Das @ steht da, damit PHP nicht über eine undeklarierte Variable meckert, falls $_GET['id'] nicht gesetzt ist.

Funktionen aufrufen

Der Trinitäts-Operator kann auch in Verbindung mit Funktionsaufrufen verwendet werden. Dabei ist es auch möglich mehrere Funktionen aufzurufen. Von letzterem rate ich allerdings ab, in den meisten Fällen wird das schnell unübersichtlich. Wie es funktioniert erkläre ich allerdings trotzdem: Um mehrere Funktionen im Trinitäts-Operator zu verwenden, müssen diese mittels AND verbunden werden, eine Trennung mittels Semikolon oder && funktioniert nicht.

$allesrichtig ? print("Alle Fragen wurden richtig beantwortet, super!") AND
                die("Das Quiz ist zu Ende.") : die("Leider falsch!");

Es ist übrigens auch möglich, den Trinitätsoperator innerhalb von Zeichenketten zu verwenden:

echo 'Bitte ' . ($siezen ? 'klicken Sie ' : 'klicke ') . 'hier, '
. 'um zur vorherigen Seite zurückzukehren';

So nicht!

Der Trinitäts-Operator kann zwar verschachtelt werden, davon rate ich aber ab. Solche Zuweisungen werden schnell sehr unübersichtlich.

// Unübersichtlich:
$allesrichtig = ($antwort1 == 42 && $antwort2 == 1337) ? (($antwort3 > $antwort4) ?
                ((0 === 0) ? true : false) : false) : false;

Beispiel-Datei

Eine Beispieldatei, mit allen möglichen Formen der Verwendung des Trinitäts-Operators habe ich auch noch erstellt: Beispiel.phps

Geschwindigkeitsvergleich

Dominik Deobald vergleicht in seinem Artikel Benchmarking PHP: eAccelerator und andere OpCode Caches die Geschwindigkeit von PHP ohne Zwischenspeicher mit der Geschwindigkeit von 5 populären Zwischenspeichern. Neben APC werden auch eAccelerator, Zend und xCache getestet. Sein Fazit: Die Nutzung eines Zwischenspeichers lohnt sich, wie sehr die Geschwindigkeit sich verbessern lässt ist allerdings anwendungsabhängig. In seinen Tests schneidet der eAccelerator etwas besser ab als APC.

Installation von APC

Ab PHP 6 soll APC zu PHP standardmäßig dazugehören, zur Zeit ist es nur ein PECL-Modul, und muss erst installiert werden. Die meisten Linux-Distributionen bieten allerdings Pakete für APC an, was die Installation stark vereinfacht. Aber auch die Installation mittels PECL ist eigentlich nicht weiter schwer. Wie man den Zwischenspeicher installiert, und ihn in der php.ini aktiviert, erkläre ich im Artikel Installation von APC.

APC richtig konfigurieren

Die Standardkonfiguration von APC ist für die meisten Einsatzzwecke gut geeignet. Dennoch gibt es einige Optionen, die man vielleicht anpassen möchte. In meinem Artikel Konfiguration von APC erkläre ich die wichtigsten Optionen, und zeige eine Übersicht aller Einstellungsmöglichkeiten. Ich beschreibe beispielsweise wie man die Größe des Zwischenspeichers verändern kann, wie die Überwachung des Hochladevorgangs eingeschaltet wird, die Lebensdauer von Dateien im Zwischenspeicher eingestellt wird, und noch einiges mehr.

Funktionen von APC

APC kann nicht nur die Geschwindigkeit von PHP erhöhen, indem es vorkompilierte Dateien zwischenspeichert. APC kann auch Variablen/Konstanten/Objekte im Zwischenspeicher ablegen, und diese über mehrere Aufrufe hinweg verfügbar machen. So können beispielsweise zeitaufwendige Datenbankabfragen eingespart werden. Außerdem bietet APC einige nützliche Funktionen, die einem nützliche Informationen über den Zwischenspeicher liefern, sowie die Möglichkeit geben Dateien/Variablen aus ihm zu entfernen. Welche Funktionen es gibt, und wie man sie benutzt, beschreibe ich im Artikel Funktionen von APC.

APC überwachen

Mit APC wird noch ein kleines PHP-Skript mitgeliefert, mit dem man den Zustand des Zwischenspeichers überwachen kann. Außerdem können damit im Zwischenspeicher gespeicherte Variablen und Dateien eingesehen und auch gelöscht werden. Wie dieses Skript benutzt wird, erkläre ich in meinem Artikel APC: Status und Überwachung.

Alternativen

APC ist nicht der einzige Zwischenspeicher für PHP, es gibt noch einige andere. Einer davon ist XCache, der übrigens wie APC neben dem Zwischenspeicher für vorkompilierte Dateien noch über einen Variablen-Zwischenspeicher verfügt. Außerdem gibt es noch den eAccelerator, und den Zend Cache. Der IonCube PHP Accelerator und TurkMMCache sind ebenfalls Zwischenspeicher, diese werden allerdings schon seit längerer Zeit nicht mehr weiterentwickelt, und funktionieren nicht mehr mit neueren PHP-Versionen.

Variablen und Objekte

Variablen, Objekte und Konstanten werden im sog. User Cache abgelegt, dabei muss ihnen ein einzigartiger Schlüssel zugewiesen werden. APC stellt Funktionen zum Speichern, Auslesen, Überschreiben und Löschen bereit. Bei Variablen und Objekten lässt sich eine Lebensdauer angeben, diese wird bei jedem Aufruf überprüft, wurde sie überschritten, wird die Variable aus dem Zwischenspeicher gelöscht. Hat die Lebensdauer den Wert 0 (Standard), ist sie unendlich, die Variable wird also nicht automatisch gelöscht (außer natürlich bei einem Neustart/Leeren des Zwischenspeichers).

Hinweis: Es ist nicht möglich, ein Feld von Objekten im Zwischenspeicher abzulegen. Das Feld wird zwar gespeichert, die darin befindlichen Objekte haben aber alle den Wert NULL. Es gibt allerdings einen Weg, trotzdem ein Feld von Objekten zu speichern, und zwar mit dem ArrayObject.

Speichern von Variablen/Objekten

bool apc_add(string Schlüssel, mixed Variable
             [, int Lebensdauer = 0])
bool apc_store(string Schlüssel, mixed Variable
               [, int Lebensdauer = 0])

Diese Funktionen speichern eine Variable bzw. ein Objekt im Zwischenspeicher, der erste Parameter ist der Schlüssel/Name unter dem diese abgelegt wird. Der zweite Parameter ist die Variable selbst, der dritte (optional) gibt die Lebensdauer an. Die Funktion apc_store überschreibt eine Variable, wenn der Schlüssel bereits vorhanden ist, apc_add gibt in diesem Fall false zurück, ohne die Variable zu überschreiben.

// true (wenn die Variable noch nicht im Zwischenspeicher ist)
var_dump(apc_add('hallo', 'Hallo Welt'));
// false, da der Schlüssel 'hallo' bereits existiert.
var_dump(apc_add('hallo', 123));
 
echo apc_fetch('hallo'); // Hallo Welt
 
// apc_store überschreibt die Variable, wenn der Schlüssel bereits
// existiert.
apc_store('hallo', 456);
echo apc_fetch('hallo'); // 456

Auslesen von Variablen/Objekten

mixed apc_fetch(string Schlüssel [, bool &Erfolg])
array apc_fetch(array Schlüssel [, bool &Erfolg])

Mit apc_fetch können die Daten wieder aus dem Zwischenspeicher ausgelesen werden. Der erste Parameter ist der Schlüssel, unter dem die Variable abgelegt ist. Die ausgelesenen Daten werden zurückgegeben, konnten keine Daten ausgelesen werden (z.B. weil der Schlüssel nicht existiert) wird false zurückgegeben.

Im zweiten Parameter kann eine Referenz auf eine Variable angegeben werden, die von APC bei erfolgreichem Auslesen auf true, ansonsten auf false gesetzt wird. Das ist ganz nützlich, da man ja auch Variablen vom Typ boolean (true oder false) im Zwischenspeicher ablegen kann, und man sonst nicht herausfinden könnte, ob der Rückgabewert false nun bedeutet das die Variable den Wert false hat, oder die Variable nicht ausgelesen werden konnte.

apc_store('Test', 123);
echo "Inhalt von 'Test': ", apc_fetch('Test'); // 123
$erfolg = false;
 
echo "Inhalt von 'ExistiertNicht': ";
var_dump(apc_fetch('ExistiertNicht', $erfolg)); // false
 
echo '$erfolg: ';
var_dump($erfolg); // false

Es ist auch möglich mehrere Schlüssel auf einmal abzufragen, dazu übergibt man anstatt eines Schlüssels einfach ein Feld mit mehreren Schlüsseln.

var_dump(apc_fetch('Test', 'hallo'));

APC gibt dann ein Feld (Schlüssel => Wert) zurück. Wenn einer der Schlüssel ausgelesen werden konnte, gilt die Abfrage als erfolgreich, konnte kein Schlüssel ausgelesen werden, wird ein leeres Feld zurückgegeben, und $Erfolg ist trotzdem true.

array(2) { ["Test"]=>  int(123)
           ["hallo"]=>  int(456)
}

Löschen von Variablen/Objekten

bool apc_delete(string Schlüssel)

Mit apc_delete können Variablen/Objekte wieder aus dem Zwischenspeicher gelöscht werden.

Konstanten

Mit der Funktion apc_define_constants lässt sich ein Satz von Konstanten im Zwischenspeicher speichern. Mittels apc_load_constants kann dieser wieder ausgelesen werden. Jeder Satz von Konstanten bekommt einen Namen, es ist also auch möglich mehrere verschiedene Sätze von Konstanten zu speichern.

Das erstmalige Definieren der Konstanten, bzw. deren Eintragung im Zwischenspeicher dauert etwa doppelt so lange, als würde man define verwenden, das Laden der Konstanten aus dem Zwischenspeicher ist allerdings drei mal so schnell wie define. Anschließend können die Konstanten verwendet werden, wie sonst auch.

Definieren von Konstanten

bool apc_define_constants(string Schlüssel, array Konstanten
                          [, bool Groß- u. Kleinschreibung beachten = true])

Die Funktion apc_define_constants erwartet zwei Parameter. Der erste ist der Name/Schlüssel unter dem der Satz von Konstanten gespeichert wird, der zweite ist ein Feld, welches die Konstanten enthält. Der dritte Parameter ist optional, und gibt an ob bei den Konstantennamen die Groß- und Kleinschreibung beachtet werden soll (also ob KONSTANTE und Konstante ein und die selbe Konstante sind (false) oder nicht (true)).

$konstanten = array ('ROT'   => '#f00',
                     'GRUEN' => '#0f0',
                     'BLAU'  => '#00f');
apc_define_constants('farben', $konstanten);

Bei Erfolg gibt die Funktion true zurück, ansonsten false.

Konstanten auslesen

bool apc_load_constants(string Schlüssel
                        [, bool Groß- u. Kleinschreibung beachten = true])

Mit apc_load_constants können die gespeicherten Konstanten wieder ausgelesen werden, sie werden beim Auslesen automatisch definiert. Der erste Parameter gibt wieder den Schlüssel/Namen des Konstantensatzes an, der zweite, optionale Parameter, gibt an ob die Groß- und Kleinschreibung beachtet wird. Bei Erfolg wird true, ansonsten false zurückgegeben.

apc_load_constants('farben');
echo "Rot: ", ROT;

Konstanten aus dem Zwischenspeicher entfernen

Um einen Satz von Konstanten wieder zu entfernen, kann die Funktion apc_delete verwendet werden.

apc_delete('farben');

Informationen über den Zwischenspeicher

array apc_cache_info([string Typ[, bool Limitiert]])
array apc_sma_info([bool Limitiert])

Die Funktion apc_cache_info kann verwendet werden, um Informationen über den Zwischenspeicher und darin enthaltene Dateien, Variablen, etc. zu erhalten. Der Typ gibt an, welche Art von Informationen zurückgegeben werden soll. Der Parameter Limitiert bestimmt, ob nur generelle Informationen (true) oder auch ein Feld mit Informationen über die einzelnen Dateien/Variablen (false) zurückgegeben werden soll.

Folgende Typen stehen zur Verfügung:

• "user": Informationen über den “User Cache”, also die Anzahl der gespeicherten Variablen, noch freie (verfügbare) Einträge, wie oft Variablen gespeichert wurden, wie viel Speicher die Variablen verbrauchen, etc. Ist die Ausgabe nicht limitiert, werden auch noch ausführliche Informationen über jede einzelne Variable zu dem Feld hinzugefügt.
• "filehits": Eine Liste von Dateien die für den aktuellen Aufruf aus dem Zwischenspeicher geholt wurden. (Funktioniert nur, wenn --enable-apc-filehits bei der Installation angegeben wurde.)
• Datei-Speicher: Wenn kein Typ oder ein ungültiger Typ angegeben wurde, gibt die Funktion Informationen über den Dateispeicher zurück. Zum Beispiel die Größe des Speichers, die Anzahl der Dateien, wie oft eine Datei nicht im Cache gefunden wurde, etc. Wenn die Ausgabe nicht limitiert ist, wird auch ein Feld mit Informationen über alle gespeicherten Dateien zurückgeliefert.

Die Funktion apc_sma_info hingegen liefert Informationen über den benutzten Speicher. Sie gibt ein Feld zurück, mit Informationen darüber wie viele Segmente verwendet werden, wie groß diese sind, und wie viel Speicher insgesamt zur Verfügung steht. Ist die Ausgabe nicht limitiert, werden auch noch Informationen über die einzelnen Segmente zurückgegeben.

Zwischenspeicher leeren

bool apc_clear_cache([string Typ])

Um den Zwischenspeicher zu leeren, kann die Funktion apc_clear_cache verwendet werden. Hat der Parameter den Wert user, wird der Variablen/Objekte/Konstanten-Zwischenspeicher geleert, ansonsten wird der Zwischenspeicher für Dateien geleert. Gibt true bei Erfolg zurück, ansonsten false.

apc_clear_cache();

Datei kompilieren und zwischenspeichern

bool apc_compile_file(string Dateiname)

Mit apc_compile_file wird eine Datei kompiliert und im Zwischenspeicher gespeichert. In der Konfiguration eingestellte Filter werden dabei umgangen.

if (apc_compile_file('datei.php')) {
    echo "Datei >datei.php< wurde im Zwischenspeicher abgelegt.";
}
else {
    echo "Fehler: Datei konnte nicht im Zwischenspeicher abgelegt werden.";
}

Die Funktion gibt bei Erfolg true, im Fehlerfall false zurück.

Überprüfen ob APC verfügbar ist

Wenn man überprüfen möchte, ob APC verfügbar ist, kann man mit extension_loaded einfach überprüfen ob die Erweiterung geladen ist. Wenn APC geladen ist, gibt die Funktion true zurück, ansonsten false.

var_dump(extension_loaded('apc')); // true oder false

Es gibt noch ein paar andere APC-Funktionen, wie beispielsweise apc_inc/apc_dec, diese sind allerdings leider (noch) nicht dokumentiert, weswegen ich diese hier nicht erklären werde.

Wie man diese Funktionalität von APC benutzt, was vorausgesetzt wird, und welches Informationen APC liefern kann erkläre ich in diesem Artikel.

Voraussetzungen

Um den Hochladevorgang mittels APC zu überwachen, bzw. Informationen über ihn zu erhalten, werden einige Dinge vorausgesetzt. Natürlich muss APC installiert und aktiviert sein. In der APC-Konfiguration muss die Option apc.rfc1867 auf On stehen. Der Benutzer muss JavaScript in seinem Browser aktiviert haben, denn sonst kann der Fortschritt nicht mittels AJAX abgefragt werden. Außerdem muss das Hochlade-Formular um ein weiteres input-Element erweitert werden. Als Ziel-Adresse für das Formular wird ein iframe verwendet.

Die Werte folgender beider APC-Optionen müssen bekannt sein:

• Der Präfix: apc.rfc1867_prefix (upload_)
• Der Name des Formularelements: apc.rfc1867_name (APC_UPLOAD_PROGRESS)

(Standardwerte in Klammern, wenn nichts an der Konfiguration geändert wurde, kann man davon ausgehen das APC diese Werte verwendet. Der Einfachheit halber verwende ich in dieser Anleitung in Beispielen immer die Standardwerte, wenn man andere Werte benutzt, müssen diese natürlich entsprechend angepasst werden.)

Das Formular

Das Hochlade-Formular muss etwas erweitert werden. Zuerst wird ein zusätzliches input-Element mit dem Namen APC_UPLOAD_PROGRESS erstellt, welches einen eindeutigen Wert zugewiesen bekommt. Über diesen Wert kann später der Hochladevorgang verfolgt werden, deshalb ist es auch wichtig, dass der Wert einzigartig ist, sonst funktioniert das ganze nicht mehr, wenn mehrere Benutzer gleichzeitig Dateien hochladen. Mit der PHP-Funktion uniqid() ist das aber kein Problem, sie erstellt eindeutige IDs.

<input type="hidden" name="APC_UPLOAD_PROGRESS" value="<?php echo uniqid(); ?>" />

Wenn eine Datei hochgeladen wird, blockiert die Seite normalerweise, und der Benutzer kann nichts auf der Seite machen, bis die Datei vollständig hochgeladen wurde. Ist die Datei dann hochgeladen, bekommt der Benutzer die Ausgabe der Ziel-Seite (action) des Formulars zu sehen. Wenn man eine Fortschrittsanzeige erstellen möchte ist das natürlich ungünstig. Deshalb erstellt man ein iframe, und weist dem Formular dieses iframe als target zu. Dadurch wird die Ziel-Seite im iframe geladen, und die Formular-Seite blockiert nicht.

Das sollte man aber nur machen, wenn der Benutzer JavaScript aktiviert hat, und somit die Fortschrittsanzeige sehen kann. Deswegen wird die target-Eigenschaft dem Formular per JavaScript zugewiesen. Hat der Benutzer JavaScript deaktiviert, verhält sich das Formular wie jedes andere auch (ohne Fortschrittsanzeige, aber mit Blockieren), ist JavaScript aktiviert sieht der Benutzer die Fortschrittsanzeige und die Seite blockiert nicht.

<iframe src="upload.php" name="versteckt" style="display:none;"></iframe>
<form name="dateihochladen" action="upload.php" method="post" enctype="multipart/form-data">
<script type="text/javascript">document.forms.dateihochladen.target = 'versteckt';</script>

Fehlt nur noch der AJAX-Teil des ganzen. Vorher benötigt man allerdings noch eine PHP-Datei, die die Informationen über den Vorgang liefert.

<?php
var_dump(apc_fetch('upload_' . $_GET['id']));
?>

Mittels apc_fetch werden die Informationen aus dem Zwischenspeicher ausgelesen, hierzu wird die eindeutige ID benötigt, welche man praktischerweise einfach über die URL überträgt und mittels $_GET abfragt. Anstatt das komplette Feld mit allen Informationen per var_dump auszugeben, kann man es natürlich auch per json_encode umwandeln (und dann gleich im JavaScript weiterverwenden), oder per PHP gleich die Fortschrittsanzeige in HTML ausgeben. Aber das ist jedem selbst überlassen.

Der AJAX-Teil ist auch nicht weiter schwer, man ruft einfach nach dem Absenden des Formulars in bestimmten Zeitintervallen die obige PHP-Datei ab, und verarbeitet die Informationen weiter, bzw. gibt sie aus. Komplett sieht das ganze dann so aus:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="de-DE">
  <head>
    <title>Fortschrittsanzeige beim Hochladen von Dateien</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <script type="text/javascript">
    function aktualisiere() {
      var anfrage = null;
 
      if (window.XMLHttpRequest) {
        anfrage = new XMLHttpRequest();
      }
      else if (window.ActiveXObject) {
        anfrage = new ActiveXObject("Microsoft.XMLHTTP");
      }
 
      anfrage.onreadystatechange = function() {
       if ((anfrage.readyState == 4) && (anfrage.status == 200)) {
          document.getElementById('status').innerHTML = anfrage.responseText;
        }
      }
 
      anfrage.open('GET', 'status.php?id=' + 
                    document.forms.dateihochladen.APC_UPLOAD_PROGRESS.value);
      anfrage.send(null);
    }
 
    function ladeHoch(elem) {
      elem.disabled = true;
 
      setInterval('aktualisiere()', 1000);
    }
    </script>
    <link rel="stylesheet" type="text/css" href="stil.css" />
  </head>
  <body>
    <h1>Dateien hochladen mit Fortschrittsanzeige</h1>
    <div id="inhalt">
      <iframe name="versteckt" style="display:none;"></iframe>
      <form name="dateihochladen" action="upload.php" 
            method="post" enctype="multipart/form-data">
      <script type="text/javascript">
        document.forms.dateihochladen.target = 'versteckt';
      </script>
        <fieldset>
          <legend>Datei</legend>
          <input type="hidden" name="APC_UPLOAD_PROGRESS" 
                 value="<?php echo uniqid(); ?>" />
          <input type="file" name="datei" />
          <input type="submit" value="Hochladen" 
                 onclick="ladeHoch(this);" />
        </fieldset>
        <div id="status"></div>
      </form>
    </div>
  </body>
</html>

In der Form funktioniert das Skript bereits, es macht aber nichts anderes, als das von APC zurückgegebene Feld mit Informationen im status-div auszugeben.

Welche Informationen bekommt man?

Welche Informationen APC zurückgibt hängt davon ab, ob die Datei gerade hochgeladen wird, oder der Hochladevorgang bereits abgeschlossen ist.

Wird die Datei gerade hochgeladen, enthält das von APC zurückgegebene Feld folgende Informationen:

Wenn der Hochladevorgang abgeschlossen wurde, kommen noch folgende Elemente hinzu:

Mehrere Dateien hochladen?

Es ist auch möglich den Hochladevorgang von mehreren Dateien zu überwachen, man kann aber erst nach dem Hochladen feststellen, wie groß jede einzelne Datei war/ist, da APC die Dateigrößen zusammenrechnet. Braucht man diese Information unbedingt, kann man mehrere Formulare mit je einer Datei, und unterschiedlichen APC_UPLOAD_PROGRESS-IDs erstellen.

Wie erstelle ich denn jetzt einen Fortschrittsbalken?

Wie man Fortschrittsbalken erstellt, habe ich in diesem Artikel beschrieben. Man könnte obiges Skript wie folgt modifizieren um einen Fortschrittsbalken zu implementieren (ich verwende in diesem Beispiel die dwProgressBar):
status.php

<?php
echo json_encode(apc_fetch('upload_' . $_GET['id']));
?>

hochladen.php

<!-- [...] -->
		<script src="mootools-1.2.3-core-yc.js" type="text/javascript"></script>
		<script src="dwprogressbar.js" type="text/javascript"></script>
		<script type="text/javascript">
			function aktualisiere() {
				var anfrage = null;
 
				if (window.XMLHttpRequest) {
					anfrage = new XMLHttpRequest();
				}
				else if (window.ActiveXObject) {
					anfrage = new ActiveXObject("Microsoft.XMLHTTP");
				}
 
				anfrage.onreadystatechange = function() {
					if ((anfrage.readyState == 4) && (anfrage.status == 200)) {
						var ergebnis = eval('(' + anfrage.responseText + ')');
						if (ergebnis.done == 1) {
							if (ergebnis.cancel_upload == 0) {
								document.getElementById('status').innerHTML = 'Hochgeladen!';
							}
							else {
								document.getElementById('status').innerHTML = 'Fehler/Abgebrochen.';
							}
						}
						else {
							//document.getElementById('status').innerHTML = Math.round((ergebnis.current * 100) / ergebnis.total) + '%';
							document.fsb.set(Math.round((ergebnis.current * 100) / ergebnis.total));
						}
					}
				}
 
				anfrage.open('GET', 'status.php?id=' + document.forms.dateihochladen.APC_UPLOAD_PROGRESS.value);
				anfrage.send(null);
			}
 
			function ladeHoch(elem) {
				elem.disabled = true;
 
				document.fsb = new dwProgressBar({
					container: $('status'),
					startPercentage: 0,
					speed: 1000,
					boxID: 'rahmen',
					percentageID: 'balken',
					step: 10,
					allowMore:0,
					displayID: 'text',
					displayText: true
				});
 
				setInterval('aktualisiere()', 1000);
			}
		</script>
		<style type="text/css">
			#rahmen {
				background:url('gfx/normal.png') right center no-repeat; width:300px; height:30px;
				display:inline-block;
			}
			#balken {
				background:url('gfx/farbig.png') left center no-repeat; height:30px;
			}
			#text {
				font-size:16px;
				line-height:20px;
				vertical-align:top;
				padding-left:10px;
				display:inline-block;
			}
		</style>
<!-- [...] -->

Ich hoffe ich konnte euch einen kleinen Einblick in das Thema Fortschrittsanzeige beim Hochladen von Dateien geben. Anhand dieses Artikels (und der vorangehenden zum Thema APC/Dateien hochladen) sollte es möglich sein, ein individuelles Formular zum Hochladen von Dateien, mit Fortschrittsbalken, etc. zu erstellen.

Die drei wichtigsten Einstellungen sind wohl die Größe des Zwischenspeichers, die Überwachung des Hochladevorgangs von Dateien, und ob APC bei jeder Anfrage überprüfen soll, ob eine Datei modifiziert wurde.

Die Größe des Zwischenspeichers

Die Größe des Zwischenspeichers lässt sich über die Konfigurationsoptionen apc.shm_size und apc.shm_segments einstellen. Erstere legt fest wie groß ein gemeinsames Speichersegment (Shared Memory) sein darf, letztere legt fest aus wie vielen solchen Segmenten der Zwischenspeicher besteht. Bei manchen Betriebssystemen können solche Speichersegmente nur wenige Megabytes groß sein, weswegen entweder mehrere Segmente verwendet werden müssen, oder die Betriebssystemkonfiguration angepasst werden muss. Linux hat standardmäßig eine maximale Segmentgröße von 32 MiB, BSD von 4 MiB.

; 2 Segmente von je 30 MiB = 60 MiB
apc.shm_size = 30
apc.shm_segments = 2

Hochladen von Dateien

Ist apc.rfc1867 eingeschaltet (On), legt APC beim Hochladen von Dateien einen Eintrag im Zwischenspeicher ab, der Informationen über den Hochladevorgang enthält. Mit diesen Daten lässt sich beispielsweise eine Fortschrittsanzeige realisieren. Damit APC einen solchen Eintrag erstellt, muss das Formular allerdings ein Feld mit einem bestimmten Namen, standardmäßig APC_UPLOAD_PROGRESS, haben. APC erstellt dann einen Eintrag im Zwischenspeicher mit dem Namen upload_<Schlüssel> wobei der Schlüssel dem Wert der value-Eigenschaft des Formularfeldes entspricht.

; Es sollen Informationen über den Hochladevorgang gespeichert werden.
apc.rfc1867 = On
; Benutze upload_ als Präfix für den Eintrag im Zwischenspeicher.
apc.rfc1867_prefix = upload_
; Name des versteckten Formularelementes, welches diese Funktionalität aktiviert.
apc.rfc1867_name APC_UPLOAD_PROGRESS
; Wie oft sollen die Informationen aktualisiert werden?
; 0 = So oft wie möglich. (Kann den Hochladevorgang verlangsamen)
; % = % der Dateigröße (z.B. 2% = alle 2% wird aktualisiert)
; <Zahl>< ,k,m,g> Nach  Bytes, Kilobytes, Megabytes oder Gigabytes.
apc.rfc1867 = 50k

Mehr Informationen zu dieser Funktion finden sich im Artikel Fortschrittsanzeige beim Hochladen von Dateien.

Wurde die Datei modifiziert?

Die Option apc.stat gibt an, ob bei jedem Aufruf überprüft werden soll, ob die Datei im Zwischenspeicher auch der Datei auf der Festplatte entspricht. Ist diese Option abgeschaltet (Off), wird keine Überprüfung durchgeführt, was zwar die Geschwindigkeit merklich verbessert, es aber auch nötig macht den Zwischenspeicher neu aufzubauen, damit die Änderungen am Quelltext einer Datei wirksam werden.

apc.stat = On

Auch wenn diese Option abgeschaltet ist, werden mit relativem Pfad inkludierte Dateien beim Inkludieren vorher überprüft. Bei absoluten Pfaden (also solchen die mit einem / beginnen), ist das nicht der Fall.

Viele gleichzeitige Zugriffe

Beim Starten von stark ausgelasteten Servern bzw. wenn viele Dateien modifiziert wurden, kann es passieren, dass mehrere Prozesse versuchen die gleiche Datei für den Zwischenspeicher zu kompilieren. Mittels apc.write_lock wird festgelegt, dass in diesem Fall nur ein Prozess die Datei zwischenspeichert, während die anderen Prozesse die noch nicht-zwischengespeicherte Datei einfach nur ausliefern. Ist die Option abgeschaltet, müssten die anderen Prozesse auf den ersten warten.

Überschreiben von Dateien

Wenn man eine Datei überschreibt, kann es passieren, das genau in dem Moment ein Zugriff auf diese Datei erfolgt. In dem Fall würde der Benutzer wahrscheinlich eine fehlerhafte Seite sehen (zum Teil die neue Datei, zum Teil noch die alte). Die Option apc.file_update_protection schützt davor, das eine erst zum Teil auf die Festplatte geschriebene Datei zwischengespeichert wird. Der Benutzer der in dem ungünstigen Moment auf die Datei zugreift bekommt zwar trotzdem eine fehlerhafte Seite ausgeliefert, aber die fehlerhafte Seite landet nicht im Zwischenspeicher.

; Um in den Zwischenspeicher zu kommen muss eine Datei min. 2 Sekunden alt sein.
apc.file_update_protection = 2

Auf Systemen mit hoher Festplattenauslastung ist es sinnvoll diesen Wert noch etwas zu erhöhen. Wenn man sich sicher ist, das Dateien immer atomar überschrieben werden, kann dieser Wert auf 0 gesenkt werden. (Beispielsweise wenn man die neue Datei erst in eine temporäre Datei schreibt und sie dann umbenennt.)

Lebenszeit von Dateien

Da die Größe des Zwischenspeichers begrenzt ist, könnte es unter Umständen passieren, dass dieser voll wird und kein Platz mehr für neue Dateien/Variablen ist. APC bietet allerdings die Möglichkeit Dateien oder Variablen auf die eine bestimmte Zeit lang nicht mehr zugegriffen wurde, aus dem Zwischenspeicher zu nehmen, um wieder Platz zu schaffen. Diese Funktion wird durch die Optionen apc.ttl (für Dateien) und apc.user_ttl (für Variablen) beeinflusst, welche festlegen, wie lange eine Datei/Variable nicht mehr aufgerufen werden darf bevor sie entfernt wird. Ist dieser Wert 0, ist die Funktion abgeschaltet. In diesem Fall wird der Zwischenspeicher komplett geleert, wenn er voll ist.

Außerdem gibt es noch apc.gc_ttl, wodurch bestimmt wird, wie oft APC den Zwischenspeicher auf veraltete Dateien überprüft, bzw. diese löscht.

apc.ttl = 0
apc_user_ttl = 0
apc.gc_ttl = 3600

Filtern von Dateien

Standardmäßig speichert APC alle aufgerufenen PHP-Dateien im Zwischenspeicher. Mithilfe von Filtern kann man aber einstellen, das nur bestimmte Dateien zwischengespeichert werden, bzw. bestimmte Dateien nicht in den Zwischenspeicher kommen. Dazu wird die Option apc.filters verwendet, diese erwartet eine durch Komma getrennte Liste von regulären Ausdrücken. Ein + oder ein – vor jedem Ausdruck legt fest ob auf den Ausdruck passende Dateien zwischengespeichert werden (+) oder nicht gespeichert werden (-). Wird das Plus/Minus weggelassen, wird Minus angenommen.

Die Option apc.cache_by_default gibt an ob APC standardmäßig alle PHP-Dateien zwischenspeichert, oder keine. Mit apc.max_file_size können außerdem Dateien ab einer bestimmten Größe vom Zwischenspeicher ausgeschlossen werden.

; Alle Dateien zwischenspeichern
apc.cache_by_default = 1
; Ausser: Dateien in /nicht_zwischenspeichern/ und
; die Datei mit dem Namen blablabla.php
apc.filters = "/nicht_zwischenspeichern/.*,blablabla\.php"
; Keine Datei groesser als 1 MB
apc.max_file_size = 1M

Hinweis: Beim Inkludieren von Dateien wird dieser Filter auf den Dateinamen der in der include-Anweisung steht angewendet, nicht auf den absoluten Pfad der Datei.

Tabelle: Alle Optionen

In dieser Übersicht stehen noch mal alle Optionen, mit den Standardwerten und einer sehr kurzen Beschreibung. Eine ausführlichere Beschreibung der Optionen findet sich im PHP-Handbuch. Wenn bei Zeitangaben keine Einheit dabei steht, sind Sekunden gemeint.

Einige Optionen sind veraltet, und sollten nicht mehr verwendet werden.

• apc.optimization
• apc.slam_defense (anstatt dessen sollte apc.write_lock verwendet werden.)

APC ist eine PECL-Erweiterung, die nicht zum Installationsumfang von PHP 5 gehört. Ab PHP 6 soll APC standardmäßig in PHP enthalten sein. Ob APC bereits installiert ist, kann man in der Ausgabe von phpinfo() sehen.

Es gibt zwei Möglichkeiten APC zu installieren: Entweder man installiert es über die Paketverwaltung der verwendeten Linux-Distribution, was die Vorteile hat, das man sich über die Abhängigkeiten keine Gedanken machen muss, und das es von der Paketverwaltung (meistens) schon automatisch aktiviert wird. Die andere Möglichkeit ist die Installation mittels PECL.

Installation über die Paketverwaltung

Viele Distributionen bieten bereits Pakete für APC an, ist das bei der verwendeten Distribution nicht der Fall, muss es über PECL installiert werden. Bei Debian heißt das Paket php-apc, bei Gentoo pecl-apc, bei anderen Distributionen wahrscheinlich ähnlich. Hier hilft einem die Suchfunktion der entsprechenden Paketverwaltung.

# Debian
apt-get install php-apc
# Gentoo
emerge pecl-apc

Die meisten Paketverwalter aktivieren APC automatisch (tragen die Erweiterung in eine PHP-Konfigurationsdatei ein), es sollte also nur noch ein Neustart des Webservers nötig sein (siehe weiter unten).

Installation mit PECL

Wenn alle für die Installation benötigten Programme/Abhängigkeiten installiert sind, kann APC mittels folgendem Befehl installiert werden:

pecl install apc

Zur Installation werden die Entwicklerpakete von PHP und dem Webserver (Apache) vorausgesetzt, außerdem werden ein Compiler (gcc), sowie div. andere Entwicklerpakete wie beispielsweise make benötigt. Wenn etwas fehlt, wird PECL einen bei der Installation darauf hinweisen, das entsprechende Programm/Paket kann man dann einfach über die Paketverwaltung installieren.

Mehr Informationen über die Installation von PHP-Erweiterungen mittels PECL finden sich in der PHP-Dokumentation.

Nach der erfolgreichen Installation muss APC noch in einer Konfigurationsdatei von PHP (es kann mehrere geben) eingetragen und der Webserver neugestartet werden.

APC-Modul laden

Nachdem APC installiert wurde, muss noch dafür gesorgt werden, das PHP das Modul auch lädt. Dazu muss in einer Konfigurationsdatei, die PHP beim Start auswertet (z.B. der php.ini) ein Eintrag gemacht werden. Wenn APC über die Paketverwaltung installiert wurde, ist solch ein Eintrag wahrscheinlich sogar schon vorhanden. Dies kann man überprüfen indem man den Webserver neustartet und sich die Ausgabe von phpinfo() ansieht. Ansonsten muss man ihn selbst hinzufügen.

Wo befindet sich die PHP-Konfigurationsdatei?

Um herauszufinden, wo sich die Konfigurationsdatei von PHP befindet, legt man einfach eine PHP-Datei mit folgendem Inhalt an:

<?php phpinfo(); ?>

Wenn man diese Datei nun im Browser aufruft, erhält man eine Übersicht der PHP-Konfiguration. Am Anfang unter dem Eintrag Loaded Configuration File steht, wo sich die Konfigurationsdatei von PHP befindet. Unter additional .ini files parsed finden sich weitere Konfigurationsdateien die von PHP ausgewertet werden, ist hier schon eine apc.ini dabei, hat die Paketverwaltung APC wohl schon aktiviert.

Wichtig: Auf einem produktiven System sollte man die Datei in der phpinfo() aufgerufen wird wieder löschen oder zumindest für normale Benutzer unzugänglich machen, nachdem man die benötigten Informationen hat. Sonst könnte jeder der den Namen der Datei kennt, herausfinden wie der Server konfiguriert ist.

Eintrag in der Konfigurationsdatei

Ist noch kein Eintrag für APC vorhanden, muss er hinzugefügt werden. Dazu schreibt man folgendes in die Konfigurationsdatei:

extension=apc.so

Nach einem Neustart des Webservers sollte APC dann automatisch geladen werden. Das kann ebenfalls in der Ausgabe von phpinfo() überprüft werden, dort müsste irgendwo ein Eintrag mit der Überschrift apc angezeigt werden.

Webserver neustarten

Damit eine geänderte PHP-Konfiguration wirksam wird, muss der Webserver angewiesen werden, diese neu einzulesen. Dazu ist ein Neustart des Webservers erforderlich. Beim Apache kann einer der folgenden beiden Befehle dazu verwendet werden.

apache2ctl graceful
/etc/init.d/apache2 graceful

Nach der Installation

Die Standardkonfiguration ist für die meisten Anwender gut geeignet, einige Optionen wie beispielsweise die Größe des Zwischenspeichers kann man aber noch anpassen. Welche Konfigurationsmöglichkeiten es gibt, wird im Artikel Konfiguration von APC beschreiben.

Es gibt viele Projekte bei denen man dem Benutzer die Möglichkeit geben möchte selbst Dateien auf den Server hochzuladen, beispielsweise bei Bilderhostern, oder Foren, bei denen der Benutzer die Möglichkeit hat Dateien an einen Beitrag anzuhängen. Sowas lässt sich mit PHP problemlos realisieren.

In diesem Artikel beschreibe ich, wie man ein Formular zum Hochladen von Dateien erstellt und wie man die Dateien serverseitig mit PHP behandelt. Außerdem erkläre ich wie mehrere Dateien auf einmal hochgeladen werden können.

Das Dateiformular

Zuerst einmal wird ein Formular benötigt, in dem der Benutzer eine Datei auswählen kann. Ein input-Element vom Typ file erstellt ein Eingabefeld und eine Durchsuchen-Schaltfläche, mittels derer der Benutzer eine Datei auswählen kann. Das versteckte input-Element mit dem Namen MAX_FILE_SIZE ist ein Hinweis für den Browser des Benutzers, value gibt in Bytes an, wie groß eine hochgeladene Datei maximal sein darf. Die Größe der Datei muss natürlich serverseitig noch einmal überprüft werden, da manche Browser die Angabe evtl. nicht beachten, und weil sie leicht umgangen werden kann. PHP überprüft zwar selbst, ob die Datei größer als MAX_FILE_SIZE ist, aber da diese Angabe leicht manipuliert werden kann, bietet diese Überprüfung keine Sicherheit.

<form action="uploaded.php" enctype="multipart/form-data" method="post">
	<fieldset>
		<legend>Datei hochladen</legend>
		<label for="file">Bitte eine Datei ausw&auml;hlen.</label><br />
		<!-- Hinweis fuer den Browser des Benutzers, maximale Dateigroesse -->
		<input type="hidden" name="MAX_FILE_SIZE" value="100000" />
		<!-- Eingabefeld+Durchsuchen-Schaltflaeche -->
		<input type="file" id="file" name="beispieldatei" />
		<!-- Schaltflaeche zum Absenden der Datei -->
		<input type="submit" value="Hochladen" />
	</fieldset>
</form>

Die action-Eigenschaft des form-Elements gibt an, an welche Adresse/Datei die Daten übertragen werden sollen. Mit method wird angegeben, wie die Daten übertragen werden sollen, beim POST-Verfahren sendet der Browser eine spezielle POST-Anfrage mit den Daten an den Server. Die Eigenschaft enctype gibt die Kodierung der übertragenen Daten an, hier muss man multipart/form-data verwenden.

Die hochgeladene Datei verarbeiten

Wenn der Benutzer das Formular absendet wird die unter action angegebene Seite aufgerufen, dabei wird die Datei vom Browser an den Server gesendet. Die Datei wird vom Server in einem temporären Verzeichnis gespeichert. Im PHP-Skript muss diese nun verarbeitet und an ihren Bestimmungsort verschoben werden.
PHP sammelt die wichtigsten Informationen über die Datei im autoglobalen Feld $_FILES. Für jede hochgeladene Datei wird ein Element mit dem gleichen Namen wie das input-Element des Formulars (im Beispiel: beispieldatei) in diesem Feld angelegt. Auch dieses Element ist wieder ein Feld, mit folgenden Elementen:

Beispiel: So könnte der Inhalt von $_FILES nach dem erfolgreichen hochladen einer Datei aussehen.

Verschieben der Datei

Um die Datei nun weiter zu bearbeiten bzw. sie zu speichern, muss sie vom temporären Verzeichnis in das gewünschte Zielverzeichnis verschoben werden. Nach der Ausführung des Skripts wird die Datei gelöscht, falls sie sich noch im temporären Verzeichnis befindet. Um eine Datei nicht zu speichern, genügt es also, sie einfach nicht aus dem temporären Verzeichnis rauszuholen.

$zielverzeichnis = './hochgeladen/';
 
if ($_FILES['beispieldatei']['error'] != UPLOAD_ERR_OK)
	die('Ein Fehler ist aufgetreten.');
 
if (move_uploaded_file($_FILES['beispieldatei']['tmp_name'], 
                       $zielverzeichnis . basename($_FILES['beispieldatei']['name']))) {
	echo "Datei wurde hochgeladen!";
}
else {
	echo "Ein Fehler ist aufgetreten!";
}

Zuerst wird die error-Variable überprüft, wenn ein Fehler aufgetreten ist, bricht das Skript ab. Anschließend wird die Datei mittels move_uploaded_file($datei, $ziel) in das Zielverzeichnis verschoben. Die Funktion überprüft ob es sich bei der übergebenen Datei um eine hochgeladene Datei handelt, ist das nicht der Fall, wird sie nicht verschoben und es wird false zurückgegeben. Konnte die Datei aus irgendeinem Grund nicht verschoben werden, wird ebenfalls false zurückgegeben, sowie eine Warnung ausgegeben. Die Zieldatei wird überschrieben, wenn sie bereits existiert.

Wozu der basename-Aufruf?

Das Beispielskript speichert die Datei unter dem selben Namen, den sie auch auf dem Rechner des Benutzers hat. Die basename($pfad)-Funktion extrahiert den Dateinamen einer Datei aus einer Pfadangabe.

echo basename("/etc/passwd");
// Ausgabe: passwd

Durch den basename-Aufruf wird sichergestellt, das es sich bei dem Dateinamen wirklich um einen Dateinamen und nicht um einen Pfad handelt. Ohne diese Überprüfung könnten böswillige Benutzer möglicherweise dafür sorgen das ihre Dateien in anderen Verzeichnissen als im Zielverzeichnis landen (Sicherheitslücke!).

Die Datei validieren

Um zu verhindern, das Benutzer Dateien hochladen, die dem Server oder anderen Benutzern schaden könnten , oder aus anderen Gründen unerwünscht sind, empfiehlt es sich eine hochgeladene Datei erst zu überprüfen, bevor sie verschoben wird.

• Die Dateigröße. Je nachdem wie die hochgeladenen Dateien verwendet werden, sollte man überprüfen, das der Benutzer keine unsinnig großen (oder kleinen) Dateien hochlädt. Der Speicherplatz auf dem Server ist schließlich begrenzt. Die Variable $_FILES[...]['size'] kann hierzu verwendet werden.
• Die Dateiendung bzw. der MIME-Typ. Oft sind nur bestimmte Arten von Dateien erwünscht, beispielsweise Bilder bei einem Bilderhoster. Unpassende Dateitypen können aussortiert werden. Dateien mit der Endung .php bzw. .php3/.php4/.php5/usw. sollten ebenfalls aussortiert werden, bzw. die Dateiendung sollte geändert werden (beispielsweise zu .phps), ansonsten können die Benutzer ausführbare PHP-Dateien hochladen, was in den meisten Fällen unerwünscht sein dürfte (Sicherheitslücke). Hierzu können die Variablen $_FILES[...]['type'] (MIME-Typ) und $_FILES[...]['name'] (Dateiname) verwendet werden. Mit folgender Funktion lässt sich die Dateiendung aus dem Dateinamen ermitteln:

  function endungErmitteln($dateiname) {
  	if (false !== ($punkt = strrpos($dateiname, '.'))) {
  		if (strlen($dateiname) > $punkt)
  			return substr($dateiname, $punkt + 1);
  	}
  	// Keine Dateiendung
  	return false;
  }

  Es ist noch zu beachten, das es Dateien ohne Endung gibt, und das Dateiendungen in allen möglichen Formen von Groß- und Kleinschreibung vorkommen können (Bsp. Bild.JpEg).

• Der Dateiname. Der Name der Datei kann auf nicht erwünschte Zeichen überprüft werden, außerdem könnte man überprüfen ob der Dateiname nicht zu lang ist.
• Viren und andere Schädlinge. Ein Benutzer könnte (un-)absichtlich eine Datei hochladen die einen Virus bzw. einen Wurm o.Ä. enthält. Es gibt Erweiterungen für PHP, die es einem ermöglichen eine Datei auf solche Schadprogramme zu überprüfen.

  Wie man hochgeladene Dateien automatisch auf Viren überprüft mit php-clamavlib

Mögliche Fehler

Beim Hochladen von Dateien können auch Fehler auftreten, deshalb enthält das $_FILES-Feld im Dateielement auch ein Element namens error, welches angibt ob ein Fehler aufgetreten ist, bzw. um welchen Fehler es sich handelt.

Mögliche Fehlercodes in $_FILES[...]['error']

Mit folgenden Fehlercodes kann der error-Wert verglichen werden, um herauszufinden, was für ein Fehler aufgetreten ist.

Die Überprüfung auf Fehler könnte beispielsweise so aussehen:

$fehlercode = $_FILES['beispieldatei']['error'];
if ($fehlercode != UPLOAD_ERR_OK) {
	echo '<h2>Beim Hochladen ist ein Fehler aufgetreten!</h2>';
	switch($fehlercode) {
		case UPLOAD_ERR_INI_SIZE:
		case UPLOAD_ERR_FORM_SIZE: 
			echo 'Die Datei ist zu gro&szlig;.'; break;
		case UPLOAD_ERR_PARTIAL:
			echo 'Die Datei wurde nur teilweise hochgeladen.'; break;
		case UPLOAD_ERR_NO_FILE:
			echo 'Es wurde keine Datei hochgeladen.'; break;
		default:
			echo 'Ein interner Fehler ist aufgetreten.';
			echo 'Eine E-Mail wurde an den Administrator geschickt.';
			echo 'Bitte versuchen Sie es zu einem späteren Zeitpunkt nochmal.';
			// E-Mail mit dem Fehlercode an den Admin schicken [...] ;-)
			break;
	}
}

Optionen in der php.ini

Die Option upload_max_filesize gibt an, wie groß die Dateien die hochgeladen werden, zusammen maximal sein dürfen. Es wird also beim Hochladen mehrerer Dateien nicht überprüft wie groß die einzelnen Dateien sind, sondern wie groß sie alle zusammen sind. Die Option post_max_size muss ebenfalls beachtet werden, da die Dateien über das POST-Verfahren hochgeladen werden, limitiert auch diese Option die Gesamtgröße der Dateien die hochgeladen werden. Es empfiehlt sich den Wert dieser Option etwas höher einzustellen, da noch andere Formulardaten übertragen werden.

Außerdem gibt es noch die Option file_uploads, ist diese auf off eingestellt, ist es gar nicht möglich, Dateien hochzuladen.

Zusätzlich muss auch die max_input_time beachtet werden, welche angibt wie lange PHP für das Auswerten von POST/GET/REQUEST-Daten brauchen darf. Da das Hochladen von Dateien durchaus lange dauern kann, beispielsweise wenn die Datei sehr groß ist, oder wenn der Benutzer eine langsame Verbindung hat (ISDN, langsame DSL-Verbindungen).

; Ist das Hochladen von Dateien erlaubt?
file_uploads = On 
; Maximale Gesamtgroesse der Dateien die hochgeladen werden
; K = Kilobyte, M = Megabyte, G = Gigabyte.
upload_max_filesize = 100M 
; Maximale Groesse mittels des POST-Verfahrens uebermittelter Daten
post_max_size = 102M 
; Wie lange darf PHP fuer die Auswertung von uebermittelten Daten brauchen?
max_input_time = 3600 ; 1 Stunde

Wenn die Dateien noch weiter verarbeitet werden, also beispielsweise Vorschaubilder erstellt werden o.Ä. muss eventuell auch noch die max_execution_time beachtet werden. Diese gibt an, wie lange PHP-Skripte rechnen dürfen bzw. wie viel Prozessorzeit sie verbrauchen dürfen bevor sie beendet werden. Die Zeit die für Systemaufrufe, Datenbankabfragen o.Ä. aufgewendet wird, fließt nicht in die Berechnung mit ein, sondern nur die Zeit in der das PHP-Skript selbst ausgeführt wird.

Mehrere Dateien auf einmal hochladen

Es ist auch problemlos möglich, mehrere Dateien auf einmal hochzuladen. Dazu fügt man im Formular einfach weitere input-Elemente vom Typ file hinzu. Eine kleine Besonderheit gibt es allerdings zu beachten: Wenn man den Elementen einfach unterschiedliche Namen gibt, werden für jedes Element auch Elemente im $_FILES-Feld erstellt. Wenn man alle Elemente gleich benennt, muss hinter dem Namen [] stehen, das sieht dann z.B. so aus:

<input type="file" id="file" name="datei[]" />
<input type="file" id="file" name="datei[]" />

In diesem Fall würde PHP nur ein Element im $_FILES-Feld erstellen, die Unterelemente davon (name, size, type, etc.) hätten dann aber mehrere Werte/Elemente.

Der PhpDocumentor durchsucht Dateien nach Klassen, Funktionen, Konstanten und Variablen und erstellt automatisch eine Dokumentation. Mit sog. DocBlocks kann man die einzelnen Programmelemente direkt im Quelltext beschreiben, der PhpDocumentor fügt die Informationen aus den DocBlocks dann in der Dokumentation zur entsprechenden Klasse, Funktion, o.Ä. hinzu.

Dadurch, dass die Dokumentation direkt im Quelltext geschieht, entstehen einige Vorteile. Die Dokumentation ist immer auf dem neusten Stand, was bei einer separaten Dokumentation nicht unbedingt der Fall ist. Außerdem ist sie immer vollständig, denn auch wenn man zu einem Element keine Beschreibung geschrieben hat, sind zumindest einige Informationen die PhpDocumentor aus dem Quelltext ausgelesen hat, in der Dokumentation enthalten.

Die wichtigsten Vorteile von PhpDocumentor:

• Die Dokumentation wird automatisch erstellt, PhpDocumentor nimmt einem viel Arbeit ab.
• Sie bleibt immer auf dem neusten Stand und ist immer vollständig.
• Dadurch das die Dokumentation direkt im Quelltext ist, sieht man auch beim Bearbeiten des Quelltextes sofort, was z.B. eine bestimmte Funktion macht.
• Es ist auch möglich auf Anleitungen zu verlinken oder Code in die Dokumentation einzubinden.
• Die Dokumentation kann in viele verschiedene Formate exportiert werden, z.B. als PDF oder CHM (Windows-Hilfedatei). Wenn man die Dokumentation im HTML-Format speichert, hat man die Wahl zwischen 15 verschiedenen Smarty-Vorlagen, und es ist auch möglich eigene Vorlagen oder Exporter zu schreiben.

Ein Beispiel einer komplett mit DocBlocks dokumentierten Datei findet sich hier.

Installation

Es gibt zwei Möglichkeiten PhpDocumentor zu installieren, entweder über PEAR, oder indem man es runterlädt und entpackt. Erstere ist einfacher. Wenn man kein PEAR hat, oder aus irgendeinem anderen Grund lieber die zweite Installationsvariante vorzieht: In der PhpDocumentor-Dokumentation findet sich eine Anleitung zur Installation ohne PEAR.

Installation mittels PEAR

Wenn man PhpDocumentor über die Kommandozeile verwenden möchte, genügt folgender Befehl zur Installation:

pear install --alldeps PhpDocumentor

Will man auch die Weboberfläche verwenden, muss vorher die Option data_dir der PEAR-Konfiguration verändert werden. Sie muss so angepasst werden, das sie den Pfad zum Dokumente-Verzeichnis des Webservers, das ist das Verzeichnis in dem die Webseiten/PHP-Skripte/etc. liegen, enthält.

pear config-set data_dir /pfad/zum/htdocs/verzeichnis/pear/

Anschließend installiert man PhpDocumentor mit obigem Befehl. Nun kann man auch die Weboberfläche verwenden, diese ist, wenn man obigen Befehl verwendet, unter http://localhost/pear/PhpDocumentor zu erreichen.

Die Benutzung von PhpDocumentor

Wenn PhpDocumentor angewiesen wird, ein Projekt zu dokumentieren, werden automatisch alle Elemente wie  Klassen, Funktionen, Variablen und Konstanten aus den Dateien ausgelesen und eine Übersicht erstellt. Eine solche Übersicht ist zwar hilfreich, sie ist aber noch viel nützlicher wenn die Funktion und die Eigenschaften der einzelnen Elemente noch näher erklärt werden.

Dazu verwendet man sog. DocBlocks, das sind spezielle Kommentare, die von PhpDocumentor ausgewertet werden. Ein DocBlock sieht aus wie ein mehrzeiliger Kommentar, wird aber mit /** anstatt von /* eingeleitet, und vor jeder Zeile steht ein Sternchen. Ein DocBlock bezieht sich immer auf das darauffolgende Element. Die erste Zeile ist eine kurze Beschreibung des Elements, durch eine Leerzeile getrennt kann auch noch eine längere Beschreibung geschrieben werden. Darauf können dann noch einige Parameter folgen die weitere Informationen geben.

  /**
   * Aendert den Namen des Films.
   * @param    string   $neuerName Der neue Name des Films.
   * @return   boolean  true bei Erfolg, false wenn ein Fehler aufgetreten ist.
   */
  public function aendereName($neuerName) {
    $this->name = $neuerName;
 
    // liefert true bei Erfolg, false bei Fehlern.
    $ergebnis = $datenbank->aendere($this->filmId, 'name', $neuerName);
 
    return $ergebnis;
  }

Im Beispiel folgen auf die Beschreibung der Funktion noch die beiden Parameter param und return, ersterer beschreibt einen Parameter der Funktion, letzterer den Rückgabewert. Ein Parameter beginnt immer mit einem @-Zeichen. Der entsprechende Teil der Dokumentation könnte dann zum Beispiel so aussehen:

PhpDocumentor erstellt eine Übersicht aller im Projekt vorkommenden Elemente und Dateien. Jedes Element lässt sich dabei auch noch in Kategorien, Pakete und Unterpakete einteilen, wodurch die Dokumentation etwas übersichtlicher wird. So könnte die Klasse Film beispielsweise Teil des Pakets Video sein, welches wiederum Teil von Medienbibliothek ist.

Es ist auch möglich den Autor eines Codes anzugeben, so weiß man, wen man ansprechen kann, wenn man eine Frage hat. Auch Informationen zum Urheberrecht lassen sich in den Quelltext einbauen.

/**
 * Stellt einen Film-Eintrag in der Bibliothek dar.
 *
 * Die Klasse Film bietet Funktionen für den Zugriff auf
 * die in der Bibliothek enthaltenen Informationen ueber
 * den Film.
 *
 * @author     Max Mustermann <maxmustermann@example.de>
 * @package    Medienbibliothek
 * @subpackage Video
 * @version    1.23
 * @copyright  Copyright (c) 2009 Max Mustermann
 * @todo       Die Funktion loeschen() funktioniert noch nicht richtig!
 */
class Film {
// ...

Sehr praktisch ist auch der Parameter todo, mit dem man Hinweise auf unfertige Funktionen, Fehler, oder andere Dinge die noch zu erledigen sind, geben kann.

Mit dem Parameter access ist es auch möglich festzulegen ob das Element in der Dokumentation vorkommen soll, so können zum Beispiel interne Funktionen einer Bibliothek ausgeblendet werden, die den Endanwender nicht interessieren. Für die Entwickler der Bibliothek kann dann eine separate Dokumentation generiert werden, welche diese Elemente dann auch enthält.

Eine Übersicht der wichtigsten Parameter

Eine Übersicht aller verfügbaren Parameter gibt es in der Dokumentation von PhpDocumentor.

Code einbinden

Manchmal möchte man eine Funktion oder Klasse direkt an einem Beispiel beschreiben, auch das ist kein Problem, denn mit dem <code>-Element lässt sich auch Quelltext direkt in die Beschreibung einbinden.

/**
   * Loescht den Film aus der Datenbank
   *
   * Diese Funktion wird wie folgt benutzt:
   * <code>
   * $ergebnis = $film->loeschen();
   * if (!$ergebnis) echo "Film konnte nicht geloescht werden!";
   * </code>
   * Und so weiter ...
   */

Externe Dokumentation

Bei sehr langen Beschreibungen ist es sinnvoll, diese auszulagern. Der Quelltext würde ziemlich unübersichtlich werden, wenn mittendrin umfassende Anleitungen zur Benutzung von bestimmten Funktionen oder Klassen stehen würden. Dazu können die Parameter @link und @tutorial verwendet werden. Wie das funktioniert wird im Handbuch vom PhpDocumentor erklärt.

Erstellen der Dokumentation

Die Dokumentation kann entweder über die Kommandozeile oder über die Weboberfläche erstellt werden.

Mit dem Kommandozeilen-Programm phpdoc

Die Bedienung von phpdoc ist im Grunde ganz einfach, ein Beispiel:

phpdoc -t dokumentation/ -d meinprojekt/

Der Befehl würde alle PHP-Dateien im Verzeichnis meinprojekt durchgehen, eine Dokumentation daraus erstellen, und diese im Verzeichnis dokumentation ablegen.

Mit dem Parameter -t <Verzeichnis> wird also angegeben, wo die Dokumentation gespeichert werden soll, -d <Verzeichnis> gibt ein Verzeichnis (oder mehrere, durch Kommas getrennt) an, das nach PHP-Dateien durchsucht werden soll. Mit -f <Datei>[,<Datei>, ...] kann man noch weitere Dateien angeben, die für die Dokumentation ausgewertet werden sollen.

Mittels -ti 'Titel der Dokumentation' lässt sich der Titel festlegen, mit -o <Format> lassen sich die Ausgabeformate bestimmen. Ein Beispiel:

phpdoc -ti 'Mein PHP-Projekt' -f beispiel.php -o html:smarty:hands,pdf:default:default -t docs/

Der Befehl würde eine Dokumentation für das Projekt mit dem Namen Mein PHP-Projekt erstellen. Es wird nur die Datei beispiel.php ausgewertet, die Dokumentation wird im PDF-Format und im HTML-Format, mit der Vorlage Smarty/HandS, erstellt.

Mit der Weboberfläche

Die Weboberfläche ist sogar noch einfacher zu bedienen, als die Kommandozeilen-Version. Unter Files gibt man die Dateien und Verzeichnisse an, die dokumentiert werden sollen. Unter Output wird bei Target eingetragen wo die Dokumentation gespeichert werden soll, mittels Output Format lässt sich festlegen in welchem Format (HTML, PDF, CHM, etc.) die Dokumentation erstellt werden soll, und welche Vorlage verwendet wird. Dabei ist es auch möglich gleich mehrere Ausgabeformate anzugeben. Unter Config lassen sich noch der Name des Projekts und ein paar andere Einstellungen konfigurieren. Mit einem Klick auf create (unten rechts) wird die Dokumentation erstellt.

hallo.php:
<?php
echo "Hallo";
include 'welt.php';
?>
 
welt.php:
<?php
echo " Welt!";
?>

Wenn man die hallo.php nun aufruft, würde Hallo Welt! ausgegeben werden. Der Inhalt der welt.php wurde an der Stelle von include 'welt.php' eingefügt (auch: inkludiert, oder eingebunden).

Die include-Anweisung ist ein Sprachkonstrukt, und keine Funktion! Deswegen kann sie auch ohne Klammern geschrieben werden, das sollte man sich auch angewöhnen, denn es gibt Fälle in denen die Klammern weggelassen werden müssen.

Anweisungen zum Einbinden von Dateien

Es gibt 4 Anweisungen zum Einbinden von Dateien: include, require, include_once und require_once.

• Wenn eine mittels include eingebundene Datei nicht gefunden wurde, wird eine Warnung ausgegeben. Wurde die Datei mittels require eingebunden, wird zusätzlich zu der Warnung noch ein Fataler Fehler ausgegeben, wodurch die Skriptausführung abgebrochen wird.
• include_once und require_once inkludieren eine Datei nur wenn sie noch nicht inkludiert wurde, das ist nützlich um zu vermeiden das Variablen, Funktionen oder Klassen mehrmals definiert werden (was zu einem Fehler führen würde).

Funktionsweise: Inkludieren

Wenn eine Datei inkludiert wird, springt der PHP-Interpreter am Anfang der inkludierten Datei aus dem Parse-Modus raus, und setzt das Parsen erst am Ende der inkludierten Datei fort. Wenn man also PHP-Quelltext inkludieren möchte, muss man auch in der zu inkludierenden Datei Start- und Endtags (<?php und ?>) einfügen, ansonsten wird der Quelltext vom PHP-Interpreter nicht interpretiert (also nur ausgegeben).

Wenn bei der Interpretation der inkludierten Datei ein Fehler auftritt, beispielsweise aufgrund eines Syntax-Fehlers (z.B. einem vergessenen Semikolon), wird die Ausführung des kompletten Skripts beendet.

Der include_path

Der include_path gibt an, wo PHP die zu inkludierende Datei suchen soll, dabei können auch mehrere Pfade angegeben werden. Wenn eine Datei inkludiert wird, sucht PHP sie unter den im include_path angegebenen relativen Pfaden, zuerst relativ zum Arbeitsverzeichnis, danach relativ zu dem Verzeichnis in dem sich das aktuelle Skript befindet. Danach werden die absoluten Pfade im include_path durchsucht.

• Der aktuelle include_path kann mittels der Funktion get_include_path() abgefragt werden. Die Funktion liefert den/die Pfade als Zeichenkette, getrennt durch Doppelpunkte (Linux/Unix) bzw. Semikolons (Windows) zurück.
• Mit set_include_path(string $pfad) lässt sich der include_path ändern, die Konstante PATH_SEPARATOR kann verwendet werden um die einzelnen Pfade zu trennen, da ja unter Windows andere Separatoren (Semikolons) als unter Linux/Unix verwendet werden.
• Das aktuelle Arbeitsverzeichnis lässt sich mit der Funktion getcwd() ermitteln. Normalerweise ist es das Verzeichnis, in dem die vom Benutzer aufgerufene Datei liegt.

Ein kleines Beispiel:

/htdocs/test/index.php:
<?php
echo get_cwd();                // Arbeitsverzeichnis: /htdocs/test/
echo get_include_path();       // include_path: .:bla:/lib/php
                               // (also . und bla und /lib/php)
include 'classes/test.php';
?>
 
htdocs/test/classes/test.php:
<?php
include 'bla.php';             // (befindet sich ebenfalls in classes/)
 
?>

In diesem Beispiel würde PHP wie folgt vorgehen:

Sobald die Datei gefunden wurde, wird sie inkludiert, PHP sucht dann natürlich nicht mehr weiter.

Was hat es mit . und .. auf sich?

Der Punkt steht unter Unix/Linux für das aktuelle Verzeichnis, .. steht für das übergeordnete Verzeichnis. Der Pfad /test/./xyz hat die selbe Bedeutung wie /test/xyz, /test/../xyz wäre aber /xyz. Obwohl sie eigentlich aus der Unix-Welt kommen, funktionieren . und .. auch, wenn man PHP unter Windows benutzt. Übrigens: Wenn man vor den Pfad einer inkludierten Datei einen . bzw. .. setzt, wird der include_path ignoriert, PHP sucht dann relativ zum Skript-Verzeichnis nach der Datei.

include './datei_im_selben_verzeichnis.php';
include '../datei_im_uebergeordneten_verzeichnis.php';

Der Geltungsbereich von Variablen

Inkludierte Dateien übernehmen den Geltungsbereich von der Stelle, an der sie inkludiert werden. Alles was im dortigen Geltungsbereich liegt, ist auch in der inkludierten Datei verfügbar. Variablen die in der inkludierten Datei definiert werden übernehmen ebenfalls den Geltungsbereich von der Stelle an der die Datei inkludiert wurde. Alle Klassen und Funktionen die in der inkludierten Datei definiert werden, sind aber global sichtbar.

hallowelt.php:
<?php
function hallo() {
    $hallo = "Hallo Welt!";
    include 'ausgeben.php';
    var_dump($ausgegeben); // bool(true)
}
hallo();
var_dump($ausgegeben); // NULL
?>
ausgeben.php:
<?php
echo $hallowelt; // Hallo Welt!
$ausgegeben = true;
?>

Entfernte Dateien

Wenn in der PHP-Konfigurationsdatei allow_url_fopen und allow_url_include aktiviert sind, ist es auch möglich Dateien von anderen Servern zu inkludieren. Diese Dateien werden auch von PHP interpretiert, d.h. enthaltener PHP-Quelltext wird ausgeführt!

include 'http://www.example.com/skript.php';

Hierbei muss man allerdings beachten, das der Server auf dem die zu inkludierende Datei liegt, den PHP-Quelltext nicht schon interpretiert bzw. das der Server auch PHP-Quelltext ausgibt.

Rückgabewerte

Innerhalb einer inkludierten Datei kann man wie bei Funktionen mit return zurückspringen, es ist auch möglich ein Ergebnis bzw. einen Rückgabewert zu übergeben. Wenn eine inkludierte Datei keinen Rückgabewert mittels return zurückgibt, gibt include 1 zurück (Inkludieren erfolgreich) oder false (Inkludieren nicht erfolgreich, z.B. wenn die Datei nicht gefunden wurde).

test.php:
<?php
$ergebnis = include 'berechnung.php';
echo $ergebnis; // 42
?>
berechnung.php:
<?php
$zahl = 40 + 2;
return $zahl;
echo "Das hier wird nie ausgegeben.";
?>

Bei entfernten Dateien geht das allerdings nicht (so einfach). Man kann aber auch bei entfernten Dateien Werte zurückgeben, indem man sie einfach als Variablen definiert. In inkludierten Dateien definierte Variablen sind ja auch in der Datei die sie inkludieren verfügbar.

<?php $rueckgabewert = 42; ?>

Wenn man mit dem Rückgabewert einer inkludierten Datei arbeitet, sollte man darauf achten, dass man die include-Anweisung ohne Klammern schreibt, in manchen Fällen kann es sonst dazu kommen das PHP die Anweisung falsch interpretiert.

// So ist es falsch! PHP würde hier folgendes tun:
// ('berechnung.php') mit 42 vergleichen = false (sind nicht gleich)
// include erwartet eine Zeichenkette, false wird zu einer Zeichenkette umgewandelt,
// dabei kommt '' (leere Zeichenkette) raus.
// dann würde PHP versuchen '' zu inkludieren, das klappt nicht.
// include gibt false zurück, der Code in der if-Bedingung wird nicht ausgeführt.
if (include('berechnung.php') == 42) {
    echo "Ergebnis stimmt!";
}
// So funktioniert es richtig.
if ((include 'berechnung.php') == 42) {
    echo "Ergebnis stimmt!";
}

Automatisches Anhängen/Voranstellen von Dateien

Man kann PHP so konfigurieren, das an jede interpretierte Datei eine Datei angehängt bzw. vorangestellt wird, als würde sie am Anfang bzw. am Ende der Datei mittels der require-Anweisung inkludiert werden. Dazu trägt man in der php.ini bei den Optionen auto_prepend_file (Voranstellen) bzw. auto_append_file (Anhängen) den Pfad zu der entsprechenden Datei ein. Der include_path wird beim Inkludieren der Dateien beachtet.

; Automatically add files before or after any PHP document.
auto_prepend_file = /htdocs/header.php
auto_append_file = /htdocs/footer.php

Wenn dort nichts oder none steht, wird keine Datei angehängt bzw. vorangestellt.

Hinweis: Wenn das PHP-Skript mit der Funktion exit() beendet wird, wird keine Datei angehangen.

Automatisches Nachladen von Klassen

Wenn man objektorientierte Anwendungen schreibt, hat man oft viele Quelldateien, eine für jede Klasse. Am Anfang einer Datei steht meist eine lange Liste von include-Anweisungen, um alle benötigten Klassendefinitionen zu laden. Mit PHP 5 ist es auch möglich Klassen dynamisch nachzuladen, dazu wird die __autoload-Funktion verwendet. Wenn PHP bei der Interpretation des Quelltextes auf eine noch nicht definierte Klasse stößt und es eine __autoload-Funktion gibt, ruft es Funktion auf, in der dann die Quelldatei für die entsprechende Klasse gesucht und inkludiert wird. So spart man sich eine Menge Schreibarbeit.

Automatisches Nachladen von Klassen mit PHP

Die Geschwindigkeit

Jan Walther hat in seinem PHP-Performance-Blog zwei interessante Artikel geschrieben bei deinen es um die Geschwindigkeit der Anweisungen zum Inkludieren von Dateien geht. Im ersten Artikel PHP-Dateien in andere Scripts einbinden analysiert er die Geschwindigkeit von include, require, include_once und require_once, und kommt zum Schluss das es keine merklichen Unterschiede gibt.

Im Artikel Dateien performant einfügen beschreibt er die Unterschiede zwischen absoluten, semiabsoluten und relativen Pfaden, und wie sie sich auf die Geschwindigkeit auswirken. Außerdem beschreibt er eine Methode, mit der sich Dateien mit ihrem absoluten Pfad inkludieren lassen, ohne das man dabei auf die Flexibilität von relativen Pfaden verzichten muss.

Vorteile von Ausnahmen

• Mit Ausnahmen lässt sich die Fehlerbehandlung vom normalen Code trennen, wodurch der Quelltext übersichtlicher wird.
• Ausnahmen bieten einem mehr Kontrolle und Flexibilität bei der Fehlerbehandlung. Fehler können an der Stelle im Quelltext behandelt werden, an der man am besten darauf reagieren kann.
• Sie erleichtern die Fehlersuche und vermeiden das Übersehen von Fehlern. Bei der Fehlerbehandlung mittels Rückgabewerten kann es passieren das man vergisst einen Rückgabewert zu prüfen. Das Skript arbeitet dann einfach weiter, und es kann zu unerwarteten Ergebnissen kommen. Die Ursache solcher Fehler zu finden ist sehr schwer, besonders wenn sie nur selten oder unter bestimmten Umständen auftreten. Mit Ausnahmen kann das nicht passieren, eine nicht behandelte Ausnahme bricht die Skript-Ausführung ab.

Ein kleines Beispiel

Der folgende Quelltext gibt eine zufällige Zeile aus der Datei zitate.txt aus, zur Fehlerbehandlung wird der Rückgabewert überprüft.

function zitat() {
	$handle = fopen('zitate.txt', 'r');
	if ($handle === FALSE) {
		echo "Öffnen der Datei ist fehlgeschlagen";
		return NULL;
	}
 
	$zitate = array();
	while (!feof($handle)) {
		$zitat = fgets($handle);
		if (!empty($zitat))
			$zitate[] = $zitat;
	}
 
	fclose($handle);
 
	if (!count($zitate)) {
		echo "Keine Zitate gefunden.";
		return NULL;
	}
 
	return $zitate[array_rand($zitate)];
}
 
$lustiges_zitat = zitat();
if ($lustiges_zitat !== NULL)
	echo $lustiges_zitat;

Die Funktion zitat() gibt eine Fehlermeldung aus und liefert den Wert NULL zurück wenn ein Fehler auftritt. Man könnte die Funktion auch so umschreiben, dass sie anstatt NULL einen Fehlercode zurückgibt.

Anstatt jedoch die Funktion einen Rückgabewert, der einen Fehler anzeigt, zurückgeben zu lassen kann man sie auch einfach eine Ausnahme auslösen lassen die alle für die Fehlerbehandlung benötigten Informationen enthält. Denn möglicherweise kann man innerhalb der Funktion bzw. bei deren Aufruf gar nicht angemessen auf den Fehler reagieren. Ausnahmen werden so lange an aufrufende Funktionen zurückgereicht bis sie gefangen werden. So kann den Fehler an der Stelle behandeln an der man am besten darauf reagieren kann.

Beispielsweise könnte man den Fehler das keine Zitate gefunden wurden an einer Stelle behandeln an der bekannt ist ob der Benutzer eingeloggt ist und neue Zitate in die Textdatei einfügen darf. Ist das der Fall könnte man zusätzlich zur Fehlermeldung noch einen Link zu einer Seite anzeigen, auf der man neue Zitate in die Datei schreiben kann.

Der selbe Quelltext mit Ausnahmen zur Fehlerbehandlung könnte so aussehen:

function zitat() {
	$handle = fopen('zitate.txt', 'r');
	if ($handle === FALSE)
		throw new Exception("Konnte die Datei nicht öffnen.", 1);
 
	$zitate = array();
	while (!feof($handle)) {
		$zitat = fgets($handle);
		if (!empty($zitat))
			$zitate[] = $zitat;
	}
 
	fclose($handle);
 
	if (!count($zitate))
		throw new Exception("Keine Zitate gefunden.", 2);
 
	return $zitate[array_rand($zitate)];
}
 
try {
	echo zitat();
}
catch (Exception $e) {
	echo "<h1>Fehler</h1>" . $e->getMessage();
	if ($e->getCode() == 2 && $berechtigungen['zitat_hinzufuegen'])
		echo '<a href="neu.php">Neues Zitat hinzufügen</a>';
}

In dieser Variante wird ein Link zum Hinzufügen neuer Zitate angezeigt wenn keine Zitate gefunden wurden. Wenn man an dieser Stelle nicht überprüfen kann ob der Benutzer überhaupt die Rechte dazu hat, könnte man die Ausnahme auch an einer anderen Stelle abfangen, an der man das überprüfen kann.

Funktionsweise von Ausnahmen

Eine Ausnahme wird mit dem Schlüsselwort throw “geworfen” und mit catch gefangen bzw. behandelt. Es können nur Objekte der Ausnahmeklasse Exception oder davon abgeleiteten Klassen geworfen werden.

throw new Exception("Es ist was schiefgegangen.");

Jede geworfene Ausnahme muss auch irgendwo gefangen werden, ansonsten bricht die Ausführung des Skripts mit einer Fehlermeldung wie dieser ab:

Fatal error: Uncaught exception 'Exception' with 
message 'Es ist was schiefgegangen.' in /www/exception.php:37 
Stack trace: #0 {main} thrown in /www/exception.php on line 37

Innerhalb eines try-Blocks werden Ausnahmen gefangen, auf einen try-Block muss immer mindestens ein catch-Block folgen welcher die Ausnahme behandelt. Es ist möglich mehrere catch-Blöcke an einen try-Block anzuhängen um verschiedene Ausnahme-Klassen verschieden zu behandeln. Ein kleines Beispiel:

class SchlimmerFehler extends Exception {}
 
try {
    /* Hier der Quelltext in dem eine Ausnahme auftreten kann */
    if ($var == 1) {
        throw new Exception("Es ist was schiefgegangen.");
        echo "Dieser Text wird niemals ausgegeben!";
    }
    else
        throw new SchlimmerFehler("Das hat nicht geklappt.");
}
catch (SchlimmerFehler $e) {
    echo "Ein ganz schlimmer Fehler ist aufgetreten! ", $e->getMessage();
    die();
}
catch (Exception $e) {
    echo "Ein Fehler ist aufgetreten: ", $e->getMessage();
}

Wird keine Ausnahme geworfen, überspringt PHP einfach die catch-Blöcke und macht dahinter weiter. Wenn im try-Block eine Ausnahme geworfen wird, springt PHP direkt, ohne den restlichen Code im try-Block auszuführen, zum ersten catch-Block.

Wenn die Klasse im catch-Block mit der Klasse der geworfenen Ausnahme übereinstimmt, oder von ihr abgeleitet ist, wird der catch-Block ausgeführt, ansonsten springt PHP zum nächsten catch-Block weiter. Es wird immer nur der erste catch-Block ausgeführt der passt.

Es ist auch möglich innerhalb eines catch-Blocks eine Ausnahme zu werfen, und try-Blöcke können auch verschachtelt werden.

class SchlimmerFehler extends Exception {}
class GanzSchlimmerFehler extends Exception {}
 
try {
	try {
		try {
			throw new SchlimmerFehler("Das hat nicht geklappt.");
		}
		catch (GanzSchlimmerFehler $e) {
			// Wird nicht ausgeführt. Dieser catch-Block wird
			// nur ausgeführt wenn die geworfene Ausnahme ein 
			// Objekt der Klasse GanzSchlimmerFehler ist (oder
			// von ihr abgeleitet).
		}
	}
	catch (Exception $e) {
		// SchlimmerFehler ist von Exception abgeleitet, also
		// wird dieser Block ausgeführt.
 
		// Man kann Ausnahmen auch einfach weiterwerfen.
		throw $e;
	}
}
catch (Exception $e) {
	// Hier wird die Ausnahme wieder gefangen und die Fehler-
	// meldung wird ausgegeben.
    echo "Ein Fehler ist aufgetreten: ", $e->getMessage();
}
catch (SchlimmerFehler $e) {
	// Dieser catch-Block wird niemals ausgeführt. SchlimmerFehler
	// ist von der Klasse Exception abgeleitet, und der catch-Block 
	// vor diesem hier fängt bereits alle von Exception  
	// abgeleiteten Ausnahme-Klassen ab.
}

Wie man an dem Beispiel sehen kann, ist es wichtig das die catch-Blöcke in der richtigen Reihenfolge sind. Der letzte catch-Block des Beispiels würde nie ausgeführt werden, weil der Block davor bereits alle Ausnahmen (bzw. alle der Klasse Exception und davon abgeleiteten, was allen entspricht) abfängt.

Die Klasse Exception

Die Ausnahmeklasse Exception bietet noch mehr als nur die Möglichkeit eine Fehlermeldung und einen Fehlercode auszugeben. Sie ist wie folgt aufgebaut.

class Exception {
	protected $message = 'Unknown Exception'	// Fehlermeldung
	protected $code = 0;				// Fehlercode
 
	// Dateiname der Datei in der die Ausnahme aufgetreten ist.
	protected $file;
 
	// Zeile in der die Ausnahme aufgetreten ist.
	protected $line;
 
	function __construct($message = NULL, $code = 0);
 
	// Formatierte Zeichenkette für die Ausgabe
	function __toString();
 
	// Diese Funktionen können nicht überschrieben werden.
	final function getMessage();
	final function getCode();
	final function getFile();
	final function getLine();
	final function getTrace();
	final function getTraceAsString();
}

Eine Besonderheit stellt die Funktion getTrace bzw. getTraceAsString dar. Mit ihr lässt sich der Ablauf bis zum Fehler zurückverfolgen, ein Beispiel:

#0 /www/exception.php(4): test('Test', 123)
#1 /www/exception.php(6): test2(123)
#2 {main}

Der dazugehörige Code ist folgender:

3
4
5
6
7
8
9

function test($a, $b) { throw new Exception("Es ist was schiefgelaufen.", 100); }
function test2($var) { test("Test", $var); }
 
try { test2(123); }
catch (Exception $e) {
	echo  $e->getTraceAsString();
}

Eigene Exception-Klassen

Es ist auch möglich eigene Klassen von Exception abzuleiten, und diese je nach Bedarf noch um eigene Informationen oder Funktionen zu erweitern. Man könnte beispielsweise eine Ausnahmeklasse für nicht gefundene Dateien schreiben.

class DateiNichtGefunden extends Exception {
	protected $dateiname;
 
	public function __construct($name) {
		$this->dateiname = $name;
 
		// Sicherstellen das alles richtig zugewiesen wird
		parent::__construct("Datei nicht gefunden", 123);
	}
 
	public function datei() {
		return $this->dateiname;
	}
 
	public function __toString() {
		return "Die Datei »{$this->dateiname}« wurde nicht gefunden.";
	}
}

Man kann so viele Methoden und Eigenschaften hinzufügen wie man möchte, wichtig ist nur das man im Konstruktor am Ende parent::__construct($fehlermeldung, $fehlercode); aufruft, damit sichergestellt ist, dass alle Daten korrekt zugewiesen werden.

Ungefangene Ausnahmen behandeln

Wenn eine Ausnahme nicht gefangen wird, wird die Ausführung des Skripts abgebrochen und die Standardfunktion zum Behandeln von Ausnahmen aufgerufen. Es ist aber auch möglich diese Standardfunktion durch eine eigene zu ersetzen.

function ungefangene_ausnahme($e) {
	echo "Ungefangene Ausnahme: ", $e->getMessage();
}
 
set_exception_handler('ungefangene_ausnahme');

Dazu wird die Funktion set_exception_handler('name_der_funktion') verwendet. Wichtig ist, dass die Funktion einen Parameter annimmt (die ungefangene Ausnahme), und das sie deklariert wird bevor eine Ausnahme geworfen wird die nirgends gefangen wird. Mit restore_exception_handler lässt sich die vorherige Funktion zur Ausnahmebehandlung wiederherstellen.

Die Standardausgabe von PHP die angezeigt wird wenn eine Ausnahme nicht gefangen wird ist ziemlich unübersichtlich, wie man diese mittels set_exception_handler etwas übersichtlicher gestalten kann beschreibt Stephan Linzner in seinem Artikel PHP Exceptions Formatieren.

Wofür sind Ausnahmen nicht gedacht?

Ausnahmen sollten nur verwendet werden wenn, wie der Name es schon sagt, eine Ausnahme bzw. ein Fehler auftritt. Sie sind nicht dazu gedacht den Programmablauf zu steuern! Im Normalfall sollte ein Skript komplett durchlaufen, ohne das eine Ausnahme geworfen wird.

Beispiel: Für solche Zwecke sollte man Ausnahmen nicht verwenden

try {
	if (array_search($benutzername, $benutzer) !== FALSE)
		throw BenutzerExistiert();
	else
		throw BenutzerExistiertNicht();
}
catch (BenutzerExistiert $e)
// ...

Torsten Zander gibt in seinem Artikel Exceptions Fangen und Werfen noch ein paar Tipps wie man Ausnahmen richtig einsetzt.