QueryBuilder

Om SQL-queries makkelijker te maken heeft de WebCie haar eigen sql-library geschreven, de QueryBuilder. De QueryBuilder maakt queries op dmv van een QueryBuilder-object waaraan properties veranderd worden. Op die manier wordt de query pas gebouwd als de query uitgevoerd moet worden. Hierdoor is er meer mogelijkheid voor controle en sanity checks.

De QueryBuilder bestaat uit de Query-klasse, de QueryBuilder-klasse en alle uitbreidingen. De Query-klasse is een extensie van de QueryBuilder-klasse. Het verschil tussen de twee klasses is dat de QueryBuilder-klasse wordt gebruikt om de query op te bouwen en de Query-klasse wordt gebruikt om van het geheel een werkende query te maken, alsmede verschillende functies zoals het verzamelen van objecten te implementeren.

QueryBuilder starten

Omdat je een query altijd wilt gebruiken voor WhosWho4-objecten heeft elk WhosWho4-object zijn eigen query-classe die een uitbreiding is van de Query-klasse. Zo heb je bv de PersoonQuery-klasse en de LidQuery-klasse. Deze extensies hebben niet hun eigen speciale constructor. in plaats daarvan heeft elk van deze klassen de methode table waarmee een Query-klasse wordt aangemaakt, het object als table bij de query wordt gezet en het ObjectQuery-object wordt gereturnd zodat er meteen methoden op kunnen worden toegepast. Voor uitgebreide klasse zoals Persoon en Lid worden automatisch de onderliggende klassen gejoind zodat je dit niet zelf hoeft te doen en bij deze data kan. Een voorbeeld:

1. $query = PersoonQuery::table();

Query uitvoeren

Een query kan je uitvoeren met de methode get. get heeft geen argumenten nodig. Als je verder niets aan je Query-object hebt toegevoegd selecteert de query automatisch alle objecten in de table. Met het volgende voorbeeld worden alle entries uit de Persoon-table opgevraagd:

1. $personen = PersoonQuery::table()->get();

first

De methode first voert de query uit zoals get dat doet en geeft vervolgens alleen het eerste resultaat terug. Met het volgende voorbeeld wordt de eerste entry uit de Persoon-table opgehaald:

1. $personen = PersoonQuery::table()->first();

aggregate (TODO: in de php-code moet deze functie nog worden aangepast)

De methode aggregate voert een aggregator uit op de query. De toegestane aggregators zijn: COUNT, SUM, MAX, MIN en YEAR. De aggregator pakt op dit moment nog alles ipv een specifieke kolom. aggregate haalt ook de huidige selectie weg. Een voorbeeld om alle entries in de Persoon-table te tellen:

1. $aantal_personen = PersoonQuery::table()->aggregate('COUNT');

count

Om makkelijker entries te tellen is de speciale methode count. Deze methode telt het aantal entries en haalt ook de orderBys, limits en offset van de query weg.

1. $aantal_personen = PersoonQuery::table()->count();

verzamel

De methode die het vaakst gebruikt wordt is verzamel. Net zoals verzamel van elke Verzameling van een WhosWho4-object verzamelt deze query-methode alle WhosWho4-objecten die met de query opgehaald worden. Hierbij verdwijnen alle huidige selects van de query. De methode kan twee argumenten krijgen: de naam van de klasse om de objecten van te verzamelen as string en of de objecten distinct moeten zijn als bool. Zonder argumenten is distinct true en worden de objecten opgehaald van de klasse waarvan je het query-object gemaakt hebt. Als voorbeeld, haal alle Persoon-objecten op:

1. $persoon_objecten = PersoonQuery::table()->verzamel();

Haal alle distinct bugmelders op (dit voorbeeld gebruikt ook join):

1. $persoon_objecten = BugQuery::table()

2.         ->join('Persoon')

3.         ->verzamel('Persoon', true);

geef

Net zoals de methode geef voor objecten heeft de QueryBuilder een soortgelijke methode. De methode geeft een object terug die wordt opgevraagd dmv de query. Net als bij verzamel heeft de methode een argument voor het soort object wat je op wilt halen. Geef het lid-object met ID 5794

1. $persoon = PersoonQuery::table()

2.         ->whereInt('contactID', 5794)

3.         ->geef();

Joins

De QueryBuilder heeft uiteraard ook de mogelijkheid om joins uit te voeren op tables. Nieuwe tabellen worden automatisch op de juiste velden gejoind, dus dit hoef je niet meer zelf te doen. Mocht de QueryBuilder het toch niet zelf kunnen, dan hebben de join-methoden extra argumenten nodig voor het joinen.

(left) join

De standaard join is een left join. Je hoeft als enige argument de table mee te geven om op te joinen. Zo kan je bv de table Persoon joinen met Bug

1. $query = BugQuery::table()->join('Persoon');

Als het echt nodig is kan je zelf de twee namen van de kolommen meegeven waarop gejoined moet worden

1. $query = BugQuery::table()->join('Persoon', 'Bug.melder_contactID', 'Persoon.contactID');

rightJoin

De rightJoin werkt hetzelfde als join alleen voert het een right join uit ipv een left join.

1. $query = BugQuery::table()->rightJoin('Persoon');

innerJoin

De innerJoin werkt ook hetzelfde als join alleen voert het een inner join uit ipv een left join.

1. $query = BugQuery::table()->innerJoin('Persoon');

fullJoin

De fullJoin werkt ook hetzelfde als join alleen voert het een full join uit ipv een left join.

1. $query = BugQuery::table()->fullJoin('Persoon');

Where

Uiteraard heeft een query ook where's nodig. Daarom heeft de QueryBuilder verschillende methoden om where toe te voegen.

whereProp

De belangrijkste where-methode is whereProp. Met deze methode wordt de where automatisch uitgevoerd op een eigenschap van de objecten waarvan de tables in de query zitten (met from of dmv een join). Hiervoor is het ook nodig dat waarmee je wilt matchen in je where van het juiste type is. Zo is een ID een int en wil je daar dus geen string voor meegeven. De whereProp zoekt ook automatisch de table waarbij de property hoort. Als er meerdere mogelijkheden zijn kan je er altijd 'tablename.' voor zetten, net zoals met normale sql.

Je kan whereProp twee of drie argumenten meegeven. Als je twee argumenten meegeeft wordt er een match op gelijkheid aan je query toegevoegd. Hierbij is het eerste argument welke property je wilt matchen en je tweede argument waarmee gematcht wordt. Selecteer alle Bugs met melder $melder ($melder moet een Persoonobject zijn)

1. $query = BugQuery::table()->whereProp('melder', $melder);

Als je drie argumenten meegeeft is het eerste argument nog steeds welke property je wilt matchen, je tweede argument is je operator en je derde argument is waarmee gematcht wordt. Selecteer alle Bugs waarvan melder niet $melder is ($melder moet een Persoonobject zijn)

1. $query = BugQuery::table()->whereProp('melder', '!=', $melder);