Database Explorer

Z Explorerjem začnete s klicem metode table() objekta Nette\Database\Explorer (podrobnosti o povezavi najdete v poglavju Povezava in konfiguracija):

$books = $explorer->table('book'); // 'book' je ime tabele

Metoda vrača objekt Selection, ki predstavlja SQL poizvedbo. Na ta objekt lahko navezujemo nadaljnje metode za filtriranje in razvrščanje rezultatov. Poizvedba se sestavi in zažene šele v trenutku, ko začnemo zahtevati podatke. Na primer s prehajanjem skozi zanko foreach. Vsaka vrstica je predstavljena z objektom ActiveRow:

foreach ($books as $book) {
	echo $book->title;        // izpis stolpca 'title'
	echo $book->author_id;    // izpis stolpca 'author_id'
}

Explorer bistveno olajša delo s povezavami med tabelami. Naslednji primer prikazuje, kako enostavno lahko izpišemo podatke iz povezanih tabel (knjige in njihovi avtorji). Opazite, da nam ni treba pisati nobenih JOIN poizvedb, Nette jih ustvari za nas:

$books = $explorer->table('book');

foreach ($books as $book) {
	echo 'Knjiga: ' . $book->title;
	echo 'Avtor: ' . $book->author->name; // ustvari JOIN na tabelo 'author'
}

Nette Database Explorer optimizira poizvedbe, da so čim bolj učinkovite. Zgornji primer izvede samo dve SELECT poizvedbi, ne glede na to, ali obdelujemo 10 ali 10.000 knjig.

Poleg tega Explorer spremlja, kateri stolpci se v kodi uporabljajo, in nalaga iz podatkovne baze samo te, s čimer prihrani dodatno zmogljivost. To obnašanje je popolnoma samodejno in prilagodljivo. Če kasneje prilagodite kodo in začnete uporabljati druge stolpce, Explorer samodejno prilagodi poizvedbe. Ničesar vam ni treba nastavljati, niti razmišljati o tem, katere stolpce boste potrebovali – prepustite to Nette.

Filtriranje in razvrščanje

Razred Selection ponuja metode za filtriranje in razvrščanje izbora podatkov.

Metode lahko verižimo (t.i. fluent interface): $table->where(...)->order(...)->limit(...).

V teh metodah lahko uporabljate tudi posebno notacijo za dostop do podatkov iz povezanih tabel.

Ubežanje znakov in identifikatorji

Metode samodejno ubežijo parametre in navajajo identifikatorje (imena tabel in stolpcev), s čimer preprečujejo SQL injection. Za pravilno delovanje je treba upoštevati nekaj pravil:

• Ključne besede, imena funkcij, procedur ipd. pišite z velikimi črkami.
• Imena stolpcev in tabel pišite z malimi črkami.
• Nize vedno vstavljajte prek parametrov.

where('name = ' . $name);         // KRITIČNA RANLJIVOST: SQL injection
where('name LIKE "%search%"');    // NAPAKA: otežuje samodejno navajanje
where('name LIKE ?', '%search%'); // PRAVILNO: vrednost vstavljena prek parametra

where('name like ?', $name);     // NAPAKA: generira: `name` `like` ?
where('name LIKE ?', $name);     // PRAVILNO: generira: `name` LIKE ?
where('LOWER(name) = ?', $value);// PRAVILNO: LOWER(`name`) = ?

where (string|array $condition, …$parameters): static

Filtrira rezultate s pomočjo pogojev WHERE. Njena močna stran je inteligentno delo z različnimi tipi vrednosti in samodejna izbira SQL operatorjev.

Osnovna uporaba:

$table->where('id', $value);     // WHERE `id` = 123
$table->where('id > ?', $value); // WHERE `id` > 123
$table->where('id = ? OR name = ?', $id, $name); // WHERE `id` = 1 OR `name` = 'Jon Snow'

Zahvaljujoč samodejnemu zaznavanju ustreznih operatorjev nam ni treba reševati različnih posebnih primerov. Nette jih reši za nas:

$table->where('id', 1);          // WHERE `id` = 1
$table->where('id', null);       // WHERE `id` IS NULL
$table->where('id', [1, 2, 3]);  // WHERE `id` IN (1, 2, 3)
// lahko se uporabi tudi nadomestni vprašaj brez operatorja:
$table->where('id ?', 1);        // WHERE `id` = 1

