PHP-Handbuch: Prüft ab, ob eine Zusicherung FALSE ist

Beschreibung

PHP 5 und 7

bool assert ( mixed $assertion [, string $description ] )

PHP 7

bool assert ( mixed $assertion [, Throwable $exception ] )

assert überprüft den übergebenen Parameter assertion und verfährt entsprechend, falls die in assertion spezifizierte Bedingung FALSE ist.

Traditionelle Zusicherungen (PHP 5 und 7)

Wird der Parameter assertion als String übergeben, so wird der String als PHP-Code interpretiert. Vorteile der Übergabe des Parameters assertion als Zeichenkette sind geringerer Mehraufwand, wenn die Zusicherungsprüfung deaktiviert ist, und dass die ausgegebene Meldung die über assertion übergebene Zeichenkette enthält. Das bedeutet, dass bei Übergabe einer booleschen Bedingung an assertion, eine solche nicht als Parameter an die Zusicherungsfunktion, die möglicherweise per assert_options Funktion definiert wurde, auftaucht; die Bedingung wird vor dem Aufruf der Handler-Funktion in eine Zeichenkette umgewandelt, und der boolesche Wert FALSE wird dabei zur leeren Zeichenkette konvertiert.

assert sollte nur zum Debuggen des Codes verwendet werden. Es kann für Plausibilitätsprüfungen verwendet werden, um auf Bedingungen zu prüfen, die immer TRUE sein sollten, und die andernfalls Programmierfehler anzeigen, oder um auf die Verfügbarkeit bestimmter Merkmale, wie Erweiterungsfunktionen oder bestimmte Systembeschränkungen und Eigenschaften, zu prüfen.

Zusicherungen sollten nicht für normale Laufzeitoperationen wie die Überprüfung von Eingaben verwendet werden. Als Faustregel sollte der Code immer korrekt funktionieren können, auch wenn die Zusicherungsüberprüfung deaktiviert ist.

Die Optionen für die assert können über die Funktion assert_options oder durch ini Settings, die in der Handbuchseite dieser Funktion beschrieben werden, eingestellt werden.

Die Funktion assert_options und/oder die ASSERT_CALLBACK Direktive ermöglicht eine Funktion anzugeben, die bei fehlschlagender Überprüfung aufgerufen wird.

Callback-Funktionen in Zusammenhang mit assert sind nützlich, um beispielsweise automatisierte Tests durchzuführen, da die Callback-Funktion über die Information verfügt, von welcher Stelle sie aufgerufen wurde. Auch wenn diese Information mit anderen Methoden zugänglich ist, macht es die Verwendung von Zusicherungen viel schneller und leichter!

Die Callback-Funktion wird mit drei Parametern aufgerufen. Der erste Parameter enthält den Namen des Scripts, in dem die Überprüfung statt fand, der zweite Parameter die Zeilennummer, und der dritte Paramter enthält die über assertion angegebene Bedingung (wobei Literale wie 1 oder "zwei" nicht übergeben werden). Nutzer von PHP 5.4.8 und höher können ebenfalls ein viertes optionales Argument angeben, das die description, die an assert übergeben wurde, enthält, wenn diese gesetzt wurde.

Erwartungen (nur PHP 7)

assert ist in PHP 7 ein Sprachkonstrukt, das die Definition von Annahmen ermöglicht: Zusicherungen, die in Entwicklungs- und Testumgebungen wirken, aber so optimiert werden, dass sie in Produktionsumgebungen keinen Mehraufwand verursachen.

Während assert_options noch immer verwendet werden kann, um das oben beschriebene Verhalten aus Gründen der Abwärtskompatibilität zu steuern, sollte Code, der nur für PHP 7 geschrieben wird, die beiden neuen Konfigurationsoptionen zur Steuerung von assert verwenden, und nicht assert_options aufrufen.

**PHP 7 Konfigurationsdirektiven für assert**
Direktive	Vorgabewert	Mögliche Werte
zend.assertions	1	1: erzeugt Code und führt ihn aus (Entwicklungsmodus) 0: erzeugt Code, aber führt ihn zur Laufzeit nicht aus -1: erzeugt keinen Code (Produktionsmodus)
assert.exception	0	1: löst eine Exception aus, wenn die Zusicherung fehlschlägt; entweder das Objekt, das als `exception` übergeben wurde, oder ein neues AssertError Objekt, wenn `exception` nicht angegeben wurde. 0: verwendet oder erzeugt eine Throwable Ausnahme wie oben beschrieben, aber erzeugt nur eine Warnung, die auf diesem Objekt basiert, anstatt eine Exception auszulösen (kompatibel zum Verhalten unter PHP 5).

