2013-06-21 10:32:08 +12:00
|
|
|
<?php
|
|
|
|
|
2016-06-15 16:03:16 +12:00
|
|
|
namespace SilverStripe\ORM\Queries;
|
|
|
|
|
2013-06-21 10:32:08 +12:00
|
|
|
/**
|
|
|
|
* Represents a SQL expression which may have field values assigned
|
|
|
|
* (UPDATE/INSERT Expressions)
|
|
|
|
*/
|
2016-11-29 12:31:16 +13:00
|
|
|
interface SQLWriteExpression
|
|
|
|
{
|
2014-08-15 18:53:05 +12:00
|
|
|
|
2016-11-29 12:31:16 +13:00
|
|
|
/**
|
|
|
|
* Adds assignments for a list of several fields.
|
|
|
|
*
|
|
|
|
* For multi-row objects this applies this to the current row.
|
|
|
|
*
|
|
|
|
* Note that field values must not be escaped, as these will be internally
|
|
|
|
* parameterised by the database engine.
|
|
|
|
*
|
|
|
|
* <code>
|
|
|
|
*
|
|
|
|
* // Basic assignments
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->addAssignments([
|
2016-11-29 12:31:16 +13:00
|
|
|
* '"Object"."Title"' => 'Bob',
|
|
|
|
* '"Object"."Description"' => 'Bob was here'
|
2020-04-20 19:07:53 +12:00
|
|
|
* ])
|
2016-11-29 12:31:16 +13:00
|
|
|
*
|
|
|
|
* // Parameterised assignments
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->addAssignments([
|
|
|
|
* '"Object"."Title"' => ['?' => 'Bob'],
|
|
|
|
* '"Object"."Description"' => ['?' => null]
|
|
|
|
* ])
|
2016-11-29 12:31:16 +13:00
|
|
|
*
|
|
|
|
* // Complex parameters
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->addAssignments([
|
|
|
|
* '"Object"."Score"' => ['MAX(?,?)' => [1, 3]]
|
|
|
|
* ]);
|
2016-11-29 12:31:16 +13:00
|
|
|
*
|
2020-04-20 19:07:53 +12:00
|
|
|
* // Assignment of literal SQL for a field. The empty array is
|
2021-12-13 09:05:33 +01:00
|
|
|
* // important to denote the zero-number parameter list
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->addAssignments([
|
|
|
|
* '"Object"."Score"' => ['NOW()' => []]
|
|
|
|
* ]);
|
2016-11-29 12:31:16 +13:00
|
|
|
*
|
|
|
|
* </code>
|
|
|
|
*
|
|
|
|
* @param array $assignments The list of fields to assign
|
|
|
|
* @return $this Self reference
|
|
|
|
*/
|
|
|
|
public function addAssignments(array $assignments);
|
2014-08-15 18:53:05 +12:00
|
|
|
|
2016-11-29 12:31:16 +13:00
|
|
|
/**
|
|
|
|
* Sets the list of assignments to the given list
|
|
|
|
*
|
|
|
|
* For multi-row objects this applies this to the current row.
|
|
|
|
*
|
|
|
|
* @see SQLWriteExpression::addAssignments() for syntax examples
|
|
|
|
*
|
|
|
|
* @param array $assignments
|
|
|
|
* @return $this Self reference
|
|
|
|
*/
|
|
|
|
public function setAssignments(array $assignments);
|
2014-08-15 18:53:05 +12:00
|
|
|
|
2016-11-29 12:31:16 +13:00
|
|
|
/**
|
|
|
|
* Retrieves the list of assignments in parameterised format
|
|
|
|
*
|
|
|
|
* For multi-row objects returns assignments for the current row.
|
|
|
|
*
|
2020-04-20 19:25:47 +01:00
|
|
|
* @return array List of assignments. The key of this array will be the
|
2016-11-29 12:31:16 +13:00
|
|
|
* column to assign, and the value a parameterised array in the format
|
2020-04-20 19:07:53 +12:00
|
|
|
* ['SQL' => [parameters]];
|
2016-11-29 12:31:16 +13:00
|
|
|
*/
|
|
|
|
public function getAssignments();
|
2014-08-15 18:53:05 +12:00
|
|
|
|
2016-11-29 12:31:16 +13:00
|
|
|
/**
|
|
|
|
* Set the value for a single field
|
|
|
|
*
|
|
|
|
* For multi-row objects this applies this to the current row.
|
|
|
|
*
|
|
|
|
* E.g.
|
|
|
|
* <code>
|
|
|
|
*
|
|
|
|
* // Literal assignment
|
|
|
|
* $query->assign('"Object"."Description"', 'lorum ipsum'));
|
|
|
|
*
|
|
|
|
* // Single parameter
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->assign('"Object"."Title"', ['?' => 'Bob']);
|
2016-11-29 12:31:16 +13:00
|
|
|
*
|
|
|
|
* // Complex parameters
|
2020-04-20 19:07:53 +12:00
|
|
|
* $query->assign('"Object"."Score"', ['MAX(?,?)' => [1, 3]]);
|
2016-11-29 12:31:16 +13:00
|
|
|
* </code>
|
|
|
|
*
|
|
|
|
* @param string $field The field name to update
|
|
|
|
* @param mixed $value The value to assign to this field. This could be an
|
|
|
|
* array containing a parameterised SQL query of any number of parameters,
|
|
|
|
* or a single literal value.
|
|
|
|
* @return $this Self reference
|
|
|
|
*/
|
|
|
|
public function assign($field, $value);
|
2014-08-15 18:53:05 +12:00
|
|
|
|
2016-11-29 12:31:16 +13:00
|
|
|
/**
|
|
|
|
* Assigns a value to a field using the literal SQL expression, rather than
|
|
|
|
* a value to be escaped
|
|
|
|
*
|
|
|
|
* For multi-row objects this applies this to the current row.
|
|
|
|
*
|
|
|
|
* @param string $field The field name to update
|
|
|
|
* @param string $sql The SQL to use for this update. E.g. "NOW()"
|
|
|
|
* @return $this Self reference
|
|
|
|
*/
|
|
|
|
public function assignSQL($field, $sql);
|
2013-06-21 10:32:08 +12:00
|
|
|
}
|