Documentation

AdapterInterface
in

Table of Contents

Constants

ERROR_DDL_MESSAGE  : mixed = 'DDL statements are not allowed in transactions'
Error message for DDL query in transactions
ERROR_TRANSACTION_NOT_COMMITTED  : mixed = 'Some transactions have not been committed or r...
FK_ACTION_CASCADE  : mixed = 'CASCADE'
FK_ACTION_NO_ACTION  : mixed = 'NO ACTION'
FK_ACTION_RESTRICT  : mixed = 'RESTRICT'
FK_ACTION_SET_DEFAULT  : mixed = 'SET DEFAULT'
FK_ACTION_SET_NULL  : mixed = 'SET NULL'
INDEX_TYPE_FULLTEXT  : mixed = 'fulltext'
INDEX_TYPE_INDEX  : mixed = 'index'
INDEX_TYPE_PRIMARY  : mixed = 'primary'
INDEX_TYPE_UNIQUE  : mixed = 'unique'
INSERT_IGNORE  : mixed = 2
INSERT_ON_DUPLICATE  : mixed = 1
INTERVAL_DAY  : mixed = 'DAYS'
INTERVAL_HOUR  : mixed = 'HOURS'
INTERVAL_MINUTE  : mixed = 'MINUTES'
INTERVAL_MONTH  : mixed = 'MONTHS'
INTERVAL_SECOND  : mixed = 'SECOND'
INTERVAL_YEAR  : mixed = 'YEARS'
ISO_DATE_FORMAT  : mixed = 'yyyy-MM-dd'
ISO_DATETIME_FORMAT  : mixed = 'yyyy-MM-dd HH-mm-ss'

Methods