Metoda pravilno obdela tudi negativne pogoje in prazno polje:

$table->where('id', []);         // WHERE `id` IS NULL AND FALSE -- ničesar ne najde
$table->where('id NOT', []);     // WHERE `id` IS NULL OR TRUE -- najde vse
$table->where('NOT (id ?)', []); // WHERE NOT (`id` IS NULL AND FALSE) -- najde vse
// $table->where('NOT id ?', $ids);  Pozor - ta sintaksa ni podprta

Kot parameter lahko posredujemo tudi rezultat iz druge tabele – ustvari se podpoizvedba:

// WHERE `id` IN (SELECT `id` FROM `tableName`)
$table->where('id', $explorer->table($tableName));

// WHERE `id` IN (SELECT `col` FROM `tableName`)
$table->where('id', $explorer->table($tableName)->select('col'));

Pogoje lahko posredujemo tudi kot polje, katerega elementi se združijo s pomočjo AND:

// WHERE (`price_final` < `price_original`) AND (`stock_count` > `min_stock`)
$table->where([
	'price_final < price_original',
	'stock_count > min_stock',
]);

V polju lahko uporabimo pare ključ ⇒ vrednost in Nette spet samodejno izbere pravilne operatorje:

// WHERE (`status` = 'active') AND (`id` IN (1, 2, 3))
$table->where([
	'status' => 'active',
	'id' => [1, 2, 3],
]);

V polju lahko kombiniramo SQL izraze z nadomestnimi vprašaji in več parametri. To je primerno za kompleksne pogoje z natančno določenimi operatorji:

// WHERE (`age` > 18) AND (ROUND(`score`, 2) > 75.5)
$table->where([
	'age > ?' => 18,
	'ROUND(score, ?) > ?' => [2, 75.5], // dva parametra posredujemo kot polje
]);

Večkratni klic where() pogoje samodejno združuje s pomočjo AND.

whereOr (array $parameters): static

Podobno kot where() dodaja pogoje, vendar s to razliko, da jih združuje s pomočjo OR:

// WHERE (`status` = 'active') OR (`deleted` = 1)
$table->whereOr([
	'status' => 'active',
	'deleted' => true,
]);

Tudi tukaj lahko uporabimo kompleksnejše izraze:

// WHERE (`price` > 1000) OR (`price_with_tax` > 1500)
$table->whereOr([
	'price > ?' => 1000,
	'price_with_tax > ?' => 1500,
]);

wherePrimary (mixed $key): static

Doda pogoj za primarni ključ tabele:

// WHERE `id` = 123
$table->wherePrimary(123);

// WHERE `id` IN (1, 2, 3)
$table->wherePrimary([1, 2, 3]);

Če ima tabela sestavljen primarni ključ (npr. foo_id, bar_id), ga posredujemo kot polje:

// WHERE `foo_id` = 1 AND `bar_id` = 5
$table->wherePrimary(['foo_id' => 1, 'bar_id' => 5])->fetch();

// WHERE (`foo_id`, `bar_id`) IN ((1, 5), (2, 3))
$table->wherePrimary([
	['foo_id' => 1, 'bar_id' => 5],
	['foo_id' => 2, 'bar_id' => 3],
])->fetchAll();

order (string $columns, …$parameters): static

Določa vrstni red, v katerem bodo vrnjene vrstice. Lahko razvrščamo po enem ali več stolpcih, v padajočem ali naraščajočem vrstnem redu, ali po lastnem izrazu:

$table->order('created');                   // ORDER BY `created`
$table->order('created DESC');              // ORDER BY `created` DESC
$table->order('priority DESC, created');    // ORDER BY `priority` DESC, `created`
$table->order('status = ? DESC', 'active'); // ORDER BY `status` = 'active' DESC

select (string $columns, …$parameters): static

Določa stolpce, ki naj se vrnejo iz podatkovne baze. V privzetem stanju Nette Database Explorer vrača samo tiste stolpce, ki se dejansko uporabijo v kodi. Metodo select() tako uporabljamo v primerih, ko moramo vrniti specifične izraze:

// SELECT *, DATE_FORMAT(`created_at`, "%d.%m.%Y") AS `formatted_date`
$table->select('*, DATE_FORMAT(created_at, ?) AS formatted_date', '%d.%m.%Y');

