Database doc update

Author: matej21

doc/cs/database-activerow.texy

@@ -1,7 +1,8 @@
 Database: ActiveRow
 *******************
 
-Každý řádek, který vrátí [Selection | api:Nette\Database\Table\Selection] je reprezentován instancí [ActiveRow | api:Nette\Database\Table\ActiveRow]. Tato třída poskytuje standardní interface pro přístup k vybraným sloupcům. Data může číst jako členské proměnné nebo použít přístup přes klíče pole. Pokud sloupec neexistuje, je vyhozena výjimka [MemberAccessException | api:Nette\MemberAccessException]. Pomocí standardní konstrukce `isset` lze ověřit, zda má sloupec nastavenou neprázdnou hodnotu.
+Každý řádek, který vrátí [Selection | api:Nette\Database\Table\Selection], je reprezentován instancí [ActiveRow | api:Nette\Database\Table\ActiveRow]. Tato třída poskytuje standardní interface pro přístup k vybraným sloupcům. Data můžeme číst jako členské proměnné nebo použít přístup přes klíče pole. Pokud sloupec neexistuje, je vyhozena výjimka [MemberAccessException | api:Nette\MemberAccessException]. Pomocí standardní konstrukce `isset` lze ověřit, zda má sloupec nastavenou neprázdnou hodnotu.
+
 
 /--code php
 echo $book->id;
@@ -11,7 +12,7 @@ isset($book->id);
 isset($book['title']);
 \--
 
-Pozor, `isset` vrátí FALSE, i když byl sloupec dotazem vybrán, ale má hodnotu NULL.
+Pozor, `isset` vrátí `FALSE`, i když byl sloupec dotazem vybrán, ale má hodnotu `NULL`.
 
 
 Vztahy
@@ -20,18 +21,18 @@ Vztahy
 Hlavním principem Nette\Database\Table je oddělené načítání dat z různých tabulek. Toto chování je zajišťováno samotnou Nette\Database, příbuzná data jsou z databáze vybrána pro všechny řádky najednou. Máme dva hlavní druhy vztahů: "has one" a "has many".
 
 .[note]
-Budeme používat DiscoveredConventions, která načte vztahy mezi tabulkami přímo z databáze.
+Budeme používat `DiscoveredConventions`, která načte vztahy mezi tabulkami přímo z databáze.
 
 Relace Has one
 --------------
-Relace has one je velmi běžná. Kniha *má jednoho* autora. Kniha *má jednoho* překladatele. Řádek, který je ve vztahu has one získáme pomocí metody [ref() | api:Nette\Database\Table\ActiveRow::ref()]. Ref() přijímá dva argumenty: jméno cílové tabulky a název spojovacího sloupce. Viz příklad:
+Relace has one je velmi běžná. Kniha *má jednoho* autora. Kniha *má jednoho* překladatele. Řádek, který je ve vztahu has one získáme pomocí metody [ref() | api:Nette\Database\Table\ActiveRow::ref()]. `ref()` přijímá dva argumenty: jméno cílové tabulky a název spojovacího sloupce. Viz příklad:
 
 /--code php
 $book = $context->table('book')->get(1);
 $book->ref('author', 'author_id');
 \--
 
-V příkladu výše vybíráme souvisejícího autora z tabulky `author`. Primární klíč tabulky `author` je hledán podle sloupce `book.author_id`. Metoda ref() vrací instanci ActiveRow nebo NULL, pokud hledaný záznam neexistuje. Vrácený řádek je instance ActiveRow, takže s ním můžeme pracovat stejně jako se záznamem knihy.
+V příkladu výše vybíráme souvisejícího autora z tabulky `author`. Primární klíč tabulky `author` je hledán podle sloupce `book.author_id`. Metoda `ref()` vrací instanci `ActiveRow` nebo `NULL`, pokud hledaný záznam neexistuje. Vrácený řádek je instance `ActiveRow`, takže s ním můžeme pracovat stejně jako se záznamem knihy.
 
 /--code php
 $author = $book->ref('author', 'author_id');