addColumn()  : self
Adds new column to the table.
addForeignKey()  : self
Add new Foreign Key to table If Foreign Key with same name is exist - it will be deleted
addIndex()  : StatementInterface
Add new index to table name
allowDdlCache()  : self
Allow DDL caching
beginTransaction()  : self
Begin new DB transaction for connection
changeColumn()  : self
Change the column name and definition
changeTableAutoIncrement()  : StatementInterface
Change table auto increment value
closeConnection()  : void
Release the connection to the database server, reconnecting on next use.
commit()  : self
Commit DB transaction
createTable()  : StatementInterface
Create table from DDL object
createTableByDdl()  : Table
Create \Maho\Db\Ddl\Table object by data from describe table
createTableFromSelect()  : void
Create new table from provided select statement
createTemporaryTable()  : StatementInterface
Create temporary table from DDL object
decodeVarbinary()  : mixed
Converts fetched blob into raw binary PHP data.
delete()  : int
Deletes table rows based on a WHERE clause.
deleteFromSelect()  : string
Get delete from select object query
describeTable()  : array<string|int, mixed>
Returns the column descriptions for a table.
disableTableKeys()  : self
Stop updating indexes
disallowDdlCache()  : self
Disallow DDL caching
dropColumn()  : bool
Drop the column from table
dropForeignKey()  : self
Drop the Foreign Key from table
dropIndex()  : bool|StatementInterface
Drop the index from table
dropTable()  : bool
Drop table from database
dropTemporaryTable()  : bool
Drop temporary table from database
dropTrigger()  : self
Drop trigger
enableTableKeys()  : self
Re-create missing indexes
endSetup()  : self
Run additional environment after setup
fetchAll()  : array<string|int, mixed>
Fetches all SQL result rows as a sequential array.
fetchAssoc()  : array<string|int, mixed>
Fetches all SQL result rows as an associative array.
fetchCol()  : array<string|int, mixed>
Fetches the first column of all SQL result rows as an array.
fetchOne()  : mixed
Fetches the first column of the first row of the SQL result.
fetchPairs()  : array<string|int, mixed>
Fetches all SQL result rows as an array of key-value pairs.
fetchRow()  : array<string|int, mixed>|false
Fetches the first row of the SQL result.
formatDate()  : Expr
Format Date to internal database date format
forUpdate()  : string
Render SQL FOR UPDATE clause
fromUnixtime()  : Expr
Convert unix time to date format
getCaseSql()  : Expr
Generate fragment of SQL, that check value against multiple condition cases and return different result depends on them
getCastToTextSql()  : Expr
Generate fragment of SQL to cast a value to text/varchar for comparison.
getCheckSql()  : Expr
Generate fragment of SQL, that check condition and return true or false value
getConcatSql()  : Expr
Generate fragment of SQL, that combine together (concatenate) the results from data array All arguments in data must be quoted
getConfig()  : array<string|int, mixed>
Returns the configuration variables in this adapter.
getConnection()  : Connection
Get the underlying Doctrine DBAL Connection
getDateAddSql()  : Expr
Add time values (intervals) to a date value
getDateDiffSql()  : Expr
Get difference between two dates in days
getDateExtractSql()  : Expr
Extract part of a date
getDateFormatSql()  : Expr
Format date as specified
getDatePartSql()  : Expr
Extract the date part of a date or datetime expression
getDateSubSql()  : Expr
Subtract time values (intervals) to a date value
getDateTimeAddSql()  : Expr
Add time values (intervals) to a date and time value, and keep the time
getDaysUntilAnniversarySql()  : Expr
Get SQL expression for days until next annual occurrence of a date
getFindInSetExpr()  : Expr
Get SQL expression for FIND_IN_SET functionality
getForeignKeyName()  : string
Retrieve valid foreign key name Check foreign key name length and allowed symbols
getForeignKeys()  : array<string|int, mixed>
Retrieve the foreign keys descriptions for a table.
getGreatestSql()  : Expr
Generate fragment of SQL, that compare with two or more arguments, and returns the largest (maximum-valued) argument All arguments in data must be quoted
getGroupConcatExpr()  : Expr
Get SQL expression for concatenating grouped values
getIfNullSql()  : Expr
Returns valid IFNULL expression
getIndexList()  : array<string|int, mixed>
Returns the table index information
getIndexName()  : string
Retrieve valid index name Check index name length and allowed symbols
getJsonContainsExpr()  : Expr
Check if a JSON column contains a specific JSON value
getJsonExtractExpr()  : Expr
Extract a scalar value from a JSON column at a given path
getJsonSearchExpr()  : Expr
Search for a string value within a JSON column
getLeastSql()  : Expr
Generate fragment of SQL, that compare with two or more arguments, and returns the smallest (minimum-valued) argument All arguments in data must be quoted
getLengthSql()  : Expr
Generate fragment of SQL that returns length of character string The string argument must be quoted
getLock()  : bool
Acquire a named lock
getPrimaryKeyName()  : string
Try to find installed primary key name, if not - format new one.
getRoundSql()  : Expr
Generate fragment of SQL for rounding a numeric value to specified precision.
getStandardDeviationSql()  : Expr
Prepare standard deviation sql function
getSubstringSql()  : Expr
Prepare substring sql function
getTableName()  : string
Retrieve valid table name Check table name length and allowed symbols
getTablesChecksum()  : array<string|int, mixed>
Return array of table(s) checksum as table name - checksum pairs
getTimestampDiffExpr()  : Expr
Get SQL expression for timestamp difference in seconds
getTransactionLevel()  : int
Get adapter transaction level state. Return 0 if all transactions are complete
getUnixTimestamp()  : Expr
Convert date format to unix time
getUnixTimestampExpr()  : Expr
Generate a database-agnostic Unix timestamp expression
insert()  : int
Inserts a table row with specified data.
insertArray()  : int
Insert array to table based on columns definition
insertForce()  : int
Inserts a table row with specified data Special for Zero values to identity column
insertFromSelect()  : string
Get insert from Select object query
insertIgnore()  : int
Inserts a table row with specified data.
insertMultiple()  : int
Inserts a table multiply rows with specified data.
insertOnDuplicate()  : int
Inserts a table row with specified data.
isLocked()  : bool
Check if a named lock is currently held
isTableExists()  : bool
Checks if table exists
lastInsertId()  : string|int
Retrieve last inserted ID
listTables()  : array<string|int, string>
Retrieve the list of all tables in the database
loadDdlCache()  : string|array<string|int, mixed>|int|false
Load DDL data from cache Return false if cache does not exists
modifyColumn()  : self
Modify the column definition
modifyColumnByDdl()  : self
Modify the column definition by data from describe table
modifyTables()  : self
Modify table columns, foreign keys, comments and engine
multiQuery()  : array<string|int, mixed>
Executes a SQL statement(s)
newTable()  : Table
Retrieve DDL object for new table
orderRand()  : self
Adds order by random to select object Possible using integer field for optimization
prepareColumnValue()  : mixed
Prepare value for save in column Return converted to column data type value
prepareSqlCondition()  : string
Build SQL statement for condition
query()  : StatementInterface
Prepares and executes an SQL statement with bound data.
quote()  : string
Safely quotes a value for an SQL statement.
quoteColumnAs()  : string
Quote a column identifier and alias.
quoteIdentifier()  : string
Quotes an identifier.
quoteInto()  : string
Quotes a value and places into a piece of text at a placeholder.
quoteTableAs()  : string
Quote a table identifier and alias.
releaseLock()  : bool
Release a named lock
renameTable()  : bool
Rename table
renameTablesBatch()  : bool
Rename several tables
resetDdlCache()  : self
Reset cached DDL data from cache if table name is null - reset all cached DDL data
rollBack()  : self
Roll-back DB transaction
saveDdlCache()  : self
Save DDL data into cache
select()  : Select
Creates and returns a new \Maho\Db\Select object for this adapter.
selectsByRange()  : array<string|int, mixed>
Get insert queries in array for insert by range with step parameter
setCacheAdapter()  : self
showTableStatus()  : array<string|int, mixed>|false
Returns short table status array
startSetup()  : self
Run additional environment before setup
supportStraightJoin()  : bool
Check if the database support STRAIGHT JOIN
tableColumnExists()  : bool
Check is table column exists
truncateTable()  : self
Truncate a table
update()  : int
Updates table rows with specified data based on a WHERE clause.
updateFromSelect()  : string
Get update table query using select object for join and update

Constants

ERROR_DDL_MESSAGE

Error message for DDL query in transactions

public mixed ERROR_DDL_MESSAGE = 'DDL statements are not allowed in transactions'

ERROR_TRANSACTION_NOT_COMMITTED

public mixed ERROR_TRANSACTION_NOT_COMMITTED = 'Some transactions have not been committed or rolled back'

FK_ACTION_SET_DEFAULT

public mixed FK_ACTION_SET_DEFAULT = 'SET DEFAULT'

ISO_DATETIME_FORMAT

public mixed ISO_DATETIME_FORMAT = 'yyyy-MM-dd HH-mm-ss'

Methods

addColumn()

Adds new column to the table.

public addColumn(string $tableName, string $columnName, array<string|int, mixed>|string $definition[, string|null $schemaName = null ]) : self

Generally $defintion must be array with column data to keep this call cross-DB compatible. Using string as $definition is allowed only for concrete DB adapter.

Parameters
$tableName : string
$columnName : string
$definition : array<string|int, mixed>|string
$schemaName : string|null = null
Return values
self

addForeignKey()

Add new Foreign Key to table If Foreign Key with same name is exist - it will be deleted

