DoDomuDojade Documentation

DatabaseService
in package

Read onlyYes
FinalYes

Simplifies interaction with database

Table of Contents

Properties

$logger  : LoggerInterface
$pdo  : PDO

Methods

__construct()  : mixed
beginTransaction()  : bool
Begins a database transaction.
bindParams()  : void
Binds parameters safely to a PDOStatement with validation and logging.
buildSelectQuery()  : array{query: string, params: array}
Builds a simple SELECT query with optional conditions, limit, and offset.
bulkInsert()  : int
Inserts multiple rows in a single query for efficiency.
commit()  : bool
Commits a database transaction.
count()  : int
Counts rows in a table with optional conditions.
delete()  : int
Deletes rows from a table with optional additional WHERE conditions.
executeStatement()  : PDOStatement
Executes given PDO statement.
exists()  : bool
Checks if a row exists.
getAll()  : array<string|int, mixed>
Fetches all rows as an associative array.
getColumn()  : mixed|null
Fetches a single column value from the first row.
getOne()  : array<string|int, mixed>|null
Fetches a single row as an associative array.
getTableColumns()  : array<string|int, mixed>
Gets table column information, adapting to the PDO driver.
insert()  : string|int
Inserts a single row and returns the last insert ID or provided ID.
rollback()  : bool
Rolls back a database transaction.
update()  : int
Updates rows in a table.
validateColumns()  : bool
Validates columns before update/insert.
validateParam()  : array{0: mixed, 1: int}
Validates and normalizes a parameter pair.

Properties

Methods

__construct()

public __construct(PDO $pdo, LoggerInterface $logger) : mixed
Parameters
$pdo : PDO
$logger : LoggerInterface

beginTransaction()

Begins a database transaction.

public beginTransaction() : bool
Return values
bool —

True on success.

bindParams()

Binds parameters safely to a PDOStatement with validation and logging.

public bindParams(PDOStatement $stmt, array<string, mixed> $params) : void

Parameters should be in the format: [':key' => [value, type?]] or [':key' => value] for default string type.

Parameters
$stmt : PDOStatement

The prepared statement.

$params : array<string, mixed>

The parameters to bind.

Tags
throws
Exception

If binding fails.

buildSelectQuery()

Builds a simple SELECT query with optional conditions, limit, and offset.

public buildSelectQuery(string $table[, array<string, mixed> $conditions = [] ][, int|null $limit = null ][, int|null $offset = null ][, string $columns = '*' ][, string|null $orderBy = null ]) : array{query: string, params: array}

This is a lightweight query builder for common SELECT operations. For more complex queries, use raw SQL with executeStatement or getAll.

Parameters
$table : string

The table name.

$conditions : array<string, mixed> = []

WHERE conditions (optional).

$limit : int|null = null

LIMIT clause (optional).

$offset : int|null = null

OFFSET clause (optional).

$columns : string = '*'

Columns to select (default '*').

$orderBy : string|null = null

ORDER BY clause (optional, e.g., 'id DESC').

Return values
array{query: string, params: array} —

The query and params.

bulkInsert()

Inserts multiple rows in a single query for efficiency.

public bulkInsert(string $table, array<string|int, array<string, mixed>> $rows[, bool $validate = true ]) : int

All rows must have the same columns. Validation checks the first row's columns. Data format: [['column' => value, ...], ...] or with types as [value, type].

Parameters
$table : string

The table name.

$rows : array<string|int, array<string, mixed>>

The rows to insert.

$validate : bool = true

Whether to validate columns (default true).

Tags
throws
RuntimeException|Exception|InvalidArgumentException

On failure or mismatched columns.

Return values
int —

The number of inserted rows.

commit()

Commits a database transaction.

public commit() : bool
Return values
bool —

True on success.

count()

Counts rows in a table with optional conditions.

public count(string $table[, array<string, mixed> $conditions = [] ]) : int
Parameters
$table : string

The table name.

$conditions : array<string, mixed> = []

The WHERE conditions (optional).

Tags
throws
RuntimeException|Exception

On failure.

Return values
int —

The count.

delete()

Deletes rows from a table with optional additional WHERE conditions.

public delete(string $table[, array<string, mixed> $conditions = [] ][, string|null $additionalWhere = null ][, array<string, mixed> $additionalParams = [] ]) : int

Conditions are required to prevent accidental full-table deletion.

Parameters
$table : string

The table name.

$conditions : array<string, mixed> = []

The WHERE conditions (key = value pairs).

$additionalWhere : string|null = null

Additional WHERE clause (e.g., "decided_at < :date").

$additionalParams : array<string, mixed> = []

Additional parameters for the additional WHERE clause.

Tags
throws
RuntimeException|Exception|InvalidArgumentException

On failure or empty conditions.

Return values
int —

The number of affected rows.

executeStatement()

Executes given PDO statement.

public executeStatement(string $query[, array<string, mixed> $params = [] ]) : PDOStatement
Parameters
$query : string

The SQL query to prepare and execute.

$params : array<string, mixed> = []

Parameters to bind (optional).

Tags
throws
RuntimeException|Exception

On preparation or execution failure.

Return values
PDOStatement —

The executed statement.

exists()

Checks if a row exists.

public exists(string $table[, array<string, mixed> $conditions = [] ]) : bool
Parameters
$table : string

The table name.

$conditions : array<string, mixed> = []

The WHERE conditions (optional).

Tags
throws
RuntimeException|Exception

On failure.

Return values
bool —

True if exists.

getAll()

Fetches all rows as an associative array.

public getAll(string $query[, array<string, mixed> $params = [] ]) : array<string|int, mixed>

This method supports raw queries. For more structured queries, use buildSelectQuery() to generate the query string.

Parameters
$query : string

The SQL query.

$params : array<string, mixed> = []

Parameters to bind (optional).

Tags
throws
RuntimeException|Exception

On execution failure.

Return values
array<string|int, mixed> —

The rows.

getColumn()

Fetches a single column value from the first row.

public getColumn(string $query[, array<string, mixed> $params = [] ][, int $columnIndex = 0 ]) : mixed|null
Parameters
$query : string

The SQL query.

$params : array<string, mixed> = []

Parameters to bind (optional).

$columnIndex : int = 0

The column index (default 0).

Tags
throws
RuntimeException|Exception

On execution failure.

Return values
mixed|null —

The value or null if not found.

getOne()

Fetches a single row as an associative array.

public getOne(string $query[, array<string, mixed> $params = [] ]) : array<string|int, mixed>|null
Parameters
$query : string

The SQL query.

$params : array<string, mixed> = []

Parameters to bind (optional).

Tags
throws
RuntimeException|Exception

On execution failure.

Return values
array<string|int, mixed>|null —

The row or null if not found.

getTableColumns()

Gets table column information, adapting to the PDO driver.

public getTableColumns(string $table) : array<string|int, mixed>

Supports SQLite, MySQL/MariaDB, and PostgreSQL. Throws exception for unsupported drivers.

Parameters
$table : string

The table name.

Tags
throws
RuntimeException

On failure or unsupported driver.

Return values
array<string|int, mixed> —

The column names.

insert()

Inserts a single row and returns the last insert ID or provided ID.

public insert(string $table, array<string, mixed> $data[, bool $validate = true ]) : string|int

Validation is enabled by default to check columns against the table schema. Disable only for trusted, pre-validated data to improve performance.

Data format: ['column' => value] or ['column' => [value, type]].

Parameters
$table : string

The table name.

$data : array<string, mixed>

The data to insert.

$validate : bool = true

Whether to validate columns (default true).

Tags
throws
RuntimeException|Exception|InvalidArgumentException

On failure.

Return values
string|int —

The last insert ID or the provided ID value.

rollback()

Rolls back a database transaction.

public rollback() : bool
Return values
bool —

True on success.

update()

Updates rows in a table.

public update(string $table, array<string, mixed> $data[, array<string, mixed> $conditions = [] ][, bool $validate = true ]) : int

Validation is enabled by default. Disable only for trusted data. If conditions are empty, all rows will be updated—use with caution.

Data/conditions format: ['column' => value] or ['column' => [value, type]].

Parameters
$table : string

The table name.

$data : array<string, mixed>

The data to update.

$conditions : array<string, mixed> = []

The WHERE conditions (optional).

$validate : bool = true

Whether to validate columns (default true).

Tags
throws
RuntimeException|Exception|InvalidArgumentException

On failure.

Return values
int —

The number of affected rows.

validateColumns()

Validates columns before update/insert.

public validateColumns(string $table, array<string, mixed> $data) : bool
Parameters
$table : string

The table name.

$data : array<string, mixed>

The data keys to validate.

Tags
throws
InvalidArgumentException

If invalid columns are found.

throws
RuntimeException

On failure to fetch columns.

Return values
bool —

True if valid.

validateParam()

Validates and normalizes a parameter pair.

private validateParam(mixed $param, string|int $key) : array{0: mixed, 1: int}

Expects the parameter to be either a scalar value (which will be treated as [value, PDO::PARAM_STR]) or an array [value, type] where type is a PDO::PARAM_* constant.

Parameters
$param : mixed

The parameter value or [value, type] array.

$key : string|int

The parameter key for logging.

Tags
throws
InvalidArgumentException

If the format is invalid.

Return values
array{0: mixed, 1: int} —

Normalized [value, type].


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results