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)

Building a query

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(), firstIfExists(), only() 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(?string|?array $column_list = null)

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'.

firstIfExists(?string|?array $column_list = null)

Returns the first record of the given query or null if none exists.

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

If the given query return no records at all null is returned.

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

Null is returned.

get(?string|?array $column_list = null)

Returns all entities that match the given condition.

only(?string|?array $column_list = null)

The query must return exactly one result and this result is returned. Same as first() except that it raises an exception when no or more than one result is returned.

Example:

SampleEntity()::where('id','=',1)->only();

Returns the entity with the id 1 (or raises an exception when this id does not exist.

delete()

Deletes all entries that match the given condition or throws an exception if the entity is read only.

Example:

SampleEntity()::where('id','=',1)->delete();

Deletes the entity with the id 1.

Note: If no entity matches the given condition nothing is done an no exception is raised

update(array $fields)

Updates all entries that match the given condition or throws an exception if the entity is read only.

Example:

SampleEntity()::where('id','=',1)->update(['payload'=>'abc']);

Sets the field payload to "abc" on the entity with the id 1 .

Note: If no entity matches the given condition nothing is done an no exception is raised

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:

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