Trait luya\admin\storage\QueryTrait

All Classes | Methods

Implemented by	luya\admin\file\Query, luya\admin\folder\Query, luya\admin\image\Query
Available since version	1.0.0
Source Code	https://github.com/luyadev/luya-module-admin/blob/master/src/storage/QueryTrait.php

Query Data from Files, Filters and Images.

Usage examples which is valid for all classes implementing the QueryTrait.

The below examples are wrote for file query but are are working for all classes implementing the QueryTrait like:

Files: {{\luya\admin\file\Query}}
Images: {{\luya\admin\image\Query}}
Folders: {{\luya\admin\folder\Query}}

All vs. One ¶

return (new \luya\admin\file\Query())->where($args)->one();

return (new \luya\admin\file\Query())->findOne($fileId);

return (new \luya\admin\file\Query())->where($args)->all();

Counting ¶

return (new \luya\admin\file\Query())->where($args)->count();

Customized where condition ¶

All QueryTrait classes can use different where notations:

return (new \luya\admin\file\Query())->where(['>', 'id', 1])->andWHere(['<', 'id', 3])->all();

In condition in order to get mutiple columns of a file.

return (new \luya\admin\file\Query())->where(['in', 'id', [1, 3]])->all();

Offsets and Limits ¶

return (new \luya\admin\file\Query())->where($args)->offset(5)->limit(10)->all();

See the {{\luya\admin\storage\QueryTrait::where()}} for more details.

Public Methods

Hide inherited methods

Method	Description	Defined By
all()	Find all elementes based on the where filter.	luya\admin\storage\QueryTrait
andWhere()	Add another where statement to the existing, this is the case when using compare operators, as then only one where definition can bet set.	luya\admin\storage\QueryTrait
bind()	Bind given values into the objects for a given id.	luya\admin\storage\QueryTrait
count()	Get the count of items	luya\admin\storage\QueryTrait
createItem()	Create an item object which implements {{\luya\admin\storage\ItemTrait}}.	luya\admin\storage\QueryTrait
createIteratorObject()	Create the iterator object which extends from {{\luya\admin\storage\IteratorAbstract}}.	luya\admin\storage\QueryTrait
findOne()	FindOne with the specific ID.	luya\admin\storage\QueryTrait
getDataProvider()	Return an array with all item values provided for this query method.	luya\admin\storage\QueryTrait
getItemDataProvider()	Return the a single item by its key. If not found, false must be returned.	luya\admin\storage\QueryTrait
limit()	Set a limition for the amount of results.	luya\admin\storage\QueryTrait
offset()	Define offset start for the rows, if you defined offset to be 5 and you have 11 rows, the first 5 rows will be skiped. This is commonly used to make pagination function in combination with the limit() function.	luya\admin\storage\QueryTrait
one()	Find One based on the where condition.	luya\admin\storage\QueryTrait
orderBy()	Order the query by one or multiple fields asc or desc.	luya\admin\storage\QueryTrait
where()	Query where similar behavior of filtering items.	luya\admin\storage\QueryTrait

Method Details

Hide inherited methods

all() public method

Find all elementes based on the where filter.

public luya\admin\storage\IteratorAbstract all ( )

Source code

                public function all()
{
    return $this->createIteratorObject($this->filter());
}

andWhere() public method

Add another where statement to the existing, this is the case when using compare operators, as then only one where definition can bet set.

See {{luya\admin\storage\QueryTrait::where()}}

public luya\admin\storage\QueryTrait andWhere ( array $args )
$args	array	The where definition can be either an key-value pairing or a condition representen as array.

Source code

                public function andWhere(array $args)
{
    return $this->where($args);
}

bind() public method (available since version 1.1.1)

Bind given values into the objects for a given id.

