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_CASCADE
public
mixed
FK_ACTION_CASCADE
= 'CASCADE'
FK_ACTION_NO_ACTION
public
mixed
FK_ACTION_NO_ACTION
= 'NO ACTION'
FK_ACTION_RESTRICT
public
mixed
FK_ACTION_RESTRICT
= 'RESTRICT'
FK_ACTION_SET_DEFAULT
public
mixed
FK_ACTION_SET_DEFAULT
= 'SET DEFAULT'
FK_ACTION_SET_NULL
public
mixed
FK_ACTION_SET_NULL
= 'SET NULL'
INDEX_TYPE_FULLTEXT
public
mixed
INDEX_TYPE_FULLTEXT
= 'fulltext'
INDEX_TYPE_INDEX
public
mixed
INDEX_TYPE_INDEX
= 'index'
INDEX_TYPE_PRIMARY
public
mixed
INDEX_TYPE_PRIMARY
= 'primary'
INDEX_TYPE_UNIQUE
public
mixed
INDEX_TYPE_UNIQUE
= 'unique'
INSERT_IGNORE
public
mixed
INSERT_IGNORE
= 2
INSERT_ON_DUPLICATE
public
mixed
INSERT_ON_DUPLICATE
= 1
INTERVAL_DAY
public
mixed
INTERVAL_DAY
= 'DAYS'
INTERVAL_HOUR
public
mixed
INTERVAL_HOUR
= 'HOURS'
INTERVAL_MINUTE
public
mixed
INTERVAL_MINUTE
= 'MINUTES'
INTERVAL_MONTH
public
mixed
INTERVAL_MONTH
= 'MONTHS'
INTERVAL_SECOND
public
mixed
INTERVAL_SECOND
= 'SECOND'
INTERVAL_YEAR
public
mixed
INTERVAL_YEAR
= 'YEARS'
ISO_DATE_FORMAT
public
mixed
ISO_DATE_FORMAT
= 'yyyy-MM-dd'
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
selfaddForeignKey()
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
selfaddIndex()
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
StatementInterfaceallowDdlCache()
Allow DDL caching
public
allowDdlCache() : self
Return values
selfbeginTransaction()
Begin new DB transaction for connection
public
beginTransaction() : self
Return values
selfchangeColumn()
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
selfchangeTableAutoIncrement()
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
StatementInterfacecloseConnection()
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
selfcreateTable()
Create table from DDL object
public
createTable(Table $table) : StatementInterface
Parameters
- $table : Table
Tags
Return values
StatementInterfacecreateTableByDdl()
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
TablecreateTableFromSelect()
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
createTemporaryTable()
Create temporary table from DDL object
public
createTemporaryTable(Table $table) : StatementInterface
Parameters
- $table : Table
Tags
Return values
StatementInterfacedecodeVarbinary()
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
stringdescribeTable()
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
selfdisallowDdlCache()
Disallow DDL caching
public
disallowDdlCache() : self
Return values
selfdropColumn()
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
booldropForeignKey()
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
selfdropIndex()
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|StatementInterfacedropTable()
Drop table from database
public
dropTable(string $tableName[, string|null $schemaName = null ]) : bool
Parameters
- $tableName : string
- $schemaName : string|null = null
Return values
booldropTemporaryTable()
Drop temporary table from database
public
dropTemporaryTable(string $tableName[, string|null $schemaName = null ]) : bool
Parameters
- $tableName : string
- $schemaName : string|null = null
Return values
booldropTrigger()
Drop trigger
public
dropTrigger(string $triggerName) : self
Parameters
- $triggerName : string
Return values
selfenableTableKeys()
Re-create missing indexes
public
enableTableKeys(string $tableName[, string|null $schemaName = null ]) : self
Parameters
- $tableName : string
- $schemaName : string|null = null
Return values
selfendSetup()
Run additional environment after setup
public
endSetup() : self
Return values
selffetchAll()
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>|falseformatDate()
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
ExprforUpdate()
Render SQL FOR UPDATE clause
public
forUpdate(string $sql) : string
Parameters
- $sql : string
Return values
stringfromUnixtime()
Convert unix time to date format
public
fromUnixtime(int|Expr $timestamp) : Expr
Parameters
- $timestamp : int|Expr
Return values
ExprgetCaseSql()
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
ExprgetCastToTextSql()
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
ExprgetCheckSql()
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
Return values
ExprgetConcatSql()
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
ExprgetConfig()
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
ConnectiongetDateAddSql()
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
Return values
ExprgetDateDiffSql()
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
Return values
ExprgetDateFormatSql()
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
ExprgetDatePartSql()
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
ExprgetDateSubSql()
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
Return values
ExprgetDateTimeAddSql()
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
Return values
ExprgetDaysUntilAnniversarySql()
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
ExprgetForeignKeyName()
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
stringgetForeignKeys()
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
ExprgetGroupConcatExpr()
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
ExprgetIfNullSql()
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
ExprgetIndexList()
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
stringgetJsonContainsExpr()
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
ExprgetJsonExtractExpr()
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
ExprgetJsonSearchExpr()
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
ExprgetLeastSql()
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
ExprgetLengthSql()
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
ExprgetLock()
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
ExprgetStandardDeviationSql()
Prepare standard deviation sql function
public
getStandardDeviationSql(Expr|string $expressionField) : Expr
Parameters
- $expressionField : Expr|string
-
quoted field name or SQL statement
Return values
ExprgetSubstringSql()
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
ExprgetTableName()
Retrieve valid table name Check table name length and allowed symbols
public
getTableName(string $tableName) : string
Parameters
- $tableName : string
Return values
stringgetTablesChecksum()
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
ExprgetTransactionLevel()
Get adapter transaction level state. Return 0 if all transactions are complete
public
getTransactionLevel() : int
Return values
intgetUnixTimestamp()
Convert date format to unix time
public
getUnixTimestamp(string|Expr $date) : Expr
Parameters
- $date : string|Expr
Return values
ExprgetUnixTimestampExpr()
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
Exprinsert()
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
intinsertForce()
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
stringinsertIgnore()
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
boollastInsertId()
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|intlistTables()
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|falsemodifyColumn()
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
selfmodifyColumnByDdl()
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
selfmodifyTables()
Modify table columns, foreign keys, comments and engine
public
modifyTables(array<string|int, mixed> $tables) : self
Parameters
- $tables : array<string|int, mixed>
Return values
selfmultiQuery()
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
TableorderRand()
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
selfprepareColumnValue()
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
stringquery()
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
StatementInterfacequote()
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
boolrenameTablesBatch()
Rename several tables
public
renameTablesBatch(array<string|int, mixed> $tablePairs) : bool
Parameters
- $tablePairs : array<string|int, mixed>
-
array('oldName' => 'Name1', 'newName' => 'Name2')
Tags
Return values
boolresetDdlCache()
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
selfrollBack()
Roll-back DB transaction
public
rollBack() : self
Return values
selfsaveDdlCache()
Save DDL data into cache
public
saveDdlCache(string $tableCacheKey, int $ddlType, mixed $data) : self
Parameters
- $tableCacheKey : string
- $ddlType : int
- $data : mixed
Return values
selfselect()
Creates and returns a new \Maho\Db\Select object for this adapter.
public
select() : Select
Return values
SelectselectsByRange()
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>setCacheAdapter()
public
setCacheAdapter(Mage_Core_Model_Cache $adapter) : self
Parameters
- $adapter : Mage_Core_Model_Cache
Return values
selfshowTableStatus()
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>|falsestartSetup()
Run additional environment before setup
public
startSetup() : self
Return values
selfsupportStraightJoin()
Check if the database support STRAIGHT JOIN
public
supportStraightJoin() : bool
Return values
booltableColumnExists()
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
booltruncateTable()
Truncate a table
public
truncateTable(string $tableName[, string|null $schemaName = null ]) : self
Parameters
- $tableName : string
- $schemaName : string|null = null
Return values
selfupdate()
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>