@@ -50,15 +51,15 @@ $book->ref('author', 'translator_id')->name
 
 Tento přístup je funkční, ale pořád trochu zbytečně těžkopádný, nemyslíte? Databáze už obsahuje definice cizích klíčů, tak proč je nepoužít automaticky. Pojďme to vyzkoušet.
 
-Pokud přistoupíme k členské proměnné, která neexistuje, ActiveRow se pokusí použít jméno této proměnné pro relaci "has one". Čtení této proměnné je stejné jako volání metody ref() pouze s jedním parametrem. Tomuto parametru budeme říkat **klíč**. Tento klíč bude použit pro vyhledání cizího klíče v tabulce. Předaný klíč je porovnán se sloupci, a pokud odpovídá pravidlům, je cizí klíč na daném sloupci použit pro čtení dat z příbuzné tabulky. Viz příklad:
+Pokud přistoupíme k členské proměnné, která neexistuje, ActiveRow se pokusí použít jméno této proměnné pro relaci "has one". Čtení této proměnné je stejné jako volání metody `ref()` pouze s jedním parametrem. Tomuto parametru budeme říkat **klíč**. Tento klíč bude použit pro vyhledání cizího klíče v tabulce. Předaný klíč je porovnán se sloupci, a pokud odpovídá pravidlům, je cizí klíč na daném sloupci použit pro čtení dat z příbuzné tabulky. Viz příklad:
 
 /--code php
 $book->author->name;
 // je stejné jako
 $book->ref('author')->name;
 \--
 
