PHP Class lithium\data\model\Query

Because of this, Query objects are the primary method of communication between Model classes and backend data sources. This helps to keep APIs abstract and flexible, since a model is only required to call a single method against its backend. Since the Query object simply acts as a structured data container, each backend can choose how to operate on the data the Query contains. See each class method for more details on what data this class supports.
See also: lithium\data\Model
See also: lithium\data\Source
Inheritance: extends lithium\core\Object
Show file Open project: unionofrad/lithium Class Usage Examples

Protected Properties

Property Type Description
$_alias array Count the number of identical models in a query for building unique aliases
$_autoConfig array Auto configuration properties.
$_built string Boolean indicate if the query is built or not
$_classes array Classes used by Query.
$_data array An array of data used in a write context. Only used if no binding object is present in the $_entity property.
$_entity object If a Query is bound to a Record or Document object (i.e. for a 'create' or 'update' query).
$_fields array The query's fields
$_initializers array Initialization methods on construct
$_map array Array containing mappings of relationship and field names, which allow database results to be mapped to the correct objects.
$_models array Map beetween generated aliases and corresponding models.
$_paths array Map beetween generated aliases and corresponding relation paths
$_schema object A query can be assigned its own custom schema object, using the schema() method. If this is not assigned, then the model associated with the query will be used to get the schema information.

Public Methods

Method Description
__call ( string $method, array $params = [] ) : mixed Gets or sets a custom query field which does not have an accessor method.
__construct ( array $config = [] ) : void Constructor, which initializes the default values this object supports. Even though only a specific list of configuration parameters is available by default, the Query object uses the __call() method to implement automatic getters and setters for any arbitrary piece of data.
alias ( mixed $alias = true, string $relpath = null ) : string Get or Set a unique alias for the query or a query's relation if $relpath is set.
applyStrategy ( Source $source ) Helper method used by export() which delegate the query generation to the data source.
calculate ( string $calculate = null ) : mixed Accessor method for Query calculate values.
childs ( string $relpath = null, string $query = null ) : mixed Get/set sub queries for the query.
comment ( string | null $comment = null ) : string | lithium\data\Query Set and get method for current query's comment.
conditions ( string | array | null $conditions = null ) : string | Query Set or append to existing conditions, or get current conditions.
data ( array $data = [] ) : array Set and get method for the query's record's data.
entity ( object &$entity = null ) : lithium\data\Query | Entity Set and get method for the query's entity instance.
export ( Source $source, array $options = [] ) : array Convert the query's properties to the data sources' syntax and return it as an array.
fields ( mixed $fields = null, boolean $overwrite = false ) : array Set, get or reset fields option for query.
group ( string | array | null $group = null ) : array | null | lithium\data\Query Set and get method for the Query group config setting.
having ( mixed $having = null ) : string | Query Set and get _having_.
joins ( string $name = null, object | string $join = null ) : mixed Set and get the joins
limit ( integer | boolean $limit = null ) : integer | null | Query Set or get the limit for the amount of results to return.
map ( array $map = null ) : array Generates a schema map of the query's result set, where the keys are aliases, and the values are arrays of field names.
model ( string | null $model = null ) : string | Query Set or get the associated model.
models ( Source $source = null ) : array Return the generated aliases mapped to their corresponding model
offset ( integer | null $offset = null ) : integer | lithium\data\Query Set and get method for query's offset, i.e. which records to get
order ( array | string | null $order = null ) : array | lithium\data\Query Set and get method for the query's order specification.
page ( integer | null $page = null ) : integer | lithium\data\Query Set and get method for page, in relation to limit, of which records to get
paths ( Source $source = null ) : array Return the generated aliases mapped to their relation path
relationships ( string $relpath = null, array $config = null ) : mixed Set and get the relationships.
respondsTo ( string $method, boolean $internal = false ) : boolean Determines if a given method can be called.
schema ( $field = null )

Protected Methods

Method Description
_entityConditions ( ) : array Will return a find first condition on the associated model if a record is connected.
_exportData ( ) : array Helper method used by export() to extract the data either from a bound entity, or from passed configuration, and filter it through a configured whitelist, if present.
_init ( )

Method Details

__call() public method

Gets or sets a custom query field which does not have an accessor method.
public __call ( string $method, array $params = [] ) : mixed
$method string Query part.
$params array Query parameters.
return mixed Returns the value as set in the `Query` object's constructor.

__construct() public method