public addForeignKey(string $fkName, string $tableName, string $columnName, string $refTableName, string $refColumnName[, string $onDelete = self::FK_ACTION_CASCADE ][, string $onUpdate = self::FK_ACTION_CASCADE ][, bool $purge = false ][, string|null $schemaName = null ][, string|null $refSchemaName = null ]) : self
Parameters
$fkName : string
$tableName : string
$columnName : string
$refTableName : string
$refColumnName : string
$onDelete : string = self::FK_ACTION_CASCADE
$onUpdate : string = self::FK_ACTION_CASCADE
$purge : bool = false
$schemaName : string|null = null
$refSchemaName : string|null = null
Return values
self

addIndex()

Add new index to table name

public addIndex(string $tableName, string $indexName, string|array<string|int, mixed> $fields[, string $indexType = self::INDEX_TYPE_INDEX ][, string|null $schemaName = null ]) : StatementInterface
Parameters
$tableName : string
$indexName : string
$fields : string|array<string|int, mixed>

the table column name or array of ones

$indexType : string = self::INDEX_TYPE_INDEX
$schemaName : string|null = null
Return values
StatementInterface

allowDdlCache()

Allow DDL caching

public allowDdlCache() : self
Return values
self

beginTransaction()

Begin new DB transaction for connection

public beginTransaction() : self
Return values
self

changeColumn()

Change the column name and definition

public changeColumn(string $tableName, string $oldColumnName, string $newColumnName, array<string|int, mixed>|string $definition[, bool $flushData = false ][, string|null $schemaName = null ]) : self

For change definition of column - use modifyColumn

Parameters
$tableName : string
$oldColumnName : string
$newColumnName : string
$definition : array<string|int, mixed>|string
$flushData : bool = false
$schemaName : string|null = null
Return values
self

changeTableAutoIncrement()

Change table auto increment value

public changeTableAutoIncrement(string $tableName, int $increment[, string|null $schemaName = null ]) : StatementInterface
Parameters
$tableName : string
$increment : int
$schemaName : string|null = null
Return values
StatementInterface

closeConnection()

Release the connection to the database server, reconnecting on next use.

public closeConnection() : void

An adapter whose driver has no connection worth releasing may keep it.

commit()

Commit DB transaction

public commit() : self
Return values
self

createTableByDdl()

Create \Maho\Db\Ddl\Table object by data from describe table

public createTableByDdl(string $tableName, string $newTableName) : Table
Parameters
$tableName : string
$newTableName : string
Return values
Table

createTableFromSelect()

Create new table from provided select statement

public createTableFromSelect(string $tableName, Select $select[, bool $temporary = false ]) : void
Parameters
$tableName : string
$select : Select
$temporary : bool = false

decodeVarbinary()

Converts fetched blob into raw binary PHP data.

public decodeVarbinary(mixed $value) : mixed

Some DB drivers return blobs as hex-coded strings, so we need to process them.

Parameters
$value : mixed

delete()

Deletes table rows based on a WHERE clause.

public delete(string|array<string|int, mixed>|Select $table[, string|array<string|int, mixed> $where = '' ]) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to update.

$where : string|array<string|int, mixed> = ''

DELETE WHERE clause(s).

Return values
int —

The number of affected rows.

deleteFromSelect()

Get delete from select object query

public deleteFromSelect(Select $select, string $table) : string
Parameters
$select : Select
$table : string

the table name or alias used in select

Return values
string

describeTable()

Returns the column descriptions for a table.

public describeTable(string $tableName[, string|null $schemaName = null ]) : array<string|int, mixed>

The return value is an associative array keyed by the column name, as returned by the RDBMS.

The value of each array element is an associative array with the following keys:

SCHEMA_NAME => string; name of database or schema TABLE_NAME => string; COLUMN_NAME => string; column name COLUMN_POSITION => number; ordinal position of column in table DATA_TYPE => string; SQL datatype name of column DEFAULT => string; default expression of column, null if none NULLABLE => boolean; true if column can have nulls LENGTH => number; length of CHAR/VARCHAR SCALE => number; scale of NUMERIC/DECIMAL PRECISION => number; precision of NUMERIC/DECIMAL UNSIGNED => boolean; unsigned property of an integer type PRIMARY => boolean; true if column is part of the primary key PRIMARY_POSITION => integer; position of column in primary key IDENTITY => integer; true if column is auto-generated with unique values

Parameters
$tableName : string
$schemaName : string|null = null
Return values
array<string|int, mixed>

disableTableKeys()

Stop updating indexes

