PHP Reference ยท Databases (PDO)
PHP PDO error handling
How PDO reports errors in PHP: ERRMODE_EXCEPTION, WARNING and SILENT, the PDOException properties, SQLSTATE codes, errorInfo() and safe messages for users.
When a database call fails, PDO can react in three ways, chosen by the PDO::ATTR_ERRMODE attribute. Since PHP 8.0 the default is exception mode: failures throw a PDOException, which you handle with try/catch like any other error. The other two modes (warning and silent) are mostly of historical interest.
Whatever the mode, an error from the database comes with a standard SQLSTATE code, a driver-specific code and a message. You can read them from the exception or from errorInfo().
$pdo = new PDO($dsn, $user, $pass, [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); PDO::errorCode(): ?string PDO::errorInfo(): array PDOStatement::errorCode(): ?string PDOStatement::errorInfo(): array
| Mode | Behavior |
|---|---|
PDO::ERRMODE_EXCEPTION |
Throws PDOException. The default since PHP 8.0. |
PDO::ERRMODE_WARNING |
Raises an E_WARNING and the call returns false. |
PDO::ERRMODE_SILENT |
Only sets the error code. The call returns false; you must check errorCode()/errorInfo(). |
PDOException properties:
| Property | Meaning |
|---|---|
getMessage() |
A text such as SQLSTATE[23000]: Integrity constraint violation: .... |
getCode() |
The SQLSTATE as a string, for example '23000' (integrity violation), '42S02' (MySQL: table not found), 'HY000' (general error). |
errorInfo |
Array of [SQLSTATE, driver error code, driver message]. |
Errors / Exceptions: the constructor new PDO(...) throws PDOException on connection problems in every error mode.
Usage notes
- Use exception mode and catch
PDOExceptionwhere you can do something useful: retry, show a friendly message or roll back a transaction. getCode()is a string, not an int, so compare with'23000'. Many different failures share one SQLSTATE class; readerrorInfo[1]for the exact driver code, for example MySQL1062for a duplicate key.- Do not show raw messages to visitors. They can reveal table names, SQL fragments and sometimes host names or passwords from the DSN. Log the details and show a generic message.
- Silent and warning modes need checks everywhere (
if ($stmt === false)), which is easy to forget. That is why exception mode is the recommended one. errorInfo()describes only the last operation on that connection or statement.- Missing data is not an error.
fetch()returningfalsemeans "no more rows", not a failure. - Set the mode on the connection (constructor options) so every statement inherits it.
Related
PDO,PDO::prepare(), PDO transactions,try/catch- Lessons: PDO basics, Exceptions