This means that any information may be passed into the constructor may be used by the backend data source executing the query (or ignored, if support is not implemented). This is useful if, for example, you wish to extend a core data source and implement custom functionality.
public __construct ( array $config = [] ) : void
$config array Available configuration options are: - `'type'` _string_: The type of the query (`read`, `create`, `update`, `delete`). - `'mode'` _string_: `JOIN` mode for a join query. - `'entity'` _object_: The base entity to query on. If set `'model'` is optionnal. - `'model'` _string_: The base model to query on. - `'source'` _string_: The name of the table/collection. Unnecessary if `model` is set. - `'alias'` _string_: Alias for the source. Unnecessary if `model` is set. - `'schema'` _object_: A schema model. Unnecessary if `model` is set. - `'fields'` _array_: The fields to retreive. - `'conditions'` _array_: The conditions of the queries - `'having'` _array_: The having conditions of the queries - `'group'` _string_: The group by parameter. - `'order'` _string_: The order by parameter. - `'limit'` _string_: The limit parameter. - `'offset'` _string_: The offset of the `limit` options. - `'page'` _string_: Convenience parameter for setting the `offset`: `offset` = `page` * `limit`. - `'with'` _array_: Contain dependencies. Works only if `model` is set. - `'joins'` _array_: Contain manual join dependencies. - `'data'` _array_: Datas for update queries. - `'whitelist'` _array_: Allowed fields for updating queries. - `'calculate'` _string_: Alias name of the count. - `'comment'` _string_: Comment for the query. - `'map'` _object_: Unnecessary if `model` is set. - `'relationships'` _array_: Unnecessary if `model` is set.
return void

_entityConditions() protected method

Called by conditions when it is called as a get and no condition is set.
protected _entityConditions ( ) : array
return array Returns an array in the following format: `([model's primary key'] => [that key set in the record])`.

_exportData() protected method

Helper method used by export() to extract the data either from a bound entity, or from passed configuration, and filter it through a configured whitelist, if present.
protected _exportData ( ) : array
return array

_init() protected method

protected _init ( )

alias() public method

Get or Set a unique alias for the query or a query's relation if $relpath is set.
public alias ( mixed $alias = true, string $relpath = null ) : string
$alias mixed The value of the alias to set for the passed `$relpath`. For getting an alias value set alias to `true`.
$relpath string A dotted relation name or `null` for identifying the query's model.
return string An alias value or `null` for an unexisting `$relpath` alias.

applyStrategy() public method

Helper method used by export() which delegate the query generation to the data source.
public applyStrategy ( Source $source )
$source lithium\data\Source Instance of the data source to use for conversion.

calculate() public method

Accessor method for Query calculate values.
public calculate ( string $calculate = null ) : mixed
$calculate string Value for calculate config setting.
return mixed Current calculate config value.

childs() public method

The getter must be called after an export since the sub queries are built during the export according the export's mode option and the query with option.
See also: lithium\data\model\Query::export()
public childs ( string $relpath = null, string $query = null ) : mixed
$relpath string a dotted relation path
$query string a query instance
return mixed

comment() public method

Comment will have no effect on query, but will be passed along so data source can log it.
public comment ( string | null $comment = null ) : string | lithium\data\Query
$comment string | null
return string | lithium\data\Query

conditions() public method

When getting current conditions and none are configured for the query, will ask the bound entity for its conditions instead.
public conditions ( string | array | null $conditions = null ) : string | Query
$conditions string | array | null Condition/s to append to existing conditions. Provide `null` to get current conditions.
return string | Query Either the currrent conditions when $conditions is `null` or the query itself when setting the conditions.

data() public method

Set and get method for the query's record's data.
public data ( array $data = [] ) : array
$data array if set, will set given array.
return array Empty array if no data, array of data if the record has it.

entity() public method

Set and get method for the query's entity instance.
public entity ( object &$entity = null ) : lithium\data\Query | Entity
$entity object Reference to the query's current entity object.
return lithium\data\Query | lithium\data\Entity

export() public method

Convert the query's properties to the data sources' syntax and return it as an array.
public export ( Source $source, array $options = [] ) : array
$source lithium\data\Source Instance of the data source to use for conversion.
$options array Options to use when exporting the data.
return array Returns an array containing a data source-specific representation of a query.

fields() public method

Usage: to add a field $query->fields('created'); to add several fields $query->fields(array('title','body','modified')); to reset fields to none $query->fields(false); should be followed by a 2nd call to fields with required fields
public fields ( mixed $fields = null, boolean $overwrite = false ) : array
$fields mixed string, array or `false`
$overwrite boolean If `true`, existing fields will be removed before adding `$fields`.
return array Returns an array containing all fields added to the query.

