/**
* Add ORDER BY Clause(s)
*
* @param string|array $field
*
* <p>As string, field to lead the ordenation.</p>
*
* <p>
* As associative array, keys are the fields and values
* ordenation types
* </p>
*
* @param string|optional $type
*
* <p>Type of ordenation: ASC or DESC.</p>
*
* <p>
* If <strong>$field</strong> is an array, this value is not
* immediately used
* </p>
*
* @return Next\DB\Query\Builder
* Builder Instance (Fluent Interface)
*
* @throws Next\DB\Query\QueryException
* Ordenation field is empty or was considered an empty string
*/
public function order($field, $type = self::SQL_ORDER_ASC)
{
// Do we have multiple ORDER BY clause?
if (is_array($field)) {
if (is_array($type)) {
// Both arguments are arrays, let's equalize their lengths...
ArrayUtils::equalize($field, $type);
// ... and combine to make recursion easily
$field = array_combine($field, $type);
}
/**
* @internal
* Only first argument is array, so we expect it to be
* an associative pair/value as field to order => ordenation type
*/
foreach ($field as $f => $t) {
$this->order($f, $t);
}
} else {
// Ensuring we have a Field to lead the ordenation
$field = trim((string) $field);
if (empty($field)) {
throw QueryException::logic('Field to order results must be set as non-empty string');
}
// Ensuring we have a ordening direction (even optional for most RDBMS)
$type = trim((string) $type);
if (empty($type)) {
$type = self::SQL_ORDER_ASC;
}
/**
* @internal
* ORDER BY Clause cannot be "prepared", at least not as a question
* mark placeholder, because for some reason PDO::prepare() will
* try to wrap the values (field and ordenation type) into quotes,
* invalidating this specific part of SQL Statement
*/
self::$parts[self::SQL_ORDER_BY][$field] = $type;
}
return $this;
}
