assert
(PHP 4, PHP 5, PHP 7, PHP 8)
assert — Überprüft eine Assertion (Zusicherung)
Beschreibung
assert(
mixed $assertion
,
Throwable|string|null $description
= null
):
bool
Zusicherungen sollten nur zur Fehlersuche verwendet werden. So können sie
z. B. für Plausibilitätsprüfungen für Vorbedingungen verwendet werden, die
immer true
sein sollten, und die andernfalls auf Programmierfehler
hinweisen. Ein weiterer Anwendungsfall ist, sicherzustellen, dass bestimmte
Merkmale wie Funktionen von Erweiterungen oder bestimmte Grenzwerte und
Eigenschaften des Systems vorhanden sind.
Da Zusicherungen so konfiguriert werden können, dass sie deaktiviert
werden, sollten sie nicht für normale
Laufzeitoperationen wie die Überprüfung von Eingabeparametern verwendet
werden. Als Faustregel gilt, dass sich der Code auch bei deaktivierter
Zusicherungsüberprüfung so verhalten sollte wie erwartet.
assert() prüft, ob die in
assertion
angegebene Annahme zutrifft. Wenn dies
nicht der Fall ist und das Ergebnis somit false
ist, werden die
entsprechenden Maßnahmen ergriffen, je nachdem wie
assert() konfiguriert wurde.
Das Verhalten von assert() wird durch die folgenden
INI-Einstellungen bestimmt:
Konfigurationsoptionen für assert
Name |
Standard |
Beschreibung |
Changelog |
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.active |
true |
Wenn false , prüft assert() die Annahme nicht und
gibt automatisch true zurück.
|
|
assert.callback |
null |
Eine benutzerdefinierte Funktion, die aufgerufen wird, wenn eine
Zusicherung fehlschlägt. Sie sollte die folgende Signatur haben:
assert_callback( string $file , int $line , null $assertion , string $description = ? ): void
|
Vor PHP 8.0.0 musste die Signatur des Callbacks wie folgt lauten:
assert_callback( string $file , int $line , string $assertion , string $description = ? ): void
|
assert.exception |
true |
Wenn true , wird ein AssertionError ausgelöst,
wenn die Erwartung nicht erfüllt wird.
|
|
assert.bail |
false |
Wenn true , wird die Ausführung des PHP-Skripts gestoppt, wenn die
Erwartung nicht erfüllt wird.
|
|
assert.warning |
true |
Wenn true , wird eine E_WARNING ausgegeben, wenn
die Erwartung nicht erfüllt wird. Diese INI-Einstellung hat keine
Auswirkung, wenn
assert.exception aktiviert
ist.
|
|
Die mit
assert.
beginnenden Optionen können über
assert_options() konfiguriert werden. Allerdings wird
dies nicht empfohlen.
Parameter-Liste
-
assertion
-
Dies ist ein beliebiger Ausdruck, der einen Wert zurückgibt, der
ausgeführt wird und dessen Ergebnis verwendet wird, um anzuzeigen, ob
die Zusicherung erfolgreich war oder fehlschlug.
Warnung
Vor PHP 8.0.0 wurde assertion
, wenn es vom Typ
string war, als PHP-Code interpretiert und über
eval() ausgeführt. Diese Zeichenkette wurde dann
als drittes Argument an den Callback übergeben. Dieses Verhalten war
in PHP 7.2.0 MISSBILLIGT, und wurde in PHP 8.0.0
ENTFERNT.
-
description
-
Wenn description
eine Instanz von
Throwable ist, wird sie nur ausgelöst, wenn die
assertion
ausgeführt wird und fehlschlägt.
Hinweis:
Seit PHP 8.0.0 wird dies durchgeführt bevor ein
möglicherweise definierter Zusicherungs-Callback aufgerufen wird.
Hinweis:
Seit PHP 8.0.0 wird das Objekt unabhängig von der Einstellung von
assert.exception
ausgelöst.
Hinweis:
Seit PHP 8.0.0 hat die Einstellung von
assert.bail in diesem Fall
keine Wirkung mehr.
Wenn description
vom Typ String ist, wird
diese Nachricht verwendet, wenn eine Exception oder eine Warnung
ausgegeben wird. Eine optionale Beschreibung, die in die Fehlermeldung
aufgenommen wird, wenn die assertion
fehlschlägt.
description
kann weggelassen werden.
Die Standardbeschreibung entspricht dem Quellcode für den Aufruf von
assert() und wird zur Kompilierzeit erstellt.
Rückgabewerte
false
, wenn assertion
false
ist, anderfalls
true
.
Beispiele
Annahmen
<?php
assert(true == false);
echo 'Hi!';
?>
Ist zend.assertions auf 0
gesetzt, gibt das obige Beispiel folgendes aus:
Ist zend.assertions auf 1
gesetzt und assert.exception
auf 0, gibt das obige Beispiel folgendes aus:
Warning: assert(): assert(true == false) failed in - on line 2
Hi!
Ist zend.assertions auf 1
gesetzt und assert.exception
auf 1, gibt das obige Beispiel folgendes 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 #1 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 folgendes aus:
Ist zend.assertions auf 1
gesetzt und assert.exception
auf 0, gibt das obige Beispiel folgendes 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
gesetzt und assert.exception
auf 1, gibt das obige Beispiel aus:
Fatal error: Uncaught CustomError: True ist nicht false! in -:4
Stack trace:
#0 {main}
thrown in - on line 4
Zusicherungen mit ausgewertetem Code (nur PHP 7)
Bei Zusicherungen mit ausgewertetem Code können
assert()-Callbacks besonders nützlich sein, da der für
die Zusicherung verwendete Code zusammen mit Informationen darüber, wo die
Zusicherung durchgeführt wurde, an den Callback übergeben wird.
Beispiel #2 Handhabung einer fehlgeschlagenen Zusicherung mit benutzerdefiniertem Handler
<?php
// Zusicherungen aktivieren und stummschalten
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 Zusicherung, die fehlschlagen sollte
$array = [];
assert('count($array);');
?>
Das oben gezeigte Beispiel erzeugt mit PHP 7.2 folgende Ausgabe:
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
<hr>Zusicherung fehlgeschlagen:
Datei 'test.php'<br />
Zeile '21'<br />
Code 'count($array);'<br /><hr />
Das oben gezeigte Beispiel erzeugt mit PHP 7.1 folgende Ausgabe:
<hr>Zusicherung fehlgeschlagen:
Datei 'test.php'<br />
Zeile '21'<br />
Code 'count($array);'<br /><hr />
Beispiel #3 Verwendung eines benutzerdefinierten Handlers um eine Beschreibung anzuzeigen
<?php
// Zusicherungen aktivieren und stummschalten
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');
// Zusicherungen, die fehlschlagen sollten
assert('2 < 1');
assert('2 < 1', 'Zwei ist kleiner als Eins');
?>
Das oben gezeigte Beispiel erzeugt mit PHP 7.2 folgende Ausgabe:
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
Assertion failed at test.php:21: 2 < 1
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 22
Assertion failed at test.php:22: 2 < 1: Zwei ist kleiner als Eins
Das oben gezeigte Beispiel erzeugt mit PHP 7.1 folgende Ausgabe:
Zusicherung fehlgeschlagen in test.php:21: 2 < 1
Zusicherung fehlgeschlagen in test.php:22: 2 < 1: Zwei ist kleiner als Eins