group() public method

Set and get method for the Query group config setting.
public group ( string | array | null $group = null ) : array | null | lithium\data\Query
$group string | array | null
return array | null | lithium\data\Query

having() public method

Set and get _having_.
public having ( mixed $having = null ) : string | Query
$having mixed String or array to append to existing having.
return string | Query Either the currrent _having_ when $having is `null` or the query itself when setting _having_.

joins() public method

Set and get the joins
public joins ( string $name = null, object | string $join = null ) : mixed
$name string Optional name of join. Unless two parameters are passed, this parameter is regonized as `$join`.
$join object | string A single query object or an array of query objects
return mixed The joins array or a join array if `$name` is set. Returns `null` if a join doesn't exist.

limit() public method

Set or get the limit for the amount of results to return.
public limit ( integer | boolean $limit = null ) : integer | null | Query
$limit integer | boolean An integer indicating the number of results to limit or `false` to employ no limit at all. Or `null` to retrieve the current limit.
return integer | null | Query Either the currrent limit when $limit is `null` or the query itself when setting the limit or providing `false`.

map() public method

Generates a schema map of the query's result set, where the keys are aliases, and the values are arrays of field names.
public map ( array $map = null ) : array
$map array
return array

model() public method

Will also set the source table, i.e. $this->_config['source'] when setting the model.
public model ( string | null $model = null ) : string | Query
$model string | null Name of model to use, or `null` to retrieve current one.
return string | Query Either the current model name in use when $model is `null`, or the query itself when setting the model name.

models() public method

Return the generated aliases mapped to their corresponding model
public models ( Source $source = null ) : array
$source lithium\data\Source Instance of the data source to use for conversion.
return array Map between aliases and their corresponding fully-namespaced model names.

offset() public method

Set and get method for query's offset, i.e. which records to get
public offset ( integer | null $offset = null ) : integer | lithium\data\Query
$offset integer | null
return integer | lithium\data\Query

order() public method

Set and get method for the query's order specification.
public order ( array | string | null $order = null ) : array | lithium\data\Query
$order array | string | null
return array | lithium\data\Query

page() public method

Set and get method for page, in relation to limit, of which records to get
public page ( integer | null $page = null ) : integer | lithium\data\Query
$page integer | null
return integer | lithium\data\Query

paths() public method

Return the generated aliases mapped to their relation path
public paths ( Source $source = null ) : array
$source lithium\data\Source Instance of the data source to use for conversion.
return array Map between aliases and their corresponding dotted relation paths.

relationships() public method

Set and get the relationships.
public relationships ( string $relpath = null, array $config = null ) : mixed
$relpath string A dotted path.
$config array the config array to set.
return mixed The relationships array or a relationship array if `$relpath` is set. Returns `null` if a join doesn't exist.

respondsTo() public method

Determines if a given method can be called.
public respondsTo ( string $method, boolean $internal = false ) : boolean
$method string Name of the method.
$internal boolean Provide `true` to perform check from inside the class/object. When `false` checks also for public visibility; defaults to `false`.
return boolean Returns `true` if the method can be called, `false` otherwise.

schema() public method

public schema ( $field = null )

Property Details

$_alias protected property

Count the number of identical models in a query for building unique aliases
See also: lithium\data\model\Query::alias()
protected array $_alias
return array

$_autoConfig protected property

Auto configuration properties.
protected array $_autoConfig
return array

$_built protected property

Boolean indicate if the query is built or not
protected string $_built
return string

$_classes protected property

Classes used by Query.
protected array $_classes
return array

$_data protected property

An array of data used in a write context. Only used if no binding object is present in the $_entity property.
protected array $_data
return array

$_entity protected property

If a Query is bound to a Record or Document object (i.e. for a 'create' or 'update' query).
protected object $_entity
return object

$_fields protected property

The query's fields
See also: lithium\data\model\Query::fields()
protected array $_fields
return array

$_initializers protected property

Initialization methods on construct
protected array $_initializers
return array

$_map protected property

Array containing mappings of relationship and field names, which allow database results to be mapped to the correct objects.
protected array $_map
return array

$_models protected property

Map beetween generated aliases and corresponding models.
See also: lithium\data\model\Query::alias()
protected array $_models
return array

$_paths protected property

Map beetween generated aliases and corresponding relation paths
See also: lithium\data\model\Query::alias()
protected array $_paths
return array

$_schema protected property

A query can be assigned its own custom schema object, using the schema() method. If this is not assigned, then the model associated with the query will be used to get the schema information.
protected object $_schema
return object