public disableTableKeys(string $tableName[, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$schemaName : string|null = null
Return values
self

disallowDdlCache()

Disallow DDL caching

public disallowDdlCache() : self
Return values
self

dropColumn()

Drop the column from table

public dropColumn(string $tableName, string $columnName[, string|null $schemaName = null ]) : bool
Parameters
$tableName : string
$columnName : string
$schemaName : string|null = null
Return values
bool

dropForeignKey()

Drop the Foreign Key from table

public dropForeignKey(string $tableName, string $fkName[, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$fkName : string
$schemaName : string|null = null
Return values
self

dropIndex()

Drop the index from table

public dropIndex(string $tableName, string $keyName[, string|null $schemaName = null ]) : bool|StatementInterface
Parameters
$tableName : string
$keyName : string
$schemaName : string|null = null
Return values
bool|StatementInterface

dropTable()

Drop table from database

public dropTable(string $tableName[, string|null $schemaName = null ]) : bool
Parameters
$tableName : string
$schemaName : string|null = null
Return values
bool

dropTemporaryTable()

Drop temporary table from database

public dropTemporaryTable(string $tableName[, string|null $schemaName = null ]) : bool
Parameters
$tableName : string
$schemaName : string|null = null
Return values
bool

dropTrigger()

Drop trigger

public dropTrigger(string $triggerName) : self
Parameters
$triggerName : string
Return values
self

enableTableKeys()

Re-create missing indexes

public enableTableKeys(string $tableName[, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$schemaName : string|null = null
Return values
self

endSetup()

Run additional environment after setup

public endSetup() : self
Return values
self

fetchAll()

Fetches all SQL result rows as a sequential array.

public fetchAll(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ][, int|null $fetchMode = null ]) : array<string|int, mixed>

Uses the current fetchMode for the adapter.

Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

$fetchMode : int|null = null

Override current fetch mode.

Return values
array<string|int, mixed>

fetchAssoc()

Fetches all SQL result rows as an associative array.

public fetchAssoc(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ]) : array<string|int, mixed>

The first column is the key, the entire row array is the value. You should construct the query to be sure that the first column contains unique values, or else rows with duplicate values in the first column will overwrite previous data.

Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

Return values
array<string|int, mixed>

fetchCol()

Fetches the first column of all SQL result rows as an array.

public fetchCol(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ]) : array<string|int, mixed>

The first column in each row is used as the array key.

Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

Return values
array<string|int, mixed>

fetchOne()

Fetches the first column of the first row of the SQL result.

public fetchOne(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ]) : mixed
Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

fetchPairs()

Fetches all SQL result rows as an array of key-value pairs.

public fetchPairs(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ]) : array<string|int, mixed>

The first column is the key, the second column is the value.

Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

Return values
array<string|int, mixed>

fetchRow()

Fetches the first row of the SQL result.

public fetchRow(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ][, int|null $fetchMode = null ]) : array<string|int, mixed>|false

Uses the current fetchMode for the adapter.

Parameters
$sql : string|Select

An SQL SELECT statement.

$bind : array<string|int, mixed>|int|string|float = []

Data to bind into SELECT placeholders.

$fetchMode : int|null = null

Override current fetch mode.

Return values
array<string|int, mixed>|false

formatDate()

Format Date to internal database date format

public formatDate(int|string|DateTime $date[, bool $withTime = true ]) : Expr
Parameters
$date : int|string|DateTime
$withTime : bool = true
Return values
Expr

forUpdate()

Render SQL FOR UPDATE clause

public forUpdate(string $sql) : string
Parameters
$sql : string
Return values
string

getCaseSql()

Generate fragment of SQL, that check value against multiple condition cases and return different result depends on them

public getCaseSql(string $valueName, array<string|int, mixed> $casesResults[, string|null $defaultValue = null ]) : Expr
Parameters
$valueName : string
$casesResults : array<string|int, mixed>

Cases and results

$defaultValue : string|null = null

value to use if value doesn't confirm to any cases

Return values
Expr

getCastToTextSql()

Generate fragment of SQL to cast a value to text/varchar for comparison.

public getCastToTextSql(string $expression) : Expr

This is useful for comparing integer columns with varchar columns.

Parameters
$expression : string
Return values
Expr

getCheckSql()

Generate fragment of SQL, that check condition and return true or false value

public getCheckSql(string $condition, string|Expr $true, string|Expr $false) : Expr
Parameters
$condition : string
$true : string|Expr

true value

$false : string|Expr

false value

Return values
Expr

getConcatSql()

Generate fragment of SQL, that combine together (concatenate) the results from data array All arguments in data must be quoted

public getConcatSql(array<string|int, mixed> $data[, string|null $separator = null ]) : Expr
Parameters
$data : array<string|int, mixed>
$separator : string|null = null

concatenate with separator

Return values
Expr

getConfig()

Returns the configuration variables in this adapter.

public getConfig() : array<string|int, mixed>
Return values
array<string|int, mixed>

getConnection()

Get the underlying Doctrine DBAL Connection

public getConnection() : Connection
Return values
Connection

getDateAddSql()

Add time values (intervals) to a date value

public getDateAddSql(Expr|string $date, int|string $interval, string $unit) : Expr
Parameters
$date : Expr|string

quoted field name or SQL statement

$interval : int|string
$unit : string
Tags
see
INTERVAL_

constants for $unit

Return values
Expr

getDateDiffSql()

Get difference between two dates in days

public getDateDiffSql(Expr|string $date1, Expr|string $date2) : Expr
Parameters
$date1 : Expr|string

First date (quoted field name or SQL statement)

$date2 : Expr|string

Second date (quoted field name or SQL statement)

Return values
Expr —

SQL expression that returns (date1 - date2) in days

getDateExtractSql()

Extract part of a date

public getDateExtractSql(Expr|string $date, string $unit) : Expr
Parameters
$date : Expr|string

quoted field name or SQL statement

$unit : string
Tags
see
INTERVAL_

constants for $unit

Return values
Expr

getDateFormatSql()

Format date as specified

public getDateFormatSql(Expr|string $date, string $format) : Expr

Supported format Specifier

%H Hour (00..23) %i Minutes, numeric (00..59) %s Seconds (00..59) %d Day of the month, numeric (00..31) %m Month, numeric (00..12) %Y Year, numeric, four digits

Parameters
$date : Expr|string

quoted field name or SQL statement

$format : string
Return values
Expr

getDatePartSql()

Extract the date part of a date or datetime expression

public getDatePartSql(Expr|string $date) : Expr
Parameters
$date : Expr|string

quoted field name or SQL statement

Return values
Expr

getDateSubSql()

Subtract time values (intervals) to a date value

public getDateSubSql(Expr|string $date, int|string $interval, string $unit) : Expr
Parameters
$date : Expr|string

quoted field name or SQL statement

$interval : int|string
$unit : string
Tags
see
INTERVAL_

constants for $unit

