CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.0 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.0
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Console
    • Controller
    • Core
    • Database
      • Dialect
      • Driver
      • Exception
      • Expression
      • Log
      • Schema
      • Statement
      • Type
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • I18n
    • Log
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

Class OrderByExpression

An expression object for ORDER BY clauses

Namespace: Cake\Database\Expression

Property Summary

  • $_conditions protected
    array

    A list of strings or other expression objects that represent the "branches" of the expression tree. For example one key of the array might look like "sum > :value"

  • $_conjunction protected
    string

    String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.

  • $_typeMap protected
    Cake\Database\TypeMap

Method Summary

  • __call() public

    Helps calling the and() and or() methods transparently.

  • __construct() public

    Constructor

  • _addConditions() protected

    Auxiliary function used for decomposing a nested array of conditions and building a tree structure inside this object to represent the full SQL expression.

  • _bindMultiplePlaceholders() protected

    Returns an array of placeholders that will have a bound value corresponding to each value in the first argument.

  • _parseCondition() protected

    Parses a string conditions by trying to extract the operator inside it if any and finally returning either an adequate QueryExpression object or a plain string representation of the condition. This function is responsible for generating the placeholders and replacing the values by them, while storing the value elsewhere for future binding.

  • add() public

    Adds one or more conditions to this expression object. Conditions can be expressed in a one dimensional array, that will cause all conditions to be added directly at this level of the tree or they can be nested arbitrarily making it create more expression objects that will be nested inside and configured to use the specified conjunction.

  • addCase() public

    Adds a new case expression to the expression object

  • and_() public

    Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"

  • between() public

    Adds a new condition to the expression object in the form "field BETWEEN from AND to".

  • count() public

    Returns the number of internal conditions that are stored in this expression. Useful to determine if this expression object is void or it will generate a non-empty string when compiled

  • defaultTypes() public

    Allows setting default types when chaining query

  • eq() public

    Adds a new condition to the expression object in the form "field = value".

  • gt() public

    Adds a new condition to the expression object in the form "field > value".

  • gte() public

    Adds a new condition to the expression object in the form "field >= value".

  • in() public

    Adds a new condition to the expression object in the form "field IN (value1, value2)".

  • isCallable() public

    Check whether or not a callable is acceptable.

  • isNotNull() public

    Adds a new condition to the expression object in the form "field IS NOT NULL".

  • isNull() public

    Adds a new condition to the expression object in the form "field IS NULL".

  • iterateParts() public

    Executes a callable function for each of the parts that form this expression.

  • like() public

    Adds a new condition to the expression object in the form "field LIKE value".

  • lt() public

    Adds a new condition to the expression object in the form "field < value".

  • lte() public

    Adds a new condition to the expression object in the form "field <= value".

  • not() public

    Adds a new set of conditions to this level of the tree and negates the final result by prepending a NOT, it will look like "NOT ( (condition1) AND (conditions2) )" conjunction depends on the one currently configured for this object.

  • notEq() public

    Adds a new condition to the expression object in the form "field != value".

  • notIn() public

    Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".

  • notLike() public

    Adds a new condition to the expression object in the form "field NOT LIKE value".

  • or_() public

    Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"

  • sql() public

    Convert the expression into a SQL fragment.

  • traverse() public

    Traverses the tree structure of this query expression by executing a callback function for each of the conditions that are included in this object. Useful for compiling the final expression, or doing introspection in the structure.

  • type() public

    Changes the conjunction for the conditions at this level of the expression tree. If called with no arguments it will return the currently configured value.

  • typeMap() public

    Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.

Method Detail

__call() ¶ public

__call(string $method, array $args): Cake\Database\Expression\QueryExpression

Helps calling the and() and or() methods transparently.

Parameters
string $method

The method name.

array $args

The arguments to pass to the method.

Returns
Cake\Database\Expression\QueryExpression
Throws
BadMethodCallException

__construct() ¶ public

__construct(string|array|QueryExpression $conditions = [], array|Cake\Database\TypeMap $types = [], string $conjunction = '')

Constructor

Parameters
string|array|QueryExpression $conditions optional