-Instance ActiveRow nemá žádný sloupec author. Všechny sloupce tabulky book jsou prohledány na shodu s *klíčem*. Shoda v tomto případě znamená, že jméno sloupce musí obsahovat klíč. V příkladu výše sloupec `author_id` obsahuje řetězec "author" a tedy odpovídá klíči "author". Pokud chceme přistoupit k záznamu překladatele, obdobným způsobem použijeme klíč "translator",  protože bude odpovídat sloupci `translator_id`. Více o logice párování klíčů si můžete přečíst v kapitole [Joining expressions | database-selection#joining-key].
+Instance ActiveRow nemá žádný sloupec `author`. Všechny sloupce tabulky `book` jsou prohledány na shodu s *klíčem*. Shoda v tomto případě znamená, že jméno sloupce musí obsahovat klíč. V příkladu výše sloupec `author_id` obsahuje řetězec "author" a tedy odpovídá klíči "author". Pokud chceme přistoupit k záznamu překladatele, obdobným způsobem použijeme klíč "translator", protože bude odpovídat sloupci `translator_id`. Více o logice párování klíčů si můžete přečíst v kapitole [Joining expressions | database-selection#joining-key].
 
 /--code php
 echo $book->title . ": ";
@@ -108,7 +109,7 @@ foreach ($author->related('book.translator_id') as $book) {
 }
 \--
 
-Metoda [related() | api:Nette\Database\Table\ActiveRow::related()] přijímá popis spojení jako dva argumenty, nebo jako jeden argument spojený tečkou. První argument je cílová tabulka, druhý je sloupec.
+Metoda `related()` přijímá popis spojení jako dva argumenty, nebo jako jeden argument spojený tečkou. První argument je cílová tabulka, druhý je sloupec.
 /--code php
 $author->related('book.translator_id');
 // je stejné jako
@@ -117,7 +118,7 @@ $author->related('book', 'translator_id');
 
 Můžeme použít heuristiku Nette\Database založenou na cizích klíčích a použít pouze **klíč**. Klíč bude porovnán s cizími klíči, které odkazují do aktuální tabulky (tabulka `author`). Pokud je nalezena shoda, Nette\Database použije tento cizí klíč, v opačném případě vyhodí výjimku [Nette\InvalidArgumentException | api:Nette\InvalidArgumentException] nebo [AmbiguousReferenceKeyException | api:Nette\Database\Conventions\AmbiguousReferenceKeyException]. Více o logice párování klíčů si můžete přečíst v kapitole [Joining expressions | database-selection#joining-key].
 
-Metodu related může samozřejmě volat na všechny získané autory a Nette\Database načte všechny odpovídající knihy najednou.
+Metodu `related()` může samozřejmě volat na všechny získané autory a Nette\Database načte všechny odpovídající knihy najednou.
 
 /--code php
 $authors = $context->table('author');

doc/cs/database-selection.texy

@@ -5,7 +5,7 @@ Database: Selection
 
 Filtrování
 ----------
-Pojďme se podívat na základní API Selection. Jednoduché podmínky můžeme vytvořit zavoláním metody [where() |api:Nette\Database\Table\Selection::where()]. Otazníky v dotazu budou nahrazeny obsahem proměnných.
+Pojďme se podívat na základní API třídy Selection. Jednoduché podmínky můžeme vytvořit zavoláním metody [where() |api:Nette\Database\Table\Selection::where()]. Otazníky v dotazu budou nahrazeny obsahem proměnných.
 
 /--code php
 $selection->where('name = ?', $name);
@@ -89,7 +89,7 @@ $selection->group('author.id')
           ->having('COUNT(:book.id) > 3');
 \--
 
-Možná jste si všimli, že spojovací výraz odkazuje na book, ale není jasné, jestli spojujeme přes `author_id` nebo `translator_id`. Ve výše uvedeném příkladu Selection spojuje přes sloupec `author_id`, protože byla nalezena shoda se jménem zdrojové tabulky - tabulky `author`. Pokud by neexistovala shoda a existovalo více možností, Nette vyhodí výjimku [AmbiguousReferenceKeyException |api:Nette\Database\Conventions\AmbiguousReferenceKeyException].
+Možná jste si všimli, že spojovací výraz odkazuje na `book`, ale není jasné, jestli spojujeme přes `author_id` nebo `translator_id`. Ve výše uvedeném příkladu Selection spojuje přes sloupec `author_id`, protože byla nalezena shoda se jménem zdrojové tabulky - tabulky `author`. Pokud by neexistovala shoda a existovalo více možností, Nette vyhodí výjimku [AmbiguousReferenceKeyException |api:Nette\Database\Conventions\AmbiguousReferenceKeyException].
 
 Abychom mohli spojovat přes `translator_id`, stačí přidat volitelný "parametr" do spojovacího výrazu.
 
@@ -128,7 +128,14 @@ Podívejme se na různé možnosti filtrování a omezování výběru pomocí A
 | `$table->group($columns)` | Nastaví GROUP BY
 | `$table->having($having)` | Nastaví HAVING
 
-Můžeme použít tzv. fluent interface, například `$table->where(...)->order(...)->limit(...)`. Více `where` nebo `whereOr` podmínek je spojeno pomocí operátoru `AND`.
+Nejen v metodě `where` můžeme použít parametry. Parametry jsou podporovány i v metodách `order, select, group a having`. A pokud do těchto metod dosazujeme hodnotu, je nutné parametry použít, aby Nette\Database správně dotaz escapovalo (viz [zapisování dotazů|database-table#zapisovani-dotazu]:
+
+/--code php
+$table->select('DATE_FORMAT(created, ?)', '%d.%m.%Y')
+\--
+
+
+Můžeme použít tzv. fluent interface, například `$table->where(...)->order(...)->limit(...)`.  Více `where` nebo `whereOr` podmínek je spojeno pomocí operátoru `AND`. Pro operátor `OR` musíme použít pouze jedno volání `where()`:
 
 Možné argumenty metody [where() |api:Nette\Database\Table\Selection::where()]:
 
@@ -150,6 +157,9 @@ Můžeme vytvořit také agregaci výsledků:
 | `$table->sum($column)` | Vrátí součet všech hodnot
 | `$table->aggregation("GROUP_CONCAT($column)")` | Pro jakoukoliv jinou agregační funkci
 
+.[caution]
+Metoda `count()` bez uvedeného parametru vybere všechny záznamy a vrátí velikost pole, což je velmi neefektivní. Pokud potřebujete například spočítat počet řádků pro stránkování, vždy první argument uveďte.
+
 Čtení dat:
 
 .[wide]

doc/cs/database-table.texy

@@ -11,13 +11,13 @@ Pojďme si vyzkoušet jednoduchý příklad. Potřebujeme z databáze vybrat kni
 
 Vrstva Database\Table poskytuje instanci [Selection |api:Nette\Database\Table\Selection], která reprezentuje výběr dat z *jedné* databázové tabulky. Tato instance umožňuje filtrování požadovaných dat a vrací je jako instance ActiveRow.
 
-Vytvoření Selection je jednoduché, stačí zavolat metodu [table() |api:Nette\Database\Context::table()] na objektu databázového připojení. Jak se k databázi připojíme je popsáno v kapitole [Nette\Database | database].
+Vytvoření Selection je jednoduché, stačí zavolat metodu [table() |api:Nette\Database\Context::table()] na objektu databázového připojení. Jak se [k databázi připojíme |database#Vytvoření pomocí aplikační konfigurace] je popsáno v kapitole [Nette\Database | database], pokud však používáme Nette\Database samostatně, je nutno tento objekt [vytvořit |#rucni-vytvoreni-database-context].
 
 /--code php
 $selection = $context->table('book'); // jméno tabulky je "book"
 \--
 
-Selection implementuje interface [Traversable |php:Traversable]: nad instancí můžeme jednoduše iterovat a vybrat tak všechny knihy. Řádky jsou vráceny jako instance Active Row a data z nich můžeme přímo číst.
+Selection implementuje interface [Traversable |php:Traversable]: nad instancí můžeme jednoduše iterovat a vybrat tak všechny knihy. Řádky jsou vráceny jako instance ActiveRow a data z nich můžeme přímo číst.
 
 /--code php
 $books = $context->table('book');
@@ -82,6 +82,54 @@ SELECT `book_id`, `tag_id` FROM `book_tag` WHERE (`book_tag`.`book_id` IN (1, 4,
 SELECT `id`, `name` FROM `tag` WHERE (`tag`.`id` IN (21, 22, 23))
 \--
 
+Zapisování dotazů
+-----------------
+
+Database\Table umí chytře escapovat parametry a identifikátory. Pro správnou funkčnost je ale nutno dodržovat několik pravidel:
+
+- klíčová slova, názvy funkcí, procedur apod. psát velkými písmeny
+- názvy sloupečků a tabulek psát malými písmeny
+- hodnoty dosazovat přes parametry
+
+/--code php
+//SPATNE!:
+//->where("name like ?", "John"); //vygeneruje: `name` `like` ?
+//spravne:
+->where("name LIKE ?", "John");
+
+//SPATNE!:
+//->where("KEY = ?", $value); //KEY je klíčové slovo
+//spravne:
+->where("key = ?", $value); //vygeneruje: `key` = ?
+
+//SPATNE!:
+//->where("name = " . $name); //sql injection!
+//spravne:
+->where("name = ?", $name);
+\--
+
+.[warning]
+Špatné použití může vést k bezpečnostním dírám v aplikaci.
+
+
+Ruční vytvoření Database\Context
+--------------------------------
+
+Pokud jsme si vytvořili databázové spojení pomocí aplikační konfigurace, nemusíme se o nic starat. Vytvořila se nám totiž i služba typu `Nette\Database\Context`, kterou si můžeme předat pomocí DI.
+
+Pokud ale používáme Nette\Database samostatně a chceme využívat vrstvu Table, musíme instanci Database\Context vytvořit ručně.
+
+/--code php
+//$storage obsahuje implementaci Nette\Caching\IStorage, napr.:
+//$storage = new Nette\Caching\FileStorage($tempDir);
+
+$connection = new Nette\Database\Connection($dsn, $user, $password);
+
+$structure = new Nette\Database\Structure($connection, $storage);
+$conventions = new Nette\Database\Conventions\DiscoveredConventions($structure);
+$context = new Nette\Database\Context($connection, $structure, $conventions, $storage);
+\--
+
 {{toc: title}}
 
 {{themeicon: icon-database.png}}