Return values
Expr

getDateTimeAddSql()

Add time values (intervals) to a date and time value, and keep the time

public getDateTimeAddSql(Expr|string $date, int|string $interval, string $unit) : Expr

getDateAddSql() gives a date on SQLite and PostgreSQL, so an hourly report cannot use it.

Parameters
$date : Expr|string

quoted field name or SQL statement

$interval : int|string
$unit : string
Tags
see
INTERVAL_

constants for $unit

Return values
Expr

getDaysUntilAnniversarySql()

Get SQL expression for days until next annual occurrence of a date

public getDaysUntilAnniversarySql(Expr|string $dateField, string $referenceDate) : Expr

This calculates the number of days from a reference date until the next occurrence of an anniversary (e.g., birthday). Handles:

  • Dates where the year is in the future (returns days to that date in current year)
  • Dates where the anniversary has passed this year (returns days to next year)
  • Leap year birthdays (Feb 29) in non-leap years (uses Feb 28)
Parameters
$dateField : Expr|string

The date field containing the anniversary (e.g., birth date)

$referenceDate : string

The reference date in 'Y-m-d' or 'Y-m-d H:i:s' format (usually today)

Return values
Expr —

SQL expression that returns days until next anniversary

getFindInSetExpr()

Get SQL expression for FIND_IN_SET functionality

public getFindInSetExpr(string $needle, string $haystack) : Expr

Returns a SQL expression that checks if a value exists in a comma-separated list. This is database-agnostic and handles the syntax differences between MySQL (FIND_IN_SET) and PostgreSQL (ANY with string_to_array).

Parameters
$needle : string

The value to search for (can be a ? placeholder)

$haystack : string

The column containing comma-separated values

Return values
Expr

getForeignKeyName()

Retrieve valid foreign key name Check foreign key name length and allowed symbols

public getForeignKeyName(string $priTableName, string $priColumnName, string $refTableName, string $refColumnName) : string
Parameters
$priTableName : string
$priColumnName : string
$refTableName : string
$refColumnName : string
Return values
string

getForeignKeys()

Retrieve the foreign keys descriptions for a table.

public getForeignKeys(string $tableName[, string|null $schemaName = null ]) : array<string|int, mixed>

The return value is an associative array keyed by the UPPERCASE foreign key, as returned by the RDBMS.

The value of each array element is an associative array with the following keys:

FK_NAME => string; original foreign key name SCHEMA_NAME => string; name of database or schema TABLE_NAME => string; COLUMN_NAME => string; column name REF_SCHEMA_NAME => string; name of reference database or schema REF_TABLE_NAME => string; reference table name REF_COLUMN_NAME => string; reference column name ON_DELETE => string; action type on delete row ON_UPDATE => string; action type on update row

Parameters
$tableName : string
$schemaName : string|null = null
Return values
array<string|int, mixed>

getGreatestSql()

Generate fragment of SQL, that compare with two or more arguments, and returns the largest (maximum-valued) argument All arguments in data must be quoted

public getGreatestSql(array<string|int, mixed> $data) : Expr
Parameters
$data : array<string|int, mixed>
Return values
Expr

getGroupConcatExpr()

Get SQL expression for concatenating grouped values

public getGroupConcatExpr(string $expression[, string $separator = ',' ]) : Expr

Returns a SQL expression that concatenates values from grouped rows. This is database-agnostic and handles the syntax differences between MySQL (GROUP_CONCAT) and PostgreSQL (STRING_AGG).

Parameters
$expression : string

The column or expression to concatenate

$separator : string = ','

The separator to use between values (default: ',')

Return values
Expr

getIfNullSql()

Returns valid IFNULL expression

public getIfNullSql(string $expression[, string|int $value = '0' ]) : Expr
Parameters
$expression : string
$value : string|int = '0'

Applies when $expression is NULL

Return values
Expr

getIndexList()

Returns the table index information

public getIndexList(string $tableName[, string|null $schemaName = null ]) : array<string|int, mixed>

The return value is an associative array keyed by the UPPERCASE index key (except for primary key, that is always stored under 'PRIMARY' key) as returned by the RDBMS.

The value of each array element is an associative array with the following keys:

SCHEMA_NAME => string; name of database or schema TABLE_NAME => string; name of the table KEY_NAME => string; the original index name COLUMNS_LIST => array; array of index column names INDEX_TYPE => string; lowercase, create index type INDEX_METHOD => string; index method using type => string; see INDEX_TYPE fields => array; see COLUMNS_LIST

Parameters
$tableName : string
$schemaName : string|null = null
Return values
array<string|int, mixed>

getIndexName()

Retrieve valid index name Check index name length and allowed symbols

public getIndexName(string $tableName, string|array<string|int, mixed> $fields[, string $indexType = '' ]) : string
Parameters
$tableName : string
$fields : string|array<string|int, mixed>

the columns list

$indexType : string = ''
Return values
string

getJsonContainsExpr()

Check if a JSON column contains a specific JSON value

public getJsonContainsExpr(string $column, string $value[, string|null $path = null ]) : Expr

Returns a boolean SQL expression. The value parameter must be a JSON-encoded string (e.g., '"hello"', '42', 'true'). Optional path scopes the check. Wildcard paths ('$**') are not supported — use getJsonSearchExpr() instead.

Parameters
$column : string

The column name containing JSON data

$value : string

A JSON-encoded value (e.g., '"hello"', '42')

$path : string|null = null

Optional JSON path to scope the check

Return values
Expr

getJsonExtractExpr()

Extract a scalar value from a JSON column at a given path

public getJsonExtractExpr(string $column, string $path) : Expr