The sort columns

array|Cake\Database\TypeMap $types optional

The types for each column.

string $conjunction optional

The glue used to join conditions together.

_addConditions() ¶ protected

_addConditions(array $orders, array $types): void

Auxiliary function used for decomposing a nested array of conditions and building a tree structure inside this object to represent the full SQL expression.

New order by expressions are merged to existing ones

Parameters
array $orders

list of order by expressions

array $types

list of types associated on fields referenced in $conditions

Returns
void

_bindMultiplePlaceholders() ¶ protected

_bindMultiplePlaceholders(string $field, array $values, string $type): array

Returns an array of placeholders that will have a bound value corresponding to each value in the first argument.

Parameters
string $field

Database field to be used to bind values

array $values

The values to bind

string $type

the type to be used to bind the values

Returns
array

_parseCondition() ¶ protected

_parseCondition(string $field, mixed $value): string|Cake\Database\ExpressionInterface

Parses a string conditions by trying to extract the operator inside it if any and finally returning either an adequate QueryExpression object or a plain string representation of the condition. This function is responsible for generating the placeholders and replacing the values by them, while storing the value elsewhere for future binding.

Parameters
string $field

The value from with the actual field and operator will be extracted.

mixed $value

The value to be bound to a placeholder for the field

Returns
string|Cake\Database\ExpressionInterface

add() ¶ public

add(string|array|QueryExpression $conditions, array $types = []): $this

Adds one or more conditions to this expression object. Conditions can be expressed in a one dimensional array, that will cause all conditions to be added directly at this level of the tree or they can be nested arbitrarily making it create more expression objects that will be nested inside and configured to use the specified conjunction.

If the type passed for any of the fields is expressed "type[]" (note braces) then it will cause the placeholder to be re-written dynamically so if the value is an array, it will create as many placeholders as values are in it.

Parameters
string|array|QueryExpression $conditions

single or multiple conditions to be added. When using an array and the key is 'OR' or 'AND' a new expression object will be created with that conjunction and internal array value passed as conditions.

array $types optional

associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns
$this
See Also
\Cake\Database\Query::where() for examples on conditions

addCase() ¶ public

addCase(array|ExpressionInterface $conditions, array|ExpressionInterface $values = [], array $types = []): $this

Adds a new case expression to the expression object

Parameters
array|ExpressionInterface $conditions

The conditions to test. Must be a ExpressionInterface instance, or an array of ExpressionInterface instances.

array|ExpressionInterface $values optional

associative array of values to be associated with the conditions passed in $conditions. If there are more $values than $conditions, the last $value is used as the ELSE value

array $types optional

associative array of types to be associated with the values passed in $values

Returns
$this

and_() ¶ public

