Signatur
Beschreibung
assert() dient zur Überprüfung von Annahmen, die zur Laufzeit gelten müssen – typischerweise in der Entwicklungsphase. Ist die übergebene Behauptung false oder wird sie zu false ausgewertet, reagiert PHP je nach Konfiguration mit einer Warnung, einem Fehler oder dem Werfen einer AssertionError-Ausnahme.
Ab PHP 7 wird empfohlen, stets einen booleschen Ausdruck als erstes Argument zu übergeben. Das frühere Verhalten, einen String als Code zu übergeben (eval()-basiert), ist seit PHP 7.2 als veraltet markiert und wurde in PHP 8.0 entfernt. Mit PHP 8 wird assert() grundlegend immer als normaler Funktionsaufruf behandelt, der Ausdruck wird immer ausgewertet.
Das Verhalten von assert() kann über die INI-Direktiven assert.active, assert.exception und assert.warning sowie über assert_options() gesteuert werden. Mit assert.exception=1 (Standard ab PHP 8) wird bei einem Fehlschlag ein AssertionError geworfen statt nur eine Warnung auszugeben.
Hinweis: assert() ist für Entwicklungs- und Debugging-Zwecke gedacht. In Produktionsumgebungen sollte man Assertions entweder deaktivieren (assert.active=0) oder durch reguläre Exceptions ersetzen, um keine versteckten Fehler zu produzieren.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $assertion Pflicht | mixed | Der zu prüfende Ausdruck oder Wert. Ab PHP 7 sollte dies ein boolescher Ausdruck sein. Ergibt er false, schlägt die Assertion fehl. Seit PHP 8.0 ist die Übergabe eines Strings (zur Auswertung via eval()) nicht mehr möglich. |
|
| $description | Throwable|string|null | null | Optionale Beschreibung des Fehlerfalles. Wird ein Throwable-Objekt übergeben, wird dieses bei einem Fehlschlag (mit assert.exception=1) geworfen. Wird ein String übergeben, wird er als Fehlermeldung verwendet und, sofern assert.exception=1 aktiv ist, als Nachricht eines AssertionError genutzt. |
Rückgabewert
true zurück, wenn die Assertion erfolgreich ist (der Ausdruck ist true), andernfalls false. Wenn assert.exception=1 gesetzt ist und die Assertion fehlschlägt, wird stattdessen eine Ausnahme geworfen und der Rückgabewert spielt keine Rolle mehr.Beispiele
Einfache Assertion mit booleschen Ausdruck
<?php
// INI: assert.exception = 1 (Standard in PHP 8)
$wert = 42;
// Diese Assertion ist erfüllt – kein Fehler
assert($wert > 0, 'Wert muss positiv sein');
// Diese Assertion schlägt fehl – AssertionError wird geworfen
try {
assert($wert < 0, 'Wert muss negativ sein');
} catch (AssertionError $e) {
echo 'Assertion fehlgeschlagen: ' . $e->getMessage();
}Assertion mit eigenem Throwable-Objekt
<?php
function teilePositiv(int $a, int $b): float {
assert($b !== 0, new InvalidArgumentException('Divisor darf nicht null sein'));
return $a / $b;
}
try {
echo teilePositiv(10, 2) . PHP_EOL; // 5
echo teilePositiv(10, 0); // wirft Exception
} catch (InvalidArgumentException $e) {
echo 'Fehler: ' . $e->getMessage();
}Assertions in Unit-Tests-ähnlichem Kontext
<?php
// Einfacher Selbsttest einer Hilfsfunktion
function addiere(int $a, int $b): int {
return $a + $b;
}
assert(addiere(2, 3) === 5, 'addiere(2,3) muss 5 ergeben');
assert(addiere(0, 0) === 0, 'addiere(0,0) muss 0 ergeben');
assert(addiere(-1, 1) === 0, 'addiere(-1,1) muss 0 ergeben');
echo 'Alle Assertions erfüllt.';
// Wichtig · Fallstricke
Sicherheit und Produktivbetrieb: In Produktionsumgebungen sollte assert.active=0 in der php.ini gesetzt werden, um unnötige Laufzeitauswertungen zu vermeiden. Alternativ sollten kritische Prüfungen als reguläre if-Bedingungen mit Exceptions implementiert werden.
Deprecation-Hinweis: Die Übergabe eines Strings als $assertion (z. B. assert('$a > 0')) war seit PHP 7.2 als veraltet markiert und wurde in PHP 8.0 entfernt. Solcher Code führt in PHP 8+ zu einem ParseError.
PHP 8 Änderungen: Ab PHP 8.0 wird der übergebene Ausdruck immer ausgewertet, auch wenn assert.active=0 ist. Es gibt keine Möglichkeit mehr, Assertions zur Compile-Zeit vollständig zu eliminieren. Wer vollständig abschaltbare Assertions benötigt, sollte eigene Wrapper-Mechanismen oder dedizierte Test-Frameworks nutzen.
INI-Direktiven: assert.active (Standard: 1) – Assertions einschalten; assert.exception (Standard: 1 ab PHP 8) – Wirft AssertionError statt Warnung; assert.warning (Standard: 1) – Gibt eine Warnung aus, wenn keine Exception geworfen wird.