Queries

Queries are a unified way to access different kinds of information of the Sunhill Framework. The query system is intended to be similar to database queries of laravel. The main difference is, that its possible to query entities that are not stored in a database.

General usage

All queries have to define some standardized methods. These are described in general in the following. For details see the different types of queries.

Common query functions

As in QueryBuilder it is possible to build chains of request elements (like ->where('this','=','that')->orderBy('something')->offset(2)->limit(2)).

Terminology

Due the fact that queries could be performed on many entities there are some terms that are used:

• record is a single entity (like a database entry, a tag, a class, a plugin, etc.)
• records are all entities (or at least those that fit a certain criteria)

Finalizing calls

All queries need a finalizing call, that indicates what information should be retrieved or what action should be performed.

count()

Count returns the number of records of the given query.

Example:

SampleEntity::query()->count();

returns the number of all records of SampleEntity.

Example:

SampleEntity::query()->where('name','test')->count();

returns the number of SampleEntity Records that have the name 'test'

first()

Returns the first record of the given query.

Warning: When there is no order() statement, the result could be unpredictable.

If the given query return no records at all an exception is raised.

Example:

SampleEntity::query()->first();

Returns the first record of SampleEntity.

SampleEntity::query()->where('name','test')->first();

Returns the first record of SampleEntity where the name is 'test';

SampleEntity::query()->where('name','not existing')->first();

Throws an exception when no record has the name 'non existing'.

Column list

There is an optional parameter $fields to first() that could either take a single string or an array of strings. If $fields is a string only the result of that field is returned.

Example:

SampleEntity::query()->first('id');

Returns for example 1

If $fields is an array of strings a Collection object is returned where the elements represent the given fields.

Example:

SampleEntity::query()->first(['id','name']);

Returns [1, 'test']

List of Queries

• ORM Query
• Classes Query
• Tags Query
• Attributes Query
• Properties Query

Writing own queries

First check if you could use one of the predefined queries:

• ArrayQuery
• DatabaseQuery

If not, your own queries have to be derrived from BasicQuery and some abstract methods have to be overwritten:

assembleQuery()

This method takes no parameters and builds an internal query structure that could be used to perform the finalizing methods on. The method can return whatever you want you just have to make sure that the remaining abstract methods can use this result to return the desired value or action.

doGetCount($assembled_query)

This function takes the result of the previous function assembleQuery() and uses it to count the number of records that match the given criteria.