and_(string|array|QueryExpression $conditions, array $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"

Parameters
string|array|QueryExpression $conditions

to be joined with AND

array $types optional

associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns
Cake\Database\Expression\QueryExpression

between() ¶ public

between(mixed $field, mixed $from, mixed $to, string $type = null): $this

Adds a new condition to the expression object in the form "field BETWEEN from AND to".

Parameters
mixed $field

The field name to compare for values in between the range.

mixed $from

The initial value of the range.

mixed $to

The ending value in the comparison range.

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

count() ¶ public

count(): int

Returns the number of internal conditions that are stored in this expression. Useful to determine if this expression object is void or it will generate a non-empty string when compiled

Returns
int

defaultTypes() ¶ public

defaultTypes(array $types = null): $this|array

Allows setting default types when chaining query

Parameters
array $types optional

The array of types to set.

Returns
$this|array

eq() ¶ public

eq(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field = value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map. If it is suffixed with "[]" and the value is an array then multiple placeholders will be created, one per each value in the array.

Returns
$this

gt() ¶ public

gt(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field > value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

gte() ¶ public

gte(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field >= value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

in() ¶ public

in(string $field, string|array $values, string $type = null): $this

Adds a new condition to the expression object in the form "field IN (value1, value2)".

Parameters
string $field

Database field to be compared against value

string|array $values

the value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

isCallable() ¶ public

isCallable(callable $c): bool

Check whether or not a callable is acceptable.

We don't accept ['class', 'method'] style callbacks, as they often contain user input and arrays of strings are easy to sneak in.

Parameters
callable $c

The callable to check.

Returns
bool

isNotNull() ¶ public

isNotNull(string|Cake\Database\ExpressionInterface $field): $this

Adds a new condition to the expression object in the form "field IS NOT NULL".

Parameters
string|Cake\Database\ExpressionInterface $field

database field to be tested for not null

Returns
$this

isNull() ¶ public

isNull(string|Cake\Database\ExpressionInterface $field): $this

Adds a new condition to the expression object in the form "field IS NULL".

Parameters
string|Cake\Database\ExpressionInterface $field

database field to be tested for null

Returns
$this

iterateParts() ¶ public

iterateParts(callable $callable): $this

Executes a callable function for each of the parts that form this expression.

The callable function is required to return a value with which the currently visited part will be replaced. If the callable function returns null then the part will be discarded completely from this expression.

The callback function will receive each of the conditions as first param and the key as second param. It is possible to declare the second parameter as passed by reference, this will enable you to change the key under which the modified part is stored.

Parameters
callable $callable

The callable to apply to each part.

Returns
$this

like() ¶ public

like(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field LIKE value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

lt() ¶ public

lt(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field < value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

lte() ¶ public

lte(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field <= value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

not() ¶ public

not(string|array|QueryExpression $conditions, array $types = []): $this

Adds a new set of conditions to this level of the tree and negates the final result by prepending a NOT, it will look like "NOT ( (condition1) AND (conditions2) )" conjunction depends on the one currently configured for this object.

Parameters
string|array|QueryExpression $conditions

to be added and negated

array $types optional

associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns
$this

notEq() ¶ public

notEq(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field != value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map. If it is suffixed with "[]" and the value is an array then multiple placeholders will be created, one per each value in the array.

Returns
$this

notIn() ¶ public

notIn(string $field, array $values, string $type = null): $this

Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".

Parameters
string $field

Database field to be compared against value

array $values

the value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

notLike() ¶ public

notLike(string $field, mixed $value, string $type = null): $this

Adds a new condition to the expression object in the form "field NOT LIKE value".

Parameters
string $field

Database field to be compared against value

mixed $value

The value to be bound to $field for comparison

string $type optional

the type name for $value as configured using the Type map.

Returns
$this

or_() ¶ public

or_(string|array|QueryExpression $conditions, array $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"

Parameters
string|array|QueryExpression $conditions

to be joined with OR

array $types optional

associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns
Cake\Database\Expression\QueryExpression

sql() ¶ public

sql(Cake\Database\ValueBinder $generator): string

Convert the expression into a SQL fragment.

Parameters
Cake\Database\ValueBinder $generator

Placeholder generator object

Returns
string

traverse() ¶ public

traverse(callable $callable): void

Traverses the tree structure of this query expression by executing a callback function for each of the conditions that are included in this object. Useful for compiling the final expression, or doing introspection in the structure.

Callback function receives as only argument an instance of a QueryExpression

Parameters
callable $callable

The callable to apply to all sub-expressions.

Returns
void

type() ¶ public

type(string $conjunction = null): string|$this

Changes the conjunction for the conditions at this level of the expression tree. If called with no arguments it will return the currently configured value.

Parameters
string $conjunction optional

value to be used for joining conditions. If null it will not set any value, but return the currently stored one

Returns
string|$this

typeMap() ¶ public

typeMap(array|TypeMap $typeMap = null): $this|TypeMap

Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.

Parameters
array|TypeMap $typeMap optional

Creates a TypeMap if array, otherwise sets the given TypeMap

Returns
$this|TypeMap

Property Detail

$_conditions ¶ protected

A list of strings or other expression objects that represent the "branches" of the expression tree. For example one key of the array might look like "sum > :value"

Type
array

$_conjunction ¶ protected

String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.

Type
string

$_typeMap ¶ protected

Type
Cake\Database\TypeMap
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs