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'
A general note on first() and get()
Return type
first() and get() return the entity or a list of entities respectively. Normally a single entity is a StdClass with the givel columns as elements. In some cases it is useful to retun a different object.
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 StdClass object is returned where the elements represent the given fields.
Example:
SampleEntity::query()->first(['id','name']);
Returns {id: 1, 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'.
List of Queries
Writing own queries
First check if you could use one of the predefined queries:
If not, your own queries have to be derrived from BasicQuery and some abstract methods have to be overwritten:
Methods
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.
doGet($assembled_query, $fields)
This function returns (depending on fields) all records or only certain fields that result of the $assmbled_query. Note: All elements of the Collection are automatically passed through the getRecord() method to return the standardized result, so you mustn't call getRecord() in the method doGet().
fieldExists(string $field): bool
Returns if the given $field exists as a field or a pseudo field.
fieldOrderable(string $field): bool
Returns if the given $field is usable as a sorting key in orderBy().
getRecord($record)
This method does not have to necessarily be overwritten. By default it just return $record. In some cases it is necessary to return another type (e.g. Object).
