Trait luya\admin\storage\QueryTrait

Implemented byluya\admin\file\Query, luya\admin\folder\Query, luya\admin\image\Query
Available since version1.0.0

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 ( )

                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.

                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

                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.

                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.

                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.

                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

                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.

                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.

                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

                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.

                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 ( )

                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.

                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

                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;
}