(new Query())->find()->where(['in', 'id', [1,2,3])->bind([1 => ['caption' => 'barfoo'])->all();

public luya\admin\storage\QueryTrait bind ( array $values )
$values	array

Source code

                public function bind(array $values)
{
    if (!empty($values)) {
        $this->_binds = $values;
    }
    return $this;
}

count() public method

Get the count of items

public integer count ( )
return	integer	Amount of filtere data.

Source code

                public function count()
{
    return count($this->filter());
}

createItem() public abstract method

Create an item object which implements {{\luya\admin\storage\ItemTrait}}.

public abstract luya\admin\storage\ItemAbstract createItem ( array $itemArray )
$itemArray	array
return	luya\admin\storage\ItemAbstract	The item object implementing the ItemTrait.

Source code

                abstract public function createItem(array $itemArray);

createIteratorObject() public abstract method

Create the iterator object which extends from {{\luya\admin\storage\IteratorAbstract}}.

public abstract luya\admin\storage\IteratorAbstract createIteratorObject ( array $data )
$data	array	The data to pass to the Iterator.
return	luya\admin\storage\IteratorAbstract	An iterator object extends from IteratorAbstract class.

Source code

                abstract public function createIteratorObject(array $data);

findOne() public method

FindOne with the specific ID.

public luya\admin\image\Item\|luya\admin\file\Item\|luya\admin\folder\Item findOne ( $id )
$id	integer	The specific item id

Source code

                public function findOne($id)
{
    return ($itemArray = $this->getItemDataProvider($id)) ? $this->createItem($itemArray) : false;
}

getDataProvider() public abstract method

Return an array with all item values provided for this query method.

public abstract array getDataProvider ( )
return	array	The array with all values for this query index by its key.

Source code

                abstract public function getDataProvider();

getItemDataProvider() public abstract method

Return the a single item by its key. If not found, false must be returned.

public abstract array\|boolean getItemDataProvider ( $id )
$id	integer	The requested key identifier.
return	array\|boolean	Returns the item array or false if not found.

Source code

                abstract public function getItemDataProvider($id);

limit() public method

Set a limition for the amount of results.

public luya\admin\storage\QueryTrait limit ( $count )
$count	integer	The number of rows to return

Source code

                public function limit($count)
{
    if (is_numeric($count)) {
        $this->_limit = $count;
    }
    return $this;
}

offset() public method

Define offset start for the rows, if you defined offset to be 5 and you have 11 rows, the first 5 rows will be skiped. This is commonly used to make pagination function in combination with the limit() function.

public luya\admin\storage\QueryTrait offset ( $offset )
$offset	integer	Defines the amount of offset start position.

Source code

                public function offset($offset)
{
    if (is_numeric($offset)) {
        $this->_offset = $offset;
    }
    return $this;
}

one() public method

Find One based on the where condition.

If there are several items, it just takes the first one and does not throw an exception.

public luya\admin\image\Item\|luya\admin\file\Item\|luya\admin\folder\Item one ( )

Source code

                public function one()
{
    $data = $this->filter();
    return (count($data) !== 0) ? $this->createItem(array_values($data)[0]) : false;
}

orderBy() public method (available since version 4.0.0)

Order the query by one or multiple fields asc or desc.

Use following PHP constants for directions:

SORT_ASC: 1..10, A..Z
SORT_DESC: 10..1, Z..A

Example using orderBy:

$query = new Query()->orderBy(['id => SORT_ASC])->all();

In rare cases you like to sort for certain existing order structure, for example when an explicit order is given from an user input, then you can provide an array of that value. The limitation for this order behavior is that only elements in the list will be taken, other elements will be removed from the result array. This means if an id is not present in that array of orderding by id, this will be removed.

Example usage:

(new Query())->where(['in', 'id', [1,2,3]])->orderBy(['id' => [3,2,1]])->all();

The above example will return those elements in the order of 3,2,1.

Example usage which will remove elements:

(new Query())->where(['in', 'id', [1,2,3]])->orderBy(['id' => [2,1]])->all();

The above example will return only the order elements 2,1 and element with id 3 is gone

public luya\admin\storage\QueryTrait orderBy ( array $order )
$order	array	An array with fields to sort where key is the field and value the direction.

Source code

                public function orderBy(array $order)
{
    $orderBy = ['keys' => [], 'directions' => [], 'ids' => []];
    foreach ($order as $key => $direction) {
        $orderBy['keys'][] = $key;
        $orderBy['directions'][] = $direction;
        if (is_array($direction)) {
            $orderBy['ids'] = $direction;
        }
    }
    $this->_order = $orderBy;
    return $this;
}

where() public method

Query where similar behavior of filtering items.

Operator Filtering:

where(['operator', 'field', 'value']);

Available Operators:

< expression where field is smaller then value.
> expression where field is bigger then value.
= expression where field is equal value.
<= expression where field is small or equal then value.
>= expression where field is bigger or equal then value.
== expression where field is equal to the value and even the type must be equal.
in expression where an value array can be passed to get all values from this field type e.g. ['in', 'id', [1,3,4]].

Only one operator speific argument can be provided, to chain another expression use the andWhere() method.

Multi Dimension Filtering:

The most common case for filtering items is the equal expression combined with add statements.

For example the following expression

where(['=', 'id', 0])->andWhere(['=', 'name', 'footer']);

is equal to the short form multi deimnsion filtering expression

where(['id' => 0, 'name' => 'footer']);

Its not possibile to make where conditions on the same column:

where(['>', 'id', 1])->andWHere(['<', 'id', 3]);

This will only appaend the first condition where id is bigger then 1 and ignore the second one

public luya\admin\storage\QueryTrait where ( array $args )
$args	array	The where definition can be either an key-value pairing or a condition representen as array.
throws	luya\Exception

Source code

                public function where(array $args)
{
    foreach ($args as $key => $value) {
        if (in_array($value, $this->_whereOperators, true)) {
            if (count($args) !== 3) {
                throw new Exception("Wrong where condition. Condition needs an operator and two operands.");
            }
            $this->_where[] = ['op' => $args[0], 'field' => $args[1], 'value' => $args[2]];
            break;
        } else {
            $this->_where[] = ['op' => '=', 'field' => $key, 'value' => $value];
        }
    }
    return $this;
}