Parameter-Liste

assertion: Die Zusicherung. In PHP 5 muss dies entweder ein auszuwertender string sein, oder ein zu testender boolean Ausdruck. In PHP 7 kann dies ebenso ein beliebiger Ausdruck, der einen Wert zurückgibt, sein, der ausgeführt und dessen Ergebnis verwendet wird, um anzuzeigen, ob die Zusicherung erfolgreich war oder fehlschlug.
description: Eine optionale Beschreibung, die in der Fehlermeldung enthalten sein wird, wenn die assertion fehlschlägt.
exception: In PHP 7 kann der zweite Parameter ein Throwable Objekt anstatt eines beschreibenden strings sein, so dass dieses Objekt als Exception geworfen wird, wenn die Zusicherung fehlschlägt und die assert.exception Konfigurationsdirektive aktiviert ist.

Rückgabewerte

FALSE wenn die Zusicherung nicht erfüllt ist, TRUE anderfalls.

Changelog

Version	Beschreibung
7.0.0	assert ist nun ein Sprachkonstrukt und keine Funktion mehr. assertion kann nun ein Ausdruck sein. Der zweite Parameter wird nun entweder als `exception` interpretiert (wenn ein Throwable Objekt übergeben wird), oder als `description`, was ab PHP 5.4.8 unterstützt wird.
5.4.8	Der `description` Parameter wurde hinzugefügt. Die `description` wird nun ebenfalls zu einer Callbackfunktion im `ASSERT_CALLBACK` Modus als viertes Argument übergeben.

Beispiele

Traditionelle Zusicherungen (PHP 5 und 7)

Beispiel #1 Überprüfung mit benutzerdefinierter Funktion


<?php
// Zusicherungen aktivieren und stumm schalten
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Eine Handlerfunktion erzeugen
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Zusicherung fehlgeschlagen:
        Datei '$file'<br />
        Zeile '$line'<br />
        Code '$code'<br /><hr />";
}

// Den Callback definieren
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Eine fehlschlagende Zusicherung
assert('mysql_query("")');
?>

Beispiel #2 Verwendung eines benutzerdefinierten Handlers um eine Beschreibung anzuzeigen


<?php
// Zusicherungen aktivieren und stumm schalten
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Eine Handlerfunktion erzeugen
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Zusicherung fehlgeschlagen in $file:$line: $code";
    if ($desc) {
        echo ": $desc";
    }
    echo "\n";
}

// Den Callback definieren
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Fehlschlagende Zusicherungen
assert('2 < 1');
assert('2 < 1', 'Zwei ist kleiner als Eins');
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

 Zusicherung fehlgeschlagen in test.php:21: 2 < 1
 Zusicherung fehlgeschlagen in test.php:22: 2 < 1: Zwei ist kleiner als Eins

Annahmen (nur PHP 7)

Beispiel #3 Annahmen ohne benutzerdefinierte Exception


<?php
assert(true == false);
echo 'Hi!';
?>

Ist zend.assertions auf 0 gesetzt, gibt das obige Beispiel aus:

Hi!

Ist zend.assertions auf 1 und assert.exception auf 0 gesetzt, gibt das obige Beispiel aus:

Warning: assert(): assert(true == false) failed in - on line 2
Hi!

Ist zend.assertions auf 1 und assert.exception auf 1 gesetzt, gibt das obige Beispiel aus:

Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
  thrown in - on line 2

Beispiel #4 Annahmen mit einer benutzerdefinierten Exception


<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True ist nicht false!'));
echo 'Hi!';
?>

Ist zend.assertions auf 0 gesetzt, gibt das obige Beispiel aus:

Hi!

Ist zend.assertions auf 1 und assert.exception auf 0 gesetzt, gibt das obige Beispiel aus:

Warning: assert(): CustomError: True ist nicht false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!

Ist zend.assertions auf 1 und assert.exception auf 1 gesetzt, gibt das obige Beispiel aus:

Fatal error: Uncaught CustomError: True ist nicht false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

Siehe auch

assert_options