Documentation

DatabaseException extends LwtException
in package

Exception thrown for database-related errors.

Covers connection failures, query errors, transaction issues, and constraint violations.

Tags
since
3.0.0

Table of Contents

Properties

$context  : array<string, mixed>
Additional context data for logging/debugging.
$httpStatusCode  : int
HTTP status code to return (for web responses).
$query  : string|null
The SQL query that caused the error (if available).
$shouldLog  : bool
Whether this exception should be logged.
$sqlErrorCode  : int|null
The MySQL/MariaDB error code.
$sqlState  : string|null
The SQL state (5-character code).

Methods

__construct()  : mixed
Create a new database exception.
connectionFailed()  : self
Create exception for connection failure.
duplicateEntry()  : self
Create exception for unique constraint violation.
foreignKeyViolation()  : self
Create exception for foreign key constraint violation.
getContext()  : array<string, mixed>
Get the context data for this exception.
getHttpStatusCode()  : int
Get the HTTP status code for this exception.
getQuery()  : string|null
Get the SQL query that caused the error (sanitized for security).
getSqlErrorCode()  : int|null
Get the MySQL/MariaDB error code.
getSqlState()  : string|null
Get the SQL state.
getUserMessage()  : string
Get a user-friendly message for display.
prepareFailed()  : self
Create exception for prepared statement failure.
queryFailed()  : self
Create exception for query execution failure.
recordNotFound()  : self
Create exception for record not found.
setHttpStatusCode()  : self
Set the HTTP status code.
shouldLog()  : bool
Whether this exception should be logged.
toArray()  : array<string, mixed>
Convert exception to array for logging/JSON responses.
transactionFailed()  : self
Create exception for transaction failure.
withContext()  : self
Add context data to the exception.
sanitizeQuery()  : string
Sanitize a query for logging (remove sensitive data).

Properties

$context

Additional context data for logging/debugging.

protected array<string, mixed> $context = []

$httpStatusCode

HTTP status code to return (for web responses).

protected int $httpStatusCode = 500

$query

The SQL query that caused the error (if available).

protected string|null $query = null

$shouldLog

Whether this exception should be logged.

protected bool $shouldLog = true

$sqlErrorCode

The MySQL/MariaDB error code.

protected int|null $sqlErrorCode = null

$sqlState

The SQL state (5-character code).

protected string|null $sqlState = null

Methods

__construct()

Create a new database exception.

public __construct([string $message = '' ][, int $code = 0 ][, Throwable|null $previous = null ][, string|null $query = null ][, int|null $sqlErrorCode = null ][, string|null $sqlState = null ]) : mixed
Parameters
$message : string = ''

The exception message

$code : int = 0

The exception code (default: 0)

$previous : Throwable|null = null

The previous exception for chaining

$query : string|null = null

The SQL query that caused the error

$sqlErrorCode : int|null = null

The MySQL error code

$sqlState : string|null = null

The SQL state

connectionFailed()

Create exception for connection failure.

public static connectionFailed(string $host, string $database, string $error[, Throwable|null $previous = null ]) : self
Parameters
$host : string

Database host

$database : string

Database name

$error : string

Error message from driver

$previous : Throwable|null = null

Previous exception

Return values
self

duplicateEntry()

Create exception for unique constraint violation.

public static duplicateEntry(string $table, string $column, mixed $value[, Throwable|null $previous = null ]) : self
Parameters
$table : string

Table with the constraint

$column : string

Column with duplicate value

$value : mixed

The duplicate value

$previous : Throwable|null = null

Previous exception

Return values
self

foreignKeyViolation()

Create exception for foreign key constraint violation.

public static foreignKeyViolation(string $table, string $constraint, string $error[, Throwable|null $previous = null ]) : self
Parameters
$table : string

Table with the constraint

$constraint : string

Constraint name

$error : string

Error message

$previous : Throwable|null = null

Previous exception

Return values
self

getContext()

Get the context data for this exception.

public getContext() : array<string, mixed>
Return values
array<string, mixed>

getHttpStatusCode()

Get the HTTP status code for this exception.

public getHttpStatusCode() : int
Return values
int

getQuery()

Get the SQL query that caused the error (sanitized for security).

public getQuery() : string|null

Returns a sanitized version with string values masked to prevent information disclosure. For the raw query (logging only), access the protected $query property directly in subclasses.

Return values
string|null —

The sanitized query or null

getSqlErrorCode()

Get the MySQL/MariaDB error code.

public getSqlErrorCode() : int|null
Return values
int|null

getSqlState()

Get the SQL state.

public getSqlState() : string|null
Return values
string|null

getUserMessage()

Get a user-friendly message for display.

public getUserMessage() : string
Return values
string

prepareFailed()

Create exception for prepared statement failure.

public static prepareFailed(string $query, string $error[, Throwable|null $previous = null ]) : self
Parameters
$query : string

The failed query

$error : string

Error message

$previous : Throwable|null = null

Previous exception

Return values
self

queryFailed()

Create exception for query execution failure.

public static queryFailed(string $query, string $error[, int|null $sqlErrorCode = null ][, string|null $sqlState = null ][, Throwable|null $previous = null ]) : self
Parameters
$query : string

The failed query

$error : string

Error message from driver

$sqlErrorCode : int|null = null

MySQL error code

$sqlState : string|null = null

SQL state

$previous : Throwable|null = null

Previous exception

Return values
self

recordNotFound()

Create exception for record not found.

public static recordNotFound(string $table, string $key, int|string $id) : self
Parameters
$table : string

Table name

$key : string

Primary key column

$id : int|string

The ID that was not found

Return values
self

setHttpStatusCode()

Set the HTTP status code.

public setHttpStatusCode(int $code) : self
Parameters
$code : int

HTTP status code

Return values
self

shouldLog()

Whether this exception should be logged.

public shouldLog() : bool
Return values
bool

toArray()

Convert exception to array for logging/JSON responses.

public toArray([bool $includeTrace = false ]) : array<string, mixed>
Parameters
$includeTrace : bool = false

Whether to include stack trace

Return values
array<string, mixed>

transactionFailed()

Create exception for transaction failure.

public static transactionFailed(string $operation, string $error[, Throwable|null $previous = null ]) : self
Parameters
$operation : string

Transaction operation (begin, commit, rollback)

$error : string

Error message

$previous : Throwable|null = null

Previous exception

Return values
self

withContext()

Add context data to the exception.

public withContext(string $key, mixed $value) : self
Parameters
$key : string

Context key

$value : mixed

Context value

Return values
self

sanitizeQuery()

Sanitize a query for logging (remove sensitive data).

private sanitizeQuery(string $query) : string

Truncates very long queries and masks potential passwords.

Parameters
$query : string

The query to sanitize

Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results