Aliasi, definirani s pomočjo AS, so nato dostopni kot lastnosti objekta ActiveRow:

foreach ($table as $row) {
	echo $row->formatted_date;   // dostop do aliasa
}

limit (?int $limit, ?int $offset = null): static

Omejuje število vrnjenih vrstic (LIMIT) in po želji omogoča nastavitev odmika (offset):

$table->limit(10);        // LIMIT 10 (vrne prvih 10 vrstic)
$table->limit(10, 20);    // LIMIT 10 OFFSET 20

Za stranskanje je primernejša uporaba metode page().

page (int $page, int $itemsPerPage, &$numOfPages = null): static

Olajša stranskanje rezultatov. Sprejme številko strani (šteto od 1) in število postavk na stran. Po želji lahko posredujemo referenco na spremenljivko, v katero se shrani skupno število strani:

$numOfPages = null;
$table->page(page: 3, itemsPerPage: 10, $numOfPages);
echo "Skupaj strani: $numOfPages";

group (string $columns, …$parameters): static

Združuje vrstice po navedenih stolpcih (GROUP BY). Uporablja se običajno v povezavi z agregatnimi funkcijami:

// Prešteje število izdelkov v vsaki kategoriji
$table->select('category_id, COUNT(*) AS count')
	->group('category_id');

having (string $having, …$parameters): static

Nastavi pogoj za filtriranje združenih vrstic (HAVING). Lahko se uporablja v povezavi z metodo group() in agregatnimi funkcijami:

// Najde kategorije, ki imajo več kot 100 izdelkov
$table->select('category_id, COUNT(*) AS count')
	->group('category_id')
	->having('count > ?', 100);

Branje podatkov

Za branje podatkov iz podatkovne baze imamo na voljo več uporabnih metod:

Objekt ActiveRow je namenjen samo za branje. To pomeni, da ni mogoče spreminjati vrednosti njegovih lastnosti. Ta omejitev zagotavlja doslednost podatkov in preprečuje nepričakovane stranske učinke. Podatki se nalagajo iz podatkovne baze in vsaka sprememba bi morala biti izvedena eksplicitno in nadzorovano.

foreach – iteracija čez vse vrstice

Najlažji način za izvedbo poizvedbe in pridobitev vrstic je iteriranje v zanki foreach. Samodejno zažene SQL poizvedbo.

$books = $explorer->table('book');
foreach ($books as $key => $book) {
	// $key je vrednost primarnega ključa, $book je ActiveRow
	echo "$book->title ({$book->author->name})";
}

get ($key): ?ActiveRow

Izvede SQL poizvedbo in vrne vrstico po primarnem ključu, ali null, če ne obstaja.

$book = $explorer->table('book')->get(123);  // vrne ActiveRow z ID 123 ali null
if ($book) {
	echo $book->title;
}

fetch(): ?ActiveRow

Vrne vrstico in premakne notranji kazalec na naslednjo. Če ni več vrstic, vrne null.

$books = $explorer->table('book');
while ($book = $books->fetch()) {
	$this->processBook($book);
}

fetchPairs (string|int|null $key = null, string|int|null $value = null): array

Vrne rezultate kot asociativno polje. Prvi argument določa ime stolpca, ki se uporabi kot ključ v polju, drugi argument določa ime stolpca, ki se uporabi kot vrednost:

$authors = $explorer->table('author')->fetchPairs('id', 'name');
// [1 => 'John Doe', 2 => 'Jane Doe', ...]

Če navedemo samo prvi parameter, bo vrednost celotna vrstica, torej objekt ActiveRow:

$authors = $explorer->table('author')->fetchPairs('id');
// [1 => ActiveRow(id: 1, ...), 2 => ActiveRow(id: 2, ...), ...]

V primeru podvojenih ključev se uporabi vrednost iz zadnje vrstice. Pri uporabi null kot ključa bo polje indeksirano numerično od nič (takrat do kolizij ne pride):

$authors = $explorer->table('author')->fetchPairs(null, 'name');
// [0 => 'John Doe', 1 => 'Jane Doe', ...]

fetchPairs (Closure $callback): array

Alternativno lahko kot parameter navedete povratni klic (callback), ki bo za vsako vrstico vračal bodisi samo vrednost, bodisi par ključ-vrednost.

$titles = $explorer->table('book')
	->fetchPairs(fn($row) => "$row->title ({$row->author->name})");
