Skip to content
Tutorials Center
My learning

Topics

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().

PHP
$pdo = new PDO($dsn, $user, $pass, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Try it

PHP Catching a PDOException and reading its details

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.

PHP The three error modes

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

PHP
$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 PDOException where 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; read errorInfo[1] for the exact driver code, for example MySQL 1062 for 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() returning false means "no more rows", not a failure.
  • Set the mode on the connection (constructor options) so every statement inherits it.