Command

Type: Class
Namespace: craft\db
Inherits: craft\db\Command » yii\db\Command (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
Implements: yii\base\Configurable (opens new window)
Since: 3.0.0

# Public Properties

Property	Description
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
db	craft\db\Connection – Connection the DB connection that this command is associated with.
fetchMode (opens new window)	integer (opens new window) – The default fetch mode for this command.
params (opens new window)	array (opens new window) – The parameters (name => value) that are bound to the current PDO statement.
pdoStatement (opens new window)	PDOStatement (opens new window) – The PDOStatement object that this command is associated with
queryCacheDependency (opens new window)	yii\caching\Dependency (opens new window) – The dependency to be associated with the cached query result for this command
queryCacheDuration (opens new window)	integer (opens new window) – The default number of seconds that query results can remain valid in cache.
rawSql (opens new window)	string (opens new window) – The raw SQL with parameter values inserted into the corresponding placeholders in sql (opens new window).
sql (opens new window)	string (opens new window) – The SQL statement to be executed.

# `db`

Type: craft\db\Connection
Default value: null

Connection the DB connection that this command is associated with.

View source (opens new window)

# Protected Properties

Property	Description
pendingParams (opens new window)	array (opens new window) – Pending parameters to be bound to the current PDO statement.

# Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
addCheck() (opens new window)	Creates a SQL command for adding a check constraint to an existing table.
addColumn() (opens new window)	Creates a SQL command for adding a new DB column.
addCommentOnColumn() (opens new window)	Builds a SQL command for adding comment to column.
addCommentOnTable() (opens new window)	Builds a SQL command for adding comment to table.
addDefaultValue() (opens new window)	Creates a SQL command for adding a default value constraint to an existing table.
addForeignKey() (opens new window)	Creates a SQL command for adding a foreign key constraint to an existing table.
addPrimaryKey() (opens new window)	Creates a SQL command for adding a primary key constraint to an existing table.
addUnique() (opens new window)	Creates a SQL command for adding an unique constraint to an existing table.
alterColumn() (opens new window)	Creates a SQL command for changing the definition of a column.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
batchInsert()	Creates a batch INSERT command.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
bindParam() (opens new window)	Binds a parameter to the SQL statement to be executed.
bindValue() (opens new window)	Binds a value to a parameter.
bindValues() (opens new window)	Binds a list of values to the corresponding parameters.
cache() (opens new window)	Enables query cache for this command.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
cancel() (opens new window)	Cancels the execution of the SQL statement.
checkIntegrity() (opens new window)	Builds a SQL command for enabling or disabling integrity check.
className() (opens new window)	Returns the fully qualified name of this class.
createIndex() (opens new window)	Creates a SQL command for creating a new index.
createTable() (opens new window)	Creates a SQL command for creating a new DB table.
createView() (opens new window)	Creates a SQL View.
delete() (opens new window)	Creates a DELETE command.
deleteDuplicates()	Creates a DELETE command that will only delete duplicate rows from a table.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
dropCheck() (opens new window)	Creates a SQL command for dropping a check constraint.
dropColumn() (opens new window)	Creates a SQL command for dropping a DB column.
dropCommentFromColumn() (opens new window)	Builds a SQL command for dropping comment from column.
dropCommentFromTable() (opens new window)	Builds a SQL command for dropping comment from table.
dropDefaultValue() (opens new window)	Creates a SQL command for dropping a default value constraint.
dropForeignKey() (opens new window)	Creates a SQL command for dropping a foreign key constraint.
dropIndex() (opens new window)	Creates a SQL command for dropping an index.
dropPrimaryKey() (opens new window)	Creates a SQL command for removing a primary key constraint to an existing table.
dropTable() (opens new window)	Creates a SQL command for dropping a DB table.
dropTableIfExists()	Creates a SQL statement for dropping a DB table, if it exists.
dropUnique() (opens new window)	Creates a SQL command for dropping an unique constraint.
dropView() (opens new window)	Drops a SQL View.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
execute() (opens new window)	Executes the SQL statement.
executeResetSequence() (opens new window)	Executes a db command resetting the sequence value of a table's primary key.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getRawSql() (opens new window)	Returns the raw SQL by inserting parameter values into the corresponding placeholders in sql (opens new window).
getSql() (opens new window)	Returns the SQL statement for this command.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
insert()	Creates an INSERT command.
noCache() (opens new window)	Disables query cache for this command.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
prepare() (opens new window)	Prepares the SQL statement to be executed.
query() (opens new window)	Executes the SQL statement and returns query result.
queryAll() (opens new window)	Executes the SQL statement and returns ALL rows at once.
queryColumn() (opens new window)	Executes the SQL statement and returns the first column of the result.
queryOne() (opens new window)	Executes the SQL statement and returns the first row of the result.
queryScalar() (opens new window)	Executes the SQL statement and returns the value of the first column in the first row of data.
renameColumn() (opens new window)	Creates a SQL command for renaming a column.
renameSequence()	Creates a SQL statement for renaming a DB sequence.
renameTable() (opens new window)	Creates a SQL command for renaming a DB table.
replace()	Creates a SQL statement for replacing some text with other text in a given table column.
resetSequence() (opens new window)	Creates a SQL command for resetting the sequence value of a table's primary key.
restore()	Creates a SQL statement for restoring a soft-deleted row.
setRawSql() (opens new window)	Specifies the SQL statement to be executed. The SQL statement will not be modified in any way.
setSql() (opens new window)	Specifies the SQL statement to be executed. The SQL statement will be quoted using yii\db\Connection::quoteSql() (opens new window).
softDelete()	Creates a SQL statement for soft-deleting a row.
trigger() (opens new window)	Triggers an event.
truncateTable() (opens new window)	Creates a SQL command for truncating a DB table.
update()	Creates an UPDATE command.
upsert()	Creates a command to insert rows into a database table if they do not already exist (matching unique constraints), or update them if they do.

# `batchInsert()`

Creates a batch INSERT command.

For example,

$connection->createCommand()->batchInsert('user', ['name', 'age'], [
    ['Tom', 30],
    ['Jane', 20],
    ['Linda', 25],
])->execute();

The method will properly escape the column names, and quote the values to be inserted.

Note that the values in each row must match the corresponding column names.

Also note that the created command is not executed until execute() (opens new window) is called.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table that new rows will be inserted into.
$columns (array (opens new window)) – The column names.
$rows (array (opens new window)) – The rows to be batch inserted into the table.
$includeAuditColumns (boolean (opens new window)) – Whether dateCreated, dateUpdated, and uid values should be added to $columns.

Returns

static – The command object itself.

# `deleteDuplicates()`

Since: 3.5.2

Creates a DELETE command that will only delete duplicate rows from a table.

For example,

$connection->createCommand()->deleteDuplicates('user', ['email'])->execute();

The method will properly escape the table and column names.

Note that the created command is not executed until execute() (opens new window) is called.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table where the data will be deleted from
$columns (string (opens new window)[]) – The column names that contain duplicate data
$pk (string (opens new window)) – The primary key column name

Returns

$this – The command object itself

# `dropTableIfExists()`

Creates a SQL statement for dropping a DB table, if it exists.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table to be dropped. The name will be properly quoted by the method.

Returns

craft\db\Command – The command object itself

# `insert()`

Creates an INSERT command.

For example,

$connection->createCommand()->insert('user', [
    'name' => 'Sam',
    'age' => 30,
])->execute();

The method will properly escape the column names, and bind the values to be inserted.

Note that the created command is not executed until execute() (opens new window) is called.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table that new rows will be inserted into.
$columns (array (opens new window)) – The column data (name => value) to be inserted into the table.
$includeAuditColumns (boolean (opens new window)) – Whether dateCreated, dateUpdated, and uid values should be added to $columns.

Returns

static – The command object itself

# `renameSequence()`

Creates a SQL statement for renaming a DB sequence.

View source (opens new window)

Arguments

$oldName (string (opens new window)) – The sequence to be renamed. The name will be properly quoted by the method.
$newName (string (opens new window)) – The new sequence name. The name will be properly quoted by the method.

Returns

craft\db\Command – The command object itself

# `replace()`

Creates a SQL statement for replacing some text with other text in a given table column.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table to be updated.
$column (string (opens new window)) – The column to be searched.
$find (string (opens new window)) – The text to be searched for.
$replace (string (opens new window)) – The replacement text.
$condition (string (opens new window), array (opens new window)) – The condition that will be put in the WHERE part. Please refer to craft\db\Query::where() on how to specify condition.
$params (array (opens new window)) – The parameters to be bound to the command.

Returns

craft\db\Command – The command object itself.

# `restore()`

Since: 3.1.0

Creates a SQL statement for restoring a soft-deleted row.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table to be updated.
$condition (string (opens new window), array (opens new window)) – The condition that will be put in the WHERE part. Please refer to craft\db\Query::where() on how to specify condition.
$params (array (opens new window)) – The parameters to be bound to the command.

Returns

static – The command object itself.

# `softDelete()`

Since: 3.1.0

Creates a SQL statement for soft-deleting a row.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table to be updated.
$condition (string (opens new window), array (opens new window)) – The condition that will be put in the WHERE part. Please refer to craft\db\Query::where() on how to specify condition.
$params (array (opens new window)) – The parameters to be bound to the command.

Returns

static – The command object itself.

# `update()`

Creates an UPDATE command.

For example,

$connection->createCommand()->update('user', ['status' => 1], 'age > 30')->execute();

or with using parameter binding for the condition:

$minAge = 30;
$connection->createCommand()->update('user', ['status' => 1], 'age > :minAge', [':minAge' => $minAge])->execute();

The method will properly escape the column names and bind the values to be updated.

Note that the created command is not executed until execute() (opens new window) is called.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table to be updated.
$columns (array (opens new window)) – The column data (name => value) to be updated.
$condition (string (opens new window), array (opens new window)) – The condition that will be put in the WHERE part. Please refer to craft\db\Query::where() on how to specify condition.
$params (array (opens new window)) – The parameters to be bound to the command.
$includeAuditColumns (boolean (opens new window)) – Whether the dateUpdated value should be added to $columns.

Returns

static – The command object itself.

# `upsert()`

Creates a command to insert rows into a database table if they do not already exist (matching unique constraints), or update them if they do.

For example,

$sql = $queryBuilder->upsert('pages', [
    'name' => 'Front page',
    'url' => 'https://example.com/', // url is unique
    'visits' => 0,
], [
    'visits' => new \yii\db\Expression('visits + 1'),
], $params);

The method will properly escape the table and column names.

View source (opens new window)

Arguments

$table (string (opens new window)) – The table that new rows will be inserted into/updated in.
$insertColumns (array (opens new window), craft\db\Query) – The column data (name => value) to be inserted into the table or instance of craft\db\Query to perform INSERT INTO ... SELECT SQL statement.
$updateColumns (array (opens new window), boolean (opens new window)) – The column data (name => value) to be updated if they already exist. If true is passed, the column data will be updated to match the insert column data. If false is passed, no update will be performed if the column data already exists.
$params (array (opens new window)) – The parameters to be bound to the command.
$includeAuditColumns (boolean (opens new window)) – Whether dateCreated, dateUpdated, and uid values should be added to $columns.

Returns

$this – The command object itself.

# Protected Methods

Method	Description
bindPendingParams() (opens new window)	Binds pending parameters that were registered via bindValue() (opens new window) and bindValues() (opens new window).
getCacheKey() (opens new window)	Returns the cache key for the query.
internalExecute() (opens new window)	Executes a prepared statement.
logQuery() (opens new window)	Logs the current database query if query logging is enabled and returns the profiling token if profiling is enabled.
queryInternal() (opens new window)	Performs the actual DB query of a SQL statement.
refreshTableSchema() (opens new window)	Refreshes table schema, which was marked by requireTableSchemaRefresh() (opens new window).
requireTableSchemaRefresh() (opens new window)	Marks a specified table schema to be refreshed after command execution.
requireTransaction() (opens new window)	Marks the command to be executed in transaction.
reset() (opens new window)	Resets command properties to their initial state.
setRetryHandler() (opens new window)	Sets a callable (e.g. anonymous function) that is called when yii\db\Exception (opens new window) is thrown when executing the command. The signature of the callable should be:

← ActiveRecord Connection →

Command

# Public Properties

# db

# Protected Properties

# Public Methods

# batchInsert()

Arguments

Returns

# deleteDuplicates()

Arguments

Returns

# dropTableIfExists()

Arguments

Returns

# insert()

Arguments

Returns

# renameSequence()

Arguments

Returns

# replace()

Arguments

Returns

# restore()

Arguments

Returns

# softDelete()

Arguments

Returns

# update()

Arguments

Returns

# upsert()

Arguments

Returns

# Protected Methods

# `db`

# `batchInsert()`

# `deleteDuplicates()`

# `dropTableIfExists()`

# `insert()`

# `renameSequence()`

# `replace()`

# `restore()`

# `softDelete()`

# `update()`

# `upsert()`