// ['Prva knjiga (Jan Novak)', ...]

// Callback lahko vrne tudi polje s parom ključ & vrednost:
$titles = $explorer->table('book')
	->fetchPairs(fn($row) => [$row->title, $row->author->name]);
// ['Prva knjiga' => 'Jan Novak', ...]

fetchAll(): array

Vrne vse vrstice kot asociativno polje objektov ActiveRow, kjer so ključi vrednosti primarnih ključev.

$allBooks = $explorer->table('book')->fetchAll();
// [1 => ActiveRow(id: 1, ...), 2 => ActiveRow(id: 2, ...), ...]

count(): int .{toc: count()}wiki-method {#count(): int}

Metoda count() brez parametra vrne število vrstic v objektu Selection:

$table->where('category', 1);
$count = $table->count();
$count = count($table); // alternativa

Pozor, count() s parametrom izvaja agregatno funkcijo COUNT v podatkovni bazi, glej spodaj.

ActiveRow::toArray(): array

Pretvori objekt ActiveRow v asociativno polje, kjer so ključi imena stolpcev in vrednosti ustrezni podatki.

$book = $explorer->table('book')->get(1);
$bookArray = $book->toArray();
// $bookArray bo ['id' => 1, 'title' => '...', 'author_id' => ..., ...]

Agregacija

Razred Selection ponuja metode za enostavno izvajanje agregatnih funkcij (COUNT, SUM, MIN, MAX, AVG itd.).

count (string $expr): int

Izvede SQL poizvedbo s funkcijo COUNT in vrne rezultat. Metoda se uporablja za ugotavljanje, koliko vrstic ustreza določenemu pogoju:

$count = $table->count('*');                 // SELECT COUNT(*) FROM `table`
$count = $table->count('DISTINCT column');   // SELECT COUNT(DISTINCT `column`) FROM `table`

Pozor, count() brez parametra samo vrača število vrstic v objektu Selection.

min (string $expr) a max(string $expr)

Metodi min() in max() vračata minimalno in maksimalno vrednost v določenem stolpcu ali izrazu:

// SELECT MAX(`price`) FROM `products` WHERE `active` = 1
$maxPrice = $products->where('active', true)
	->max('price');

sum (string $expr)

Vrne vsoto vrednosti v določenem stolpcu ali izrazu:

// SELECT SUM(`price` * `items_in_stock`) FROM `products` WHERE `active` = 1
$totalPrice = $products->where('active', true)
	->sum('price * items_in_stock');

aggregation (string $function, ?string $groupFunction = null)

Omogoča izvedbo poljubne agregatne funkcije.

// povprečna cena izdelkov v kategoriji
$avgPrice = $products->where('category_id', 1)
	->aggregation('AVG(price)');

// združi oznake izdelka v en niz
$tags = $products->where('id', 1)
	->aggregation('GROUP_CONCAT(tag.name) AS tags')
	->fetch()
	->tags;

Če moramo agregirati rezultate, ki so že sami po sebi nastali iz neke agregatne funkcije in združevanja (npr. SUM(vrednost) čez združene vrstice), kot drugi argument navedemo agregatno funkcijo, ki naj se uporabi na teh vmesnih rezultatih:

// Izračuna skupno ceno izdelkov na zalogi za posamezne kategorije in nato sešteje te cene skupaj.
$totalPrice = $products->select('category_id, SUM(price * stock) AS category_total')
	->group('category_id')
	->aggregation('SUM(category_total)', 'SUM');

V tem primeru najprej izračunamo skupno ceno izdelkov v vsaki kategoriji (SUM(price * stock) AS category_total) in združimo rezultate po category_id. Nato uporabimo aggregation('SUM(category_total)', 'SUM') za seštevanje teh vmesnih vsot category_total. Drugi argument 'SUM' pove, da naj se na vmesne rezultate uporabi funkcija SUM.

Insert, Update & Delete

Nette Database Explorer poenostavlja vstavljanje, posodabljanje in brisanje podatkov. Vse navedene metode v primeru napake vržejo izjemo Nette\Database\DriverException.

Selection::insert (iterable $data)

Vstavi nove zapise v tabelo.

Vstavljanje enega zapisa:

Nov zapis posredujemo kot asociativno polje ali iterable objekt (na primer ArrayHash, ki se uporablja v obrazcih), kjer ključi ustrezajo imenom stolpcev v tabeli.

Če ima tabela definiran primarni ključ, metoda vrne objekt ActiveRow, ki se ponovno naloži iz podatkovne baze, da se upoštevajo morebitne spremembe, izvedene na ravni podatkovne baze (sprožilci, privzete vrednosti stolpcev, izračuni auto-increment stolpcev). S tem je zagotovljena doslednost podatkov in objekt vedno vsebuje aktualne podatke iz podatkovne baze. Če enoličnega primarnega ključa nima, vrne posredovane podatke v obliki polja.

$row = $explorer->table('users')->insert([
	'name' => 'John Doe',
	'email' => 'john.doe@example.com',
]);
// $row je instanca ActiveRow in vsebuje celotne podatke vstavljene vrstice,
// vključno s samodejno generiranim ID-jem in morebitnimi spremembami, izvedenimi s sprožilci (triggerji)
echo $row->id; // Izpiše ID novo vstavljenega uporabnika
echo $row->created_at; // Izpiše čas ustvarjanja, če je nastavljen s sprožilcem

Vstavljanje več zapisov hkrati:

Metoda insert() omogoča vstavljanje več zapisov z eno samo SQL poizvedbo. V tem primeru vrne število vstavljenih vrstic.

$insertedRows = $explorer->table('users')->insert([
	[
		'name' => 'John',
		'year' => 1994,
	],
	[
		'name' => 'Jack',
		'year' => 1995,
	],
]);
// INSERT INTO `users` (`name`, `year`) VALUES ('John', 1994), ('Jack', 1995)
// $insertedRows bo 2

Kot parameter lahko posredujemo tudi objekt Selection z izborom podatkov.

$newUsers = $explorer->table('potential_users')
	->where('approved', 1)
	->select('name, email');

$insertedRows = $explorer->table('users')->insert($newUsers);

Vstavljanje posebnih vrednosti:

Kot vrednosti lahko posredujemo tudi datoteke, objekte DateTime ali SQL literale:

$explorer->table('users')->insert([
	'name' => 'John',
	'created_at' => new DateTime,           // pretvori v format podatkovne baze
	'avatar' => fopen('image.jpg', 'rb'),   // vstavi binarno vsebino datoteke
	'uuid' => $explorer::literal('UUID()'), // pokliče funkcijo UUID()
]);

Selection::update (iterable $data): int

Posodobi vrstice v tabeli po navedenem filtru. Vrne število dejansko spremenjenih vrstic.

Spremenjene stolpce posredujemo kot asociativno polje ali iterable objekt (na primer ArrayHash, ki se uporablja v obrazcih), kjer ključi ustrezajo imenom stolpcev v tabeli:

$affected = $explorer->table('users')
	->where('id', 10)
	->update([
		'name' => 'John Smith',
		'year' => 1994,
	]);
// UPDATE `users` SET `name` = 'John Smith', `year` = 1994 WHERE `id` = 10

Za spremembo številskih vrednosti lahko uporabimo operatorja += in -=:

$explorer->table('users')
	->where('id', 10)
	->update([
		'points+=' => 1,  // poveča vrednost stolpca 'points' za 1
		'coins-=' => 1,   // zmanjša vrednost stolpca 'coins' za 1
	]);
// UPDATE `users` SET `points` = `points` + 1, `coins` = `coins` - 1 WHERE `id` = 10

Selection::delete(): int

Briše vrstice iz tabele po navedenem filtru. Vrne število izbrisanih vrstic.

$count = $explorer->table('users')
	->where('id', 10)
	->delete();
// DELETE FROM `users` WHERE `id` = 10

Pri klicu update() in delete() ne pozabite s pomočjo where() določiti vrstic, ki naj se uredijo/izbrišejo. Če where() ne uporabite, se operacija izvede na celotni tabeli!

ActiveRow::update (iterable $data): bool

Posodobi podatke v podatkovni vrstici, ki jo predstavlja objekt ActiveRow. Kot parameter sprejme iterable s podatki, ki naj se posodobijo (ključi so imena stolpcev). Za spremembo številskih vrednosti lahko uporabimo operatorja += in -=:

Po izvedbi posodobitve se ActiveRow samodejno ponovno naloži iz podatkovne baze, da se upoštevajo morebitne spremembe, izvedene na ravni podatkovne baze (npr. sprožilci). Metoda vrne true samo, če je prišlo do dejanske spremembe podatkov.

$article = $explorer->table('article')->get(1);
$article->update([
	'views += 1',  // povečamo število prikazov
]);
echo $article->views; // Izpiše trenutno število prikazov

Ta metoda posodobi samo eno določeno vrstico v podatkovni bazi. Za množično posodabljanje več vrstic uporabite metodo Selection::update().

ActiveRow::delete()

Izbriše vrstico iz podatkovne baze, ki jo predstavlja objekt ActiveRow.

$book = $explorer->table('book')->get(1);
$book->delete(); // Izbriše knjigo z ID 1

Ta metoda briše samo eno določeno vrstico v podatkovni bazi. Za množično brisanje več vrstic uporabite metodo Selection::delete().

Povezave med tabelami

V relacijskih podatkovnih bazah so podatki razdeljeni na več tabel in medsebojno povezani s pomočjo tujih ključev. Nette Database Explorer prinaša revolucionaren način dela s temi povezavami – brez pisanja JOIN poizvedb in potrebe po kakršnikoli konfiguraciji ali generiranju.

Za ilustracijo dela s povezavami bomo uporabili primer podatkovne baze knjig (najdete ga na GitHubu). V podatkovni bazi imamo tabele:

• author – pisatelji in prevajalci (stolpci id, name, web, born)
• book – knjige (stolpci id, author_id, translator_id, title, sequel_id)
• tag – oznake (stolpci id, name)
• book_tag – povezovalna tabela med knjigami in oznakami (stolpci book_id, tag_id)

V našem primeru podatkovne baze knjig najdemo več tipov odnosov (čeprav je model poenostavljen v primerjavi z realnostjo):

• Ena-proti-mnogo 1:N – vsaka knjiga ima enega avtorja, avtor lahko napiše več knjig
• Nič-proti-mnogo 0:N – knjiga lahko ima prevajalca, prevajalec lahko prevede več knjig
• Nič-proti-ena 0:1 – knjiga lahko ima naslednji del
• Mnogo-proti-mnogo M:N – knjiga lahko ima več oznak in oznaka je lahko dodeljena več knjigam

V teh odnosih vedno obstaja nadrejena in podrejena tabela. Na primer v odnosu med avtorjem in knjigo je tabela author nadrejena in book podrejena – lahko si predstavljamo, da knjiga vedno »pripada« nekemu avtorju. To se odraža tudi v strukturi podatkovne baze: podrejena tabela book vsebuje tuji ključ author_id, ki se nanaša na nadrejeno tabelo author.

Če moramo izpisati knjige vključno z imeni njihovih avtorjev, imamo dve možnosti. Ali podatke pridobimo z eno samo SQL poizvedbo s pomočjo JOIN:

SELECT book.*, author.name FROM book LEFT JOIN author ON book.author_id = author.id

Ali pa podatke naložimo v dveh korakih – najprej knjige in nato njihove avtorje – in jih nato v PHP sestavimo:

SELECT * FROM book;
SELECT * FROM author WHERE id IN (1, 2, 3);  -- id-ji avtorjev pridobljenih knjig

Drugi pristop je dejansko učinkovitejši, čeprav se to morda zdi presenetljivo. Podatki so naloženi samo enkrat in jih je mogoče bolje izkoristiti v predpomnilniku. Prav na ta način deluje Nette Database Explorer – vse rešuje pod površjem in vam ponuja eleganten API:

$books = $explorer->table('book');
foreach ($books as $book) {
	echo 'title: ' . $book->title;
	echo 'written by: ' . $book->author->name; // $book->author je zapis iz tabele 'author'
	echo 'translated by: ' . $book->translator?->name;
}

Dostop do nadrejene tabele

Dostop do nadrejene tabele je neposreden. Gre za odnose kot knjiga ima avtorja ali knjiga lahko ima prevajalca. Povezan zapis pridobimo prek lastnosti objekta ActiveRow – njeno ime ustreza imenu stolpca s tujim ključem brez _id:

$book = $explorer->table('book')->get(1);
echo $book->author->name;      // najde avtorja po stolpcu author_id
echo $book->translator?->name; // najde prevajalca po stolpcu translator_id

Ko dostopamo do lastnosti $book->author, Explorer v tabeli book išče stolpec, katerega ime vsebuje niz author (torej author_id). Po vrednosti v tem stolpcu naloži ustrezen zapis iz tabele author in ga vrne kot ActiveRow. Podobno deluje tudi $book->translator, ki uporabi stolpec translator_id. Ker stolpec translator_id lahko vsebuje null, v kodi uporabimo operator ?->.

Alternativno pot ponuja metoda ref(), ki sprejme dva argumenta, ime ciljne tabele in ime povezovalnega stolpca, ter vrne instanco ActiveRow ali null:

echo $book->ref('author', 'author_id')->name;      // povezava na avtorja
echo $book->ref('author', 'translator_id')->name;  // povezava na prevajalca

Metoda ref() je koristna, če ni mogoče uporabiti dostopa prek lastnosti, ker tabela vsebuje stolpec z istim imenom (tj. author). V ostalih primerih je priporočljivo uporabljati dostop prek lastnosti, ki je bolj berljiv.

Explorer samodejno optimizira podatkovne poizvedbe. Ko prehajamo skozi knjige v zanki in dostopamo do njihovih povezanih zapisov (avtorjev, prevajalcev), Explorer ne generira poizvedbe za vsako knjigo posebej. Namesto tega izvede samo en SELECT za vsak tip povezave, s čimer bistveno zmanjša obremenitev podatkovne baze. Na primer:

$books = $explorer->table('book');
foreach ($books as $book) {
	echo $book->title . ': ';
	echo $book->author->name;
	echo $book->translator?->name;
}

Ta koda pokliče samo te tri bliskovite poizvedbe v podatkovno bazo:

SELECT * FROM `book`;
SELECT * FROM `author` WHERE (`id` IN (1, 2, 3)); -- id iz stolpca author_id izbranih knjig
SELECT * FROM `author` WHERE (`id` IN (2, 3));    -- id iz stolpca translator_id izbranih knjig

Logika iskanja povezovalnega stolpca je določena z implementacijo Conventions. Priporočamo uporabo DiscoveredConventions, ki analizira tuje ključe in omogoča enostavno delo z obstoječimi relacijami med tabelami.

Dostop do podrejene tabele

Dostop do podrejene tabele deluje v obratni smeri. Zdaj se sprašujemo katere knjige je napisal ta avtor ali prevedel ta prevajalec. Za ta tip poizvedbe uporabljamo metodo related(), ki vrne Selection s povezanimi zapisi. Poglejmo si primer:

$author = $explorer->table('author')->get(1);

// Izpiše vse knjige avtorja
foreach ($author->related('book.author_id') as $book) {
	echo "Napisal: $book->title";
}

// Izpiše vse knjige, ki jih je avtor prevedel
foreach ($author->related('book.translator_id') as $book) {
	echo "Prevedel: $book->title";
}

Metoda related() sprejme opis povezave kot en argument s pikčasto notacijo ali kot dva ločena argumenta:

$author->related('book.translator_id');  // en argument
$author->related('book', 'translator_id');  // dva argumenta

Explorer zna samodejno zaznati pravilen povezovalni stolpec na podlagi imena nadrejene tabele. V tem primeru se povezuje prek stolpca book.author_id, ker je ime izvorne tabele author:

$author->related('book');  // uporabi book.author_id

Če bi obstajalo več možnih povezav, Explorer vrže izjemo AmbiguousReferenceKeyException.

Metodo related() lahko seveda uporabimo tudi pri prehajanju skozi več zapisov v zanki in Explorer tudi v tem primeru samodejno optimizira poizvedbe:

$authors = $explorer->table('author');
foreach ($authors as $author) {
	echo $author->name . ' napisal:';
	foreach ($author->related('book') as $book) {
		echo $book->title;
	}
}

Ta koda generira samo dve bliskoviti SQL poizvedbi:

SELECT * FROM `author`;
SELECT * FROM `book` WHERE (`author_id` IN (1, 2, 3)); -- id izbranih avtorjev

Povezava Mnogo-proti-mnogo

Za povezavo mnogo-proti-mnogo (M:N) je potrebna obstoj povezovalne tabele (v našem primeru book_tag), ki vsebuje dva stolpca s tujima ključema (book_id, tag_id). Vsak od teh stolpcev se nanaša na primarni ključ ene od povezanih tabel. Za pridobitev povezanih podatkov najprej pridobimo zapise iz povezovalne tabele s pomočjo related('book_tag') in nato nadaljujemo k ciljnim podatkom:

$book = $explorer->table('book')->get(1);
// izpiše imena oznak, dodeljenih knjigi
foreach ($book->related('book_tag') as $bookTag) {
	echo $bookTag->tag->name;  // izpiše ime oznake prek povezovalne tabele
}

$tag = $explorer->table('tag')->get(1);
// ali obratno: izpiše imena knjig, označenih s to oznako
foreach ($tag->related('book_tag') as $bookTag) {
	echo $bookTag->book->title; // izpiše ime knjige
}

Explorer spet optimizira SQL poizvedbe v učinkovito obliko:

SELECT * FROM `book`;
SELECT * FROM `book_tag` WHERE (`book_tag`.`book_id` IN (1, 2, ...));  -- id izbranih knjig
SELECT * FROM `tag` WHERE (`tag`.`id` IN (1, 2, ...));                 -- id oznak, najdenih v book_tag

Poizvedovanje prek povezanih tabel

V metodah where(), select(), order() in group() lahko uporabljamo posebne notacije za dostop do stolpcev iz drugih tabel. Explorer samodejno ustvari potrebne JOINe.

Pikčasta notacija (nadrejena_tabela.stolpec) se uporablja za odnos 1:N z vidika podrejene tabele:

$books = $explorer->table('book');

// Najde knjige, katerih avtor ima ime, ki se začne na 'Jon'
$books->where('author.name LIKE ?', 'Jon%');

// Razvrsti knjige po imenu avtorja padajoče
$books->order('author.name DESC');

// Izpiše naslov knjige in ime avtorja
$books->select('book.title, author.name');

Dvopična notacija (:podrejena_tabela.stolpec) se uporablja za odnos 1:N z vidika nadrejene tabele:

$authors = $explorer->table('author');

// Najde avtorje, ki so napisali knjigo s 'PHP' v naslovu
$authors->where(':book.title LIKE ?', '%PHP%');

// Prešteje število knjig za vsakega avtorja
$authors->select('*, COUNT(:book.id) AS book_count')
	->group('author.id');

V zgornjem primeru z dvopično notacijo (:book.title) ni določen stolpec s tujim ključem. Explorer samodejno zazna pravilen stolpec na podlagi imena nadrejene tabele. V tem primeru se povezuje prek stolpca book.author_id, ker je ime izvorne tabele author. Če bi obstajalo več možnih povezav, Explorer vrže izjemo AmbiguousReferenceKeyException.

Povezovalni stolpec lahko eksplicitno navedemo v oklepaju:

// Najde avtorje, ki so prevedli knjigo s 'PHP' v naslovu
$authors->where(':book(translator_id).title LIKE ?', '%PHP%');

Notacije lahko verižimo za dostop prek več tabel:

// Najde avtorje knjig, označenih z oznako 'PHP'
$authors->where(':book:book_tag.tag.name', 'PHP')
	->group('author.id');

Razširitev pogojev za JOIN

Metoda joinWhere() razširja pogoje, ki se navajajo pri povezovanju tabel v SQL za ključno besedo ON.

Recimo, da želimo najti knjige, prevedene s strani določenega prevajalca:

// Najde knjige, prevedene s strani prevajalca z imenom 'David'
$books = $explorer->table('book')
	->joinWhere('translator', 'translator.name', 'David');
// LEFT JOIN author translator ON book.translator_id = translator.id AND (translator.name = 'David')

V pogoju joinWhere() lahko uporabljamo enake konstrukcije kot v metodi where() – operatorje, nadomestne vprašaje, polja vrednosti ali SQL izraze.

Za kompleksnejše poizvedbe z več JOINi lahko definiramo aliase tabel:

$tags = $explorer->table('tag')
	->joinWhere(':book_tag.book.author', 'book_author.born < ?', 1950)
	->alias(':book_tag.book.author', 'book_author');
// LEFT JOIN `book_tag` ON `tag`.`id` = `book_tag`.`tag_id`
// LEFT JOIN `book` ON `book_tag`.`book_id` = `book`.`id`
// LEFT JOIN `author` `book_author` ON `book`.`author_id` = `book_author`.`id`
//    AND (`book_author`.`born` < 1950)

Opazite, da medtem ko metoda where() dodaja pogoje v klavzulo WHERE, metoda joinWhere() razširja pogoje v klavzuli ON pri povezovanju tabel.