Returns a SQL expression that extracts and unquotes a value from JSON data. The path uses MySQL/SQLite dot notation (e.g., '$.name', '$.address.city'). Platform adapters translate this internally for their native syntax.

Parameters
$column : string

The column name containing JSON data

$path : string

The JSON path (e.g., '$.name', '$.address.city')

Return values
Expr

getJsonSearchExpr()

Search for a string value within a JSON column

public getJsonSearchExpr(string $column, string $value, string $path) : Expr

Returns a boolean SQL expression that checks if a value exists at the given path. Supports '$' recursive wildcard for deep search (e.g., '$.attribute'). The value parameter is a plain PHP string — quoting is handled internally.

Parameters
$column : string

The column name containing JSON data

$value : string

The string value to search for

$path : string

The JSON path, supports '$**' recursive wildcard

Return values
Expr

getLeastSql()

Generate fragment of SQL, that compare with two or more arguments, and returns the smallest (minimum-valued) argument All arguments in data must be quoted

public getLeastSql(array<string|int, mixed> $data) : Expr
Parameters
$data : array<string|int, mixed>
Return values
Expr

getLengthSql()

Generate fragment of SQL that returns length of character string The string argument must be quoted

public getLengthSql(string $string) : Expr
Parameters
$string : string
Return values
Expr

getLock()

Acquire a named lock

public getLock(string $lockName[, int $timeout = 0 ]) : bool
Parameters
$lockName : string

The name of the lock

$timeout : int = 0

Timeout in seconds to wait for the lock

Return values
bool —

True if lock was acquired, false otherwise

getPrimaryKeyName()

Try to find installed primary key name, if not - format new one.

public getPrimaryKeyName(string $tableName[, string|null $schemaName = null ]) : string
Parameters
$tableName : string

Table name

$schemaName : string|null = null
Return values
string —

Primary Key name

getRoundSql()

Generate fragment of SQL for rounding a numeric value to specified precision.

public getRoundSql(string $expression[, int $precision = 0 ]) : Expr

Handles database-specific ROUND function requirements.

Parameters
$expression : string
$precision : int = 0
Return values
Expr

getStandardDeviationSql()

Prepare standard deviation sql function

public getStandardDeviationSql(Expr|string $expressionField) : Expr
Parameters
$expressionField : Expr|string

quoted field name or SQL statement

Return values
Expr

getSubstringSql()

Prepare substring sql function

public getSubstringSql(Expr|string $stringExpression, int|string|Expr $pos[, int|string|Expr|null $len = null ]) : Expr
Parameters
$stringExpression : Expr|string

quoted field name or SQL statement

$pos : int|string|Expr
$len : int|string|Expr|null = null
Return values
Expr

getTableName()

Retrieve valid table name Check table name length and allowed symbols

public getTableName(string $tableName) : string
Parameters
$tableName : string
Return values
string

getTablesChecksum()

Return array of table(s) checksum as table name - checksum pairs

public getTablesChecksum(array<string|int, mixed>|string $tableNames[, string|null $schemaName = null ]) : array<string|int, mixed>
Parameters
$tableNames : array<string|int, mixed>|string
$schemaName : string|null = null
Return values
array<string|int, mixed>

getTimestampDiffExpr()

Get SQL expression for timestamp difference in seconds

public getTimestampDiffExpr(string $startTimestamp, string $endTimestamp) : Expr

Returns the difference between two timestamps in seconds (end - start). This is database-agnostic and handles the syntax differences between MySQL and PostgreSQL.

Parameters
$startTimestamp : string

The start timestamp column or expression

$endTimestamp : string

The end timestamp column or expression

Return values
Expr

getTransactionLevel()

Get adapter transaction level state. Return 0 if all transactions are complete

public getTransactionLevel() : int
Return values
int

getUnixTimestamp()

Convert date format to unix time

public getUnixTimestamp(string|Expr $date) : Expr
Parameters
$date : string|Expr
Return values
Expr

getUnixTimestampExpr()

Generate a database-agnostic Unix timestamp expression

public getUnixTimestampExpr([string|null $timestamp = null ]) : Expr

MySQL: UNIX_TIMESTAMP($timestamp) or UNIX_TIMESTAMP() for current time PostgreSQL: EXTRACT(EPOCH FROM $timestamp)::bigint

Parameters
$timestamp : string|null = null

Optional timestamp expression (defaults to current time)

Return values
Expr

insert()

Inserts a table row with specified data.

public insert(string|array<string|int, mixed>|Select $table, array<string|int, mixed> $bind) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to insert data into.

$bind : array<string|int, mixed>

Column-value pairs.

Return values
int —

The number of affected rows.

insertArray()

Insert array to table based on columns definition

public insertArray(string $table, array<string|int, mixed> $columns, array<string|int, mixed> $data) : int
Parameters
$table : string
$columns : array<string|int, mixed>

the data array column map

$data : array<string|int, mixed>
Return values
int

insertForce()

Inserts a table row with specified data Special for Zero values to identity column

public insertForce(string $table, array<string|int, mixed> $bind) : int
Parameters
$table : string
$bind : array<string|int, mixed>
Return values
int —

The number of affected rows.

insertFromSelect()

Get insert from Select object query

public insertFromSelect(Select $select, string $table[, array<string|int, mixed> $fields = [] ][, bool|int $mode = false ]) : string
Parameters
$select : Select
$table : string
$fields : array<string|int, mixed> = []
$mode : bool|int = false
Return values
string

insertIgnore()

Inserts a table row with specified data.

public insertIgnore(string|array<string|int, mixed>|Select $table, array<string|int, mixed> $bind) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to insert data into.

$bind : array<string|int, mixed>

Column-value pairs.

Return values
int —

The number of affected rows.

insertMultiple()

