mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-02 14:18:46 +02:00
Merge pull request #7320 from robbieaverill/pulls/3.7/data-query-docblocks
NEW Fix incorrect scalar types in doc blocks, add chainable returns in setters
This commit is contained in:
Daniel Hensby
GitHub
commit
792925a3b9
@ -31,7 +31,7 @@ class DataQuery {
|
||||
private $queriedColumns = null;
|
||||
|
||||
/**
|
||||
* @var Boolean
|
||||
* @var boolean
|
||||
*/
|
||||
private $queryFinalised = false;
|
||||
|
||||
@ -43,7 +43,7 @@ class DataQuery {
|
||||
/**
|
||||
* Create a new DataQuery.
|
||||
*
|
||||
* @param String The name of the DataObject class that you wish to query
|
||||
* @param string The name of the DataObject class that you wish to query
|
||||
*/
|
||||
public function __construct($dataClass) {
|
||||
$this->dataClass = $dataClass;
|
||||
@ -59,6 +59,8 @@ class DataQuery {
|
||||
|
||||
/**
|
||||
* Return the {@link DataObject} class that is being queried.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function dataClass() {
|
||||
return $this->dataClass;
|
||||
@ -67,6 +69,8 @@ class DataQuery {
|
||||
/**
|
||||
* Return the {@link SQLQuery} object that represents the current query; note that it will
|
||||
* be a clone of the object.
|
||||
*
|
||||
* @return SQLQuery
|
||||
*/
|
||||
public function query() {
|
||||
return $this->getFinalisedQuery();
|
||||
@ -79,7 +83,7 @@ class DataQuery {
|
||||
* @param string|array $fieldExpression The predicate of the condition to remove
|
||||
* (ignoring parameters). The expression will be considered a match if it's
|
||||
* contained within any other predicate.
|
||||
* @return DataQuery Self reference
|
||||
* @return $this
|
||||
*/
|
||||
public function removeFilterOn($fieldExpression) {
|
||||
$matched = false;
|
||||
@ -159,8 +163,13 @@ class DataQuery {
|
||||
$obj->extend('augmentDataQueryCreation', $this->query, $this);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array $queriedColumns
|
||||
* @return $this
|
||||
*/
|
||||
public function setQueriedColumns($queriedColumns) {
|
||||
$this->queriedColumns = $queriedColumns;
|
||||
return $this;
|
||||
}
|
||||
|
||||
/**
|
||||
@ -292,6 +301,7 @@ class DataQuery {
|
||||
* Ensure that if a query has an order by clause, those columns are present in the select.
|
||||
*
|
||||
* @param SQLQuery $query
|
||||
* @param array $originalSelect
|
||||
* @return null
|
||||
*/
|
||||
protected function ensureSelectContainsOrderbyColumns($query, $originalSelect = array()) {
|
||||
@ -361,6 +371,8 @@ class DataQuery {
|
||||
|
||||
/**
|
||||
* Execute the query and return the result as {@link Query} object.
|
||||
*
|
||||
* @return SS_Query
|
||||
*/
|
||||
public function execute() {
|
||||
return $this->getFinalisedQuery()->execute();
|
||||
@ -379,6 +391,8 @@ class DataQuery {
|
||||
/**
|
||||
* Return the number of records in this query.
|
||||
* Note that this will issue a separate SELECT COUNT() query.
|
||||
*
|
||||
* @return int
|
||||
*/
|
||||
public function count() {
|
||||
$baseClass = ClassInfo::baseDataClass($this->dataClass);
|
||||
@ -388,7 +402,7 @@ class DataQuery {
|
||||
/**
|
||||
* Return the maximum value of the given field in this DataList
|
||||
*
|
||||
* @param String $field Unquoted database column name. Will be ANSI quoted
|
||||
* @param string $field Unquoted database column name. Will be ANSI quoted
|
||||
* automatically so must not contain double quotes.
|
||||
* @return string
|
||||
*/
|
||||
@ -403,7 +417,7 @@ class DataQuery {
|
||||
/**
|
||||
* Return the minimum value of the given field in this DataList
|
||||
*
|
||||
* @param String $field Unquoted database column name. Will be ANSI quoted
|
||||
* @param string $field Unquoted database column name. Will be ANSI quoted
|
||||
* automatically so must not contain double quotes.
|
||||
* @return string
|
||||
*/
|
||||
@ -418,7 +432,7 @@ class DataQuery {
|
||||
/**
|
||||
* Return the average value of the given field in this DataList
|
||||
*
|
||||
* @param String $field Unquoted database column name. Will be ANSI quoted
|
||||
* @param string $field Unquoted database column name. Will be ANSI quoted
|
||||
* automatically so must not contain double quotes.
|
||||
* @return string
|
||||
*/
|
||||
@ -433,7 +447,7 @@ class DataQuery {
|
||||
/**
|
||||
* Return the sum of the values of the given field in this DataList
|
||||
*
|
||||
* @param String $field Unquoted database column name. Will be ANSI quoted
|
||||
* @param string $field Unquoted database column name. Will be ANSI quoted
|
||||
* automatically so must not contain double quotes.
|
||||
* @return string
|
||||
*/
|
||||
@ -447,6 +461,9 @@ class DataQuery {
|
||||
|
||||
/**
|
||||
* Runs a raw aggregate expression. Please handle escaping yourself
|
||||
*
|
||||
* @param string $expression
|
||||
* @return string
|
||||
*/
|
||||
public function aggregate($expression) {
|
||||
return $this->getFinalisedQuery()->aggregate($expression)->execute()->value();
|
||||
@ -455,6 +472,8 @@ class DataQuery {
|
||||
/**
|
||||
* Return the first row that would be returned by this full DataQuery
|
||||
* Note that this will issue a separate SELECT ... LIMIT 1 query.
|
||||
*
|
||||
* @return SQLSelect
|
||||
*/
|
||||
public function firstRow() {
|
||||
return $this->getFinalisedQuery()->firstRow();
|
||||
@ -463,6 +482,8 @@ class DataQuery {
|
||||
/**
|
||||
* Return the last row that would be returned by this full DataQuery
|
||||
* Note that this will issue a separate SELECT ... LIMIT query.
|
||||
*
|
||||
* @return SQLSelect
|
||||
*/
|
||||
public function lastRow() {
|
||||
return $this->getFinalisedQuery()->lastRow();
|
||||
@ -470,6 +491,10 @@ class DataQuery {
|
||||
|
||||
/**
|
||||
* Update the SELECT clause of the query with the columns from the given table
|
||||
*
|
||||
* @param SQLQuery $query
|
||||
* @param string $tableClass
|
||||
* @param array $columns
|
||||
*/
|
||||
protected function selectColumnsFromTable(SQLQuery &$query, $tableClass, $columns = null) {
|
||||
// Add SQL for multi-value fields
|
||||
@ -498,7 +523,8 @@ class DataQuery {
|
||||
/**
|
||||
* Append a GROUP BY clause to this query.
|
||||
*
|
||||
* @param String $groupby Escaped SQL statement
|
||||
* @param string $groupby Escaped SQL statement
|
||||
* @return $this
|
||||
*/
|
||||
public function groupby($groupby) {
|
||||
$this->query->addGroupBy($groupby);
|
||||
@ -508,7 +534,8 @@ class DataQuery {
|
||||
/**
|
||||
* Append a HAVING clause to this query.
|
||||
*
|
||||
* @param String $having Escaped SQL statement
|
||||
* @param string $having Escaped SQL statement
|
||||
* @return $this
|
||||
*/
|
||||
public function having($having) {
|
||||
$this->query->addHaving($having);
|
||||
@ -545,7 +572,7 @@ class DataQuery {
|
||||
*
|
||||
* @param string|array|SQLConditionGroup $filter Predicate(s) to set, as escaped SQL statements or
|
||||
* paramaterised queries
|
||||
* @return DataQuery
|
||||
* @return $this
|
||||
*/
|
||||
public function where($filter) {
|
||||
if($filter) {
|
||||
@ -562,7 +589,7 @@ class DataQuery {
|
||||
*
|
||||
* @param string|array|SQLConditionGroup $filter Predicate(s) to set, as escaped SQL statements or
|
||||
* paramaterised queries
|
||||
* @return DataQuery
|
||||
* @return $this
|
||||
*/
|
||||
public function whereAny($filter) {
|
||||
if($filter) {
|
||||
@ -576,10 +603,10 @@ class DataQuery {
|
||||
*
|
||||
* @see SQLQuery::orderby()
|
||||
*
|
||||
* @param String $sort Column to sort on (escaped SQL statement)
|
||||
* @param String $direction Direction ("ASC" or "DESC", escaped SQL statement)
|
||||
* @param Boolean $clear Clear existing values
|
||||
* @return DataQuery
|
||||
* @param string $sort Column to sort on (escaped SQL statement)
|
||||
* @param string $direction Direction ("ASC" or "DESC", escaped SQL statement)
|
||||
* @param boolean $clear Clear existing values
|
||||
* @return $this
|
||||
*/
|
||||
public function sort($sort = null, $direction = null, $clear = true) {
|
||||
if($clear) {
|
||||
@ -594,7 +621,7 @@ class DataQuery {
|
||||
/**
|
||||
* Reverse order by clause
|
||||
*
|
||||
* @return DataQuery
|
||||
* @return $this
|
||||
*/
|
||||
public function reverseSort() {
|
||||
$this->query->reverseOrderBy();
|
||||
@ -616,7 +643,7 @@ class DataQuery {
|
||||
* Set whether this query should be distinct or not.
|
||||
*
|
||||
* @param bool $value
|
||||
* @return DataQuery
|
||||
* @return $this
|
||||
*/
|
||||
public function distinct($value) {
|
||||
$this->query->setDistinct($value);
|
||||
@ -626,13 +653,14 @@ class DataQuery {
|
||||
/**
|
||||
* Add an INNER JOIN clause to this query.
|
||||
*
|
||||
* @param String $table The unquoted table name to join to.
|
||||
* @param String $onClause The filter for the join (escaped SQL statement)
|
||||
* @param String $alias An optional alias name (unquoted)
|
||||
* @param string $table The unquoted table name to join to.
|
||||
* @param string $onClause The filter for the join (escaped SQL statement)
|
||||
* @param string $alias An optional alias name (unquoted)
|
||||
* @param int $order A numerical index to control the order that joins are added to the query; lower order values
|
||||
* will cause the query to appear first. The default is 20, and joins created automatically by the
|
||||
* ORM have a value of 10.
|
||||
* @param array $parameters Any additional parameters if the join is a parameterised subquery
|
||||
* @return $this
|
||||
*/
|
||||
public function innerJoin($table, $onClause, $alias = null, $order = 20, $parameters = array()) {
|
||||
if($table) {
|
||||
@ -651,6 +679,7 @@ class DataQuery {
|
||||
* will cause the query to appear first. The default is 20, and joins created automatically by the
|
||||
* ORM have a value of 10.
|
||||
* @param array $parameters Any additional parameters if the join is a parameterised subquery
|
||||
* @return $this
|
||||
*/
|
||||
public function leftJoin($table, $onClause, $alias = null, $order = 20, $parameters = array()) {
|
||||
if($table) {
|
||||
@ -664,8 +693,8 @@ class DataQuery {
|
||||
* mappings to the query object state. This has to be called
|
||||
* in any overloaded {@link SearchFilter->apply()} methods manually.
|
||||
*
|
||||
* @param String|array $relation The array/dot-syntax relation to follow
|
||||
* @return The model class of the related item
|
||||
* @param string|array $relation The array/dot-syntax relation to follow
|
||||
* @return string The model class of the related item
|
||||
*/
|
||||
public function applyRelation($relation) {
|
||||
// NO-OP
|
||||
@ -749,6 +778,7 @@ class DataQuery {
|
||||
*
|
||||
* @param DataQuery $subtractQuery
|
||||
* @param string $field
|
||||
* @return $this
|
||||
*/
|
||||
public function subtract(DataQuery $subtractQuery, $field='ID') {
|
||||
$fieldExpression = $subtractQuery->expressionForField($field);
|
||||
@ -765,8 +795,9 @@ class DataQuery {
|
||||
/**
|
||||
* Select only the given fields from the given table.
|
||||
*
|
||||
* @param String $table Unquoted table name (will be escaped automatically)
|
||||
* @param Array $fields Database column names (will be escaped automatically)
|
||||
* @param string $table Unquoted table name (will be escaped automatically)
|
||||
* @param array $fields Database column names (will be escaped automatically)
|
||||
* @return $this
|
||||
*/
|
||||
public function selectFromTable($table, $fields) {
|
||||
$fieldExpressions = array_map(function($item) use($table) {
|
||||
@ -781,8 +812,9 @@ class DataQuery {
|
||||
/**
|
||||
* Add the given fields from the given table to the select statement.
|
||||
*
|
||||
* @param String $table Unquoted table name (will be escaped automatically)
|
||||
* @param Array $fields Database column names (will be escaped automatically)
|
||||
* @param string $table Unquoted table name (will be escaped automatically)
|
||||
* @param array $fields Database column names (will be escaped automatically)
|
||||
* @return $this
|
||||
*/
|
||||
public function addSelectFromTable($table, $fields) {
|
||||
$fieldExpressions = array_map(function($item) use($table) {
|
||||
@ -812,9 +844,9 @@ class DataQuery {
|
||||
}
|
||||
|
||||
/**
|
||||
* @param String $field Select statement identifier, either the unquoted column name,
|
||||
* @param string $field Select statement identifier, either the unquoted column name,
|
||||
* the full composite SQL statement, or the alias set through {@link SQLQuery->selectField()}.
|
||||
* @return String The expression used to query this field via this DataQuery
|
||||
* @return string|null The expression used to query this field via this DataQuery
|
||||
*/
|
||||
protected function expressionForField($field) {
|
||||
|
||||
@ -835,8 +867,9 @@ class DataQuery {
|
||||
/**
|
||||
* Select the given field expressions.
|
||||
*
|
||||
* @param $fieldExpression String The field to select (escaped SQL statement)
|
||||
* @param $alias String The alias of that field (escaped SQL statement)
|
||||
* @param string $fieldExpression The field to select (escaped SQL statement)
|
||||
* @param string $alias The alias of that field (escaped SQL statement)
|
||||
*
|
||||
*/
|
||||
protected function selectField($fieldExpression, $alias = null) {
|
||||
$this->query->selectField($fieldExpression, $alias);
|
||||
@ -853,13 +886,21 @@ class DataQuery {
|
||||
/**
|
||||
* Set an arbitrary query parameter, that can be used by decorators to add additional meta-data to the query.
|
||||
* It's expected that the $key will be namespaced, e.g, 'Versioned.stage' instead of just 'stage'.
|
||||
*
|
||||
* @param string $key
|
||||
* @param mixed $value
|
||||
* @return $this
|
||||
*/
|
||||
public function setQueryParam($key, $value) {
|
||||
$this->queryParams[$key] = $value;
|
||||
return $this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set an arbitrary query parameter, that can be used by decorators to add additional meta-data to the query.
|
||||
*
|
||||
* @param string $key
|
||||
* @return mixed
|
||||
*/
|
||||
public function getQueryParam($key) {
|
||||
if(isset($this->queryParams[$key])) return $this->queryParams[$key];
|
||||
|
||||
Loading…
Reference in New Issue
Block a user