Inserts a table multiply rows with specified data.

public insertMultiple(string|array<string|int, mixed>|Select $table, array<string|int, mixed> $data) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to insert data into.

$data : array<string|int, mixed>

Column-value pairs or array of Column-value pairs.

Return values
int —

The number of affected rows.

insertOnDuplicate()

Inserts a table row with specified data.

public insertOnDuplicate(string|array<string|int, mixed>|Select $table, array<string|int, mixed> $data[, array<string|int, mixed> $fields = [] ]) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to insert data into.

$data : array<string|int, mixed>

Column-value pairs or array of column-value pairs.

$fields : array<string|int, mixed> = []

update fields pairs or values

Return values
int —

The number of affected rows.

isLocked()

Check if a named lock is currently held

public isLocked(string $lockName) : bool
Parameters
$lockName : string

The name of the lock

Return values
bool —

True if lock is held, false otherwise

isTableExists()

Checks if table exists

public isTableExists(string $tableName[, string|null $schemaName = null ]) : bool
Parameters
$tableName : string
$schemaName : string|null = null
Return values
bool

lastInsertId()

Retrieve last inserted ID

public lastInsertId([string|null $tableName = null ][, string|null $primaryKey = null ]) : string|int
Parameters
$tableName : string|null = null
$primaryKey : string|null = null
Return values
string|int

listTables()

Retrieve the list of all tables in the database

public listTables([string|null $schemaName = null ]) : array<string|int, string>
Parameters
$schemaName : string|null = null
Return values
array<string|int, string> —

List of table names

loadDdlCache()

Load DDL data from cache Return false if cache does not exists

public loadDdlCache(string $tableCacheKey, int $ddlType) : string|array<string|int, mixed>|int|false
Parameters
$tableCacheKey : string

the table cache key

$ddlType : int

the DDL constant

Return values
string|array<string|int, mixed>|int|false

modifyColumn()

Modify the column definition

public modifyColumn(string $tableName, string $columnName, array<string|int, mixed>|string $definition[, bool $flushData = false ][, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$columnName : string
$definition : array<string|int, mixed>|string
$flushData : bool = false
$schemaName : string|null = null
Return values
self

modifyColumnByDdl()

Modify the column definition by data from describe table

public modifyColumnByDdl(string $tableName, string $columnName, array<string|int, mixed>|string $definition[, bool $flushData = false ][, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$columnName : string
$definition : array<string|int, mixed>|string
$flushData : bool = false
$schemaName : string|null = null
Return values
self

modifyTables()

Modify table columns, foreign keys, comments and engine

public modifyTables(array<string|int, mixed> $tables) : self
Parameters
$tables : array<string|int, mixed>
Return values
self

multiQuery()

Executes a SQL statement(s)

public multiQuery(string $sql) : array<string|int, mixed>
Parameters
$sql : string
Return values
array<string|int, mixed>

newTable()

Retrieve DDL object for new table

public newTable([string|null $tableName = null ][, string|null $schemaName = null ]) : Table
Parameters
$tableName : string|null = null

the table name

$schemaName : string|null = null

the database or schema name

Return values
Table

orderRand()

Adds order by random to select object Possible using integer field for optimization

public orderRand(Select $select[, string|null $field = null ]) : self
Parameters
$select : Select
$field : string|null = null
Return values
self

prepareColumnValue()

Prepare value for save in column Return converted to column data type value

public prepareColumnValue(array<string|int, mixed> $column, mixed $value) : mixed
Parameters
$column : array<string|int, mixed>

the column describe array

$value : mixed

prepareSqlCondition()

Build SQL statement for condition

public prepareSqlCondition(string $fieldName, int|string|array<string|int, mixed>|null $condition) : string

If $condition integer or string - exact value will be filtered ('eq' condition)

If $condition is null - IS NULL condition will be generated

If $condition is array - one of the following structures is expected:

  • array("from" => $fromValue, "to" => $toValue)
  • array("eq" => $equalValue)
  • array("neq" => $notEqualValue)
  • array("like" => $likeValue)
  • array("in" => array($inValues))
  • array("nin" => array($notInValues))
  • array("notnull" => $valueIsNotNull)
  • array("null" => $valueIsNull)
  • array("moreq" => $moreOrEqualValue)
  • array("gt" => $greaterValue)
  • array("lt" => $lessValue)
  • array("gteq" => $greaterOrEqualValue)
  • array("lteq" => $lessOrEqualValue)
  • array("finset" => $valueInSet)
  • array("regexp" => $regularExpression)
  • array("seq" => $stringValue)
  • array("sneq" => $stringValue)

If non matched - sequential array is expected and OR conditions will be built using above mentioned structure

Parameters
$fieldName : string
$condition : int|string|array<string|int, mixed>|null
Return values
string

query()

Prepares and executes an SQL statement with bound data.

public query(string|Select $sql[, array<string|int, mixed>|int|string|float $bind = [] ]) : StatementInterface
Parameters
$sql : string|Select

The SQL statement with placeholders. May be a string or \Maho\Db\Select.

$bind : array<string|int, mixed>|int|string|float = []

An array of data or data itself to bind to the placeholders.

Return values
StatementInterface

quote()

Safely quotes a value for an SQL statement.

public quote(Select|Expr|array<string|int, mixed>|null|int|string|float|bool $value[, null|string|int $type = null ]) : string

If an array is passed as the value, the array values are quoted and then returned as a comma-separated string.

Parameters
$value : Select|Expr|array<string|int, mixed>|null|int|string|float|bool

A single value to quote into the condition.

$type : null|string|int = null

The type of the given value e.g. Zend_Db::INT_TYPE, "INT"

Return values
string —

An SQL-safe quoted value (or string of separated values).

quoteColumnAs()

Quote a column identifier and alias.

public quoteColumnAs(string|array<string|int, mixed>|Expr $ident, string|null $alias[, bool $auto = false ]) : string
Parameters
$ident : string|array<string|int, mixed>|Expr

The identifier or expression.

$alias : string|null

An alias for the column.

$auto : bool = false

If true, heed the AUTO_QUOTE_IDENTIFIERS config option.

Return values
string —

The quoted identifier and alias.

quoteIdentifier()

Quotes an identifier.

public quoteIdentifier(string|array<string|int, mixed>|Expr $ident[, bool $auto = false ]) : string

Accepts a string representing a qualified identifier. For Example: $adapter->quoteIdentifier('myschema.mytable') Returns: "myschema"."mytable"

Or, an array of one or more identifiers that may form a qualified identifier: $adapter->quoteIdentifier(array('myschema','my.table')) Returns: "myschema"."my.table"

The actual quote character surrounding the identifiers may vary depending on the adapter.

Parameters
$ident : string|array<string|int, mixed>|Expr

The identifier.

$auto : bool = false

If true, heed the AUTO_QUOTE_IDENTIFIERS config option.

Return values
string —

The quoted identifier.

quoteInto()

Quotes a value and places into a piece of text at a placeholder.

public quoteInto(string $text, Select|Expr|array<string|int, mixed>|null|int|string|float|bool $value[, null|string|int $type = null ][, int|null $count = null ]) : string

The placeholder is a question-mark; all placeholders will be replaced with the quoted value. For example:

$text = "WHERE date < ?"; $date = "2005-01-02"; $safe = $sql->quoteInto($text, $date); // $safe = "WHERE date < '2005-01-02'"
Parameters
$text : string
$value : Select|Expr|array<string|int, mixed>|null|int|string|float|bool

A single value to quote into the condition.

$type : null|string|int = null

The type of the given value e.g. Zend_Db::INT_TYPE, "INT"

$count : int|null = null

count of placeholders to replace

Return values
string —

An SQL-safe quoted value placed into the original text.

quoteTableAs()

Quote a table identifier and alias.

public quoteTableAs(string|array<string|int, mixed>|Expr|Select $ident[, string|null $alias = null ][, bool $auto = false ]) : string
Parameters
$ident : string|array<string|int, mixed>|Expr|Select

The identifier or expression.

$alias : string|null = null

An alias for the table.

$auto : bool = false

If true, heed the AUTO_QUOTE_IDENTIFIERS config option.

Return values
string —

The quoted identifier and alias.

releaseLock()

Release a named lock

public releaseLock(string $lockName) : bool
Parameters
$lockName : string

The name of the lock

Return values
bool —

True if lock was released, false otherwise

renameTable()

Rename table

public renameTable(string $oldTableName, string $newTableName[, string|null $schemaName = null ]) : bool
Parameters
$oldTableName : string
$newTableName : string
$schemaName : string|null = null
Return values
bool

renameTablesBatch()

Rename several tables

public renameTablesBatch(array<string|int, mixed> $tablePairs) : bool
Parameters
$tablePairs : array<string|int, mixed>

array('oldName' => 'Name1', 'newName' => 'Name2')

Tags
throws
Exception
Return values
bool

resetDdlCache()

Reset cached DDL data from cache if table name is null - reset all cached DDL data

public resetDdlCache([string|null $tableName = null ][, string|null $schemaName = null ]) : self
Parameters
$tableName : string|null = null
$schemaName : string|null = null
Return values
self

rollBack()

Roll-back DB transaction

public rollBack() : self
Return values
self

saveDdlCache()

Save DDL data into cache

public saveDdlCache(string $tableCacheKey, int $ddlType, mixed $data) : self
Parameters
$tableCacheKey : string
$ddlType : int
$data : mixed
Return values
self

selectsByRange()

Get insert queries in array for insert by range with step parameter

public selectsByRange(string $rangeField, Select $select[, int $stepCount = 100 ]) : array<string|int, mixed>
Parameters
$rangeField : string
$select : Select
$stepCount : int = 100
Return values
array<string|int, mixed>

showTableStatus()

Returns short table status array

public showTableStatus(string $tableName[, string|null $schemaName = null ]) : array<string|int, mixed>|false
Parameters
$tableName : string
$schemaName : string|null = null
Return values
array<string|int, mixed>|false

startSetup()

Run additional environment before setup

public startSetup() : self
Return values
self

supportStraightJoin()

Check if the database support STRAIGHT JOIN

public supportStraightJoin() : bool
Return values
bool

tableColumnExists()

Check is table column exists

public tableColumnExists(string $tableName, string $columnName[, string|null $schemaName = null ]) : bool
Parameters
$tableName : string
$columnName : string
$schemaName : string|null = null
Return values
bool

truncateTable()

Truncate a table

public truncateTable(string $tableName[, string|null $schemaName = null ]) : self
Parameters
$tableName : string
$schemaName : string|null = null
Return values
self

update()

Updates table rows with specified data based on a WHERE clause.

public update(string|array<string|int, mixed>|Select $table, array<string|int, mixed> $bind[, string|array<string|int, mixed> $where = '' ]) : int
Parameters
$table : string|array<string|int, mixed>|Select

The table to update.

$bind : array<string|int, mixed>

Column-value pairs.

$where : string|array<string|int, mixed> = ''

UPDATE WHERE clause(s).

Return values
int —

The number of affected rows.

updateFromSelect()

Get update table query using select object for join and update

public updateFromSelect(Select $select, string|array<string|int, mixed> $table) : string
Parameters
$select : Select
$table : string|array<string|int, mixed>
Return values
string
On this page

Search results