3. QueryBuilder: Podrobný prehľad

QueryBuilder je kľúčovým nástrojom Databaseru, ktorý umožňuje vytvárať SQL dotazy pomocou reťaziteľných metód. Jeho hlavnou výhodou je jednoduchosť, čitateľnosť a bezpečnosť – automaticky spravuje prepared statements a bindings, čím chráni pred SQL injection útokmi. V tejto kapitole podrobne rozoberieme jeho fungovanie, dostupné metódy a ukážeme príklady od jednoduchých až po zložité dotazy.

3.1. Základné princípy QueryBuildera

QueryBuilder je objekt triedy Dotsystems\App\Parts\QueryBuilder, ktorý sa používa v rámci metódy q() alebo qb() na inštancii $DotApp->DB. Funguje tak, že postupne budujete dotaz volaním metód, pričom každá metóda pridáva časť SQL príkazu (napr. select, where, join). Na konci sa dotaz vykoná pomocou metód ako execute(), first() alebo all().

Základné vlastnosti:

• Reťaziteľnosť: Metódy vracajú inštanciu QueryBuildera, takže ich môžete spájať do reťazca.
• Prepared Statements: Všetky hodnoty sú automaticky escapované a nahrádzané placeholdermi (?).
• Flexibilita: Podpora surových SQL dotazov cez metódu raw() pre špeciálne prípady.
• Debugovateľnosť: Po vykonaní dotazu dostanete v $debug vygenerovaný SQL a bindings.

Príklad základného použitia:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        echo $debug['query']; // "SELECT * FROM users WHERE age > ?"
        var_dump($debug['bindings']); // [18]
        var_dump($result);
    }
);

3.2. Zoznam metód QueryBuildera

Tu je podrobný prehľad všetkých hlavných metód QueryBuildera s vysvetlením a príkladmi.

3.2.1. select

Metóda select() definuje, ktoré stĺpce a z ktorej tabuľky chcete vybrať dáta.

Syntax: select($columns = '*', $table = null)

Parametre:

• $columns: Reťazec alebo pole stĺpcov (napr. 'id, name' alebo ['id', 'name']).
• $table: Názov tabuľky (voliteľné, ak použijete from()).

SQL ekvivalent: SELECT stĺpce FROM tabuľka

Príklad:

$qb->select('id, name', 'users');
// SQL: SELECT id, name FROM users

3.2.2. insert

Metóda insert() vloží nový riadok do tabuľky.

Syntax: insert($table, array $data)

Parametre:

• $table: Názov tabuľky.
• $data: Asociatívne pole s dátami (stĺpec => hodnota).

SQL ekvivalent: INSERT INTO tabuľka (stĺpce) VALUES (hodnoty)

Príklad:

$qb->insert('users', ['name' => 'Jano', 'age' => 25]);
// SQL: INSERT INTO users (name, age) VALUES (?, ?)
// Bindings: ['Jano', 25]

3.2.3. update

Metóda update() a set() aktualizuje existujúce riadky.

Syntax: update($table) + set(array $data)

Parametre:

SQL ekvivalent: UPDATE tabuľka SET stĺpec = hodnota

Príklad:

$qb->update('users')->set(['age' => 26])->where('id', '=', 1);
// SQL: UPDATE users SET age = ? WHERE id = ?
// Bindings: [26, 1]

3.2.4. delete

Metóda delete() odstráni riadky z tabuľky.

Syntax: delete($table = null)

Parametre:

• $table: Názov tabuľky (voliteľné, ak je definované inde).

SQL ekvivalent: DELETE FROM tabuľka

Príklad:

$qb->delete('users')->where('id', '=', 1);
// SQL: DELETE FROM users WHERE id = ?
// Bindings: [1]

3.2.5. where a orWhere

Metódy where() a orWhere() pridávajú podmienky.

Syntax: where($column, $operator = null, $value = null, $boolean = 'AND')

Parametre:

• $column: Stĺpec alebo Closure pre vnorené podmienky.
• $operator: Operátor (napr. =, >, <).
• $value: Hodnota alebo Closure pre subdotaz.
• $boolean: Logický spoj (predvolené AND).

SQL ekvivalent: WHERE stĺpec operátor hodnota

Príklad:

$qb->select('*', 'users')
   ->where('age', '>', 18)
   ->orWhere('name', '=', 'Jano');
// SQL: SELECT * FROM users WHERE age > ? OR name = ?
// Bindings: [18, 'Jano']

3.2.6. join (INNER, LEFT)

Metódy join() a leftJoin() spájajú tabuľky.

Syntax: join($table, $first, $operator, $second, $type = 'INNER')

Parametre:

• $table: Tabuľka alebo subdotaz (QueryBuilder).
• $first: Prvý stĺpec podmienky.
• $operator: Operátor spojenia.
• $second: Druhý stĺpec podmienky.
• $type: Typ spojenia (INNER, LEFT).

SQL ekvivalent: INNER JOIN tabuľka ON podmienka

Príklad:

$qb->select('users.name', 'users')
   ->join('posts', 'users.id', '=', 'posts.user_id');
// SQL: SELECT users.name FROM users INNER JOIN posts ON users.id = posts.user_id

3.2.7. groupBy

Metóda groupBy() zoskupuje výsledky.

Syntax: groupBy($columns)

Parametre:

• $columns: Stĺpec alebo pole stĺpcov.

SQL ekvivalent: GROUP BY stĺpce

Príklad:

$qb->select('age', 'users')->groupBy('age');
// SQL: SELECT age FROM users GROUP BY age

3.2.8. having

Metóda having() filtruje zoskupené výsledky.

Syntax: having($column, $operator, $value)

Parametre:

• $column: Stĺpec.
• $operator: Operátor.
• $value: Hodnota.

SQL ekvivalent: HAVING stĺpec operátor hodnota

Príklad:

$qb->select('age', 'users')->groupBy('age')->having('age', '>', 20);
// SQL: SELECT age FROM users GROUP BY age HAVING age > ?
// Bindings: [20]

3.2.9. orderBy

Metóda orderBy() zoraďuje výsledky.

Syntax: orderBy($column, $direction = 'ASC')

Parametre:

• $column: Stĺpec.
• $direction: Smer (ASC alebo DESC).

SQL ekvivalent: ORDER BY stĺpec smer

Príklad:

$qb->select('*', 'users')->orderBy('age', 'DESC');
// SQL: SELECT * FROM users ORDER BY age DESC

3.2.11. limit a offset

Metódy limit() a offset() obmedzujú počet výsledkov.

Syntax: limit($limit) + offset($offset)

Parametre:

• $limit: Počet riadkov.
• $offset: Počiatočný posun.

SQL ekvivalent: LIMIT počet OFFSET posun

Príklad:

$qb->select('*', 'users')->limit(5)->offset(10);
// SQL: SELECT * FROM users LIMIT ? OFFSET ?
// Bindings: [5, 10]

3.2.11. raw Query

Metóda raw() umožňuje použiť surový SQL dotaz.

Syntax: raw($sql, array $bindings = [])

Parametre:

• $sql: Surový SQL reťazec.
• $bindings: Pole hodnôt pre placeholdery.

SQL ekvivalent: Priamo zadaný dotaz.

Príklad:

$qb->raw('SELECT * FROM users WHERE age > ?', [18]);
// SQL: SELECT * FROM users WHERE age > ?
// Bindings: [18]

3.3. Príklady od jednoduchých po zložité dotazy

Jednoduchý select

$qb->select('*', 'users');
// SQL: SELECT * FROM users

select s where podmienkou

$qb->select('name', 'users')->where('age', '>', 18);
// SQL: SELECT name FROM users WHERE age > ?
// Bindings: [18]

Vnorené podmienky (Closure)

$qb->select('*', 'users')->where(function ($qb) {
    $qb->where('age', '>', 18)->orWhere('name', '=', 'Jano');
});
// SQL: SELECT * FROM users WHERE (age > ? OR name = ?)
// Bindings: [18, 'Jano']

join s viacerými tabuľkami

$qb->select('users.name, posts.title', 'users')
   ->join('posts', 'users.id', '=', 'posts.user_id')
   ->leftJoin('comments', 'posts.id', '=', 'comments.post_id');
// SQL: SELECT users.name, posts.title FROM users
//      INNER JOIN posts ON users.id = posts.user_id
//      LEFT JOIN comments ON posts.id = comments.post_id

Subquery ako hodnota

$qb->select('name', 'users')->where('id', '=', function ($qb) {
    $qb->select('user_id', 'posts')->where('title', '=', 'Novinka');
});
// SQL: SELECT name FROM users WHERE id = (SELECT user_id FROM posts WHERE title = ?)
// Bindings: ['Novinka']

raw dotaz s pomenovanými premennými

$qb->raw('SELECT * FROM users WHERE age > :age AND name = :name', [
    'age' => 18,
    'name' => 'Jano'
]);
// SQL: SELECT * FROM users WHERE age > ? AND name = ?
// Bindings: [18, 'Jano']

4. Práca s Databaserom v DotApp

V tejto kapitole sa zameriame na praktické použitie Databaseru v rámci DotApp Frameworku. Ukážeme, ako nastaviť typ návratu, vykonávať dotazy, pracovať s ORM, spravovať transakcie a debugovať výsledky. Databaser je navrhnutý tak, aby poskytoval flexibilitu a jednoduchosť, či už preferujete RAW prístup, alebo objektovo-orientovaný ORM.

4.1. Nastavenie typu návratu (RAW vs. ORM)

Databaser umožňuje definovať, aký typ dát chcete dostať ako výsledok dotazu. Typ návratu sa nastavuje pomocou metódy return() a ovplyvňuje, ako budú dáta spracované po vykonaní dotazu.

• RAW: Vráti surové dáta (napr. pole riadkov alebo databázový zdroj). Predvolený typ.
• ORM: Vráti dáta ako objekty (Entity pre jeden riadok, Collection pre viac riadkov).

Syntax: $DotApp->DB->return($type)

$type: Reťazec 'RAW' alebo 'ORM' (nezáleží na veľkosti písmen).

Príklad nastavenia RAW:

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->select('*', 'users');
})->execute(
    function ($result, $db, $debug) {
        var_dump($result); // Pole riadkov
    }
);

Príklad nastavenia ORM:

$DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->execute(
    function ($result, $db, $debug) {
        var_dump($result); // Inštancia Collection
    }
);

Typ návratu môžete meniť pred každým dotazom, čo vám dáva flexibilitu pri práci s rôznymi časťami aplikácie.

4.2. Metódy pre vykonanie dotazov

Databaser ponúka niekoľko metód na vykonanie dotazov vytvorených QueryBuilderom. Každá metóda má svoje špecifické použitie.

4.2.1. execute()

Metóda execute() je najuniverzálnejšia – vykoná dotaz a výsledky spracuje cez callbacky.

Syntax: execute($success = null, $error = null)

Parametre:

• $success: Callback pre úspech (function ($result, $db, $debug)).
• $error: Callback pre chybu (function ($error, $db, $debug)).

Výstup: Závisí od typu návratu (RAW: pole/zdroj, ORM: Collection/Entity).

Príklad:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        echo "Dotaz: " . $debug['query'] . "\n";
        var_dump($result);
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

4.2.2. first()

Metóda first() vráti prvý riadok výsledkov.

Syntax: first()

Výstup: RAW – pole, ORM – Entity alebo null.

Príklad:

$result = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
if ($result) {
    echo $result->name; // Prístup k atribútom v ORM
}

4.3. Práca s ORM

ORM mód Databaseru umožňuje pracovať s dátami ako s objektmi, čo zjednodušuje manipuláciu a vzťahy medzi tabuľkami.

4.3.1. Entity a Collection

Entity: Predstavuje jeden riadok tabuľky. Má atribúty zodpovedajúce stĺpcom a metódy na manipuláciu.

Collection: Zoskupenie viacerých Entity objektov s podporou iterácie a hromadných operácií.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
foreach ($users as $user) {
    echo $user->name . "\n"; // Collection vracia Entity objekty
}

4.3.2. Ukladanie dát (save())

Metóda save() na Entity uloží zmeny do databázy.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->age = 26;
$user->save(
    function ($result, $db, $debug) {
        echo "Používateľ uložený!\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

4.3.3. Vzťahy (hasOne, hasMany)

ORM podporuje vzťahy medzi tabuľkami:

• hasOne: Jeden k jednému.
• hasMany: Jeden k viacerým.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$posts = $user->hasMany('posts', 'user_id'); // Získa všetky príspevky používateľa
foreach ($posts as $post) {
    echo $post->title . "\n";
}

4.3.4. Lazy Loading a Collection metódy

Vzťahy sa načítajú lenivým spôsobom (lazy loading), pokiaľ ich explicitne nevyvoláte. Collection ponúka metódy ako filter(), map(), pluck().

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$names = $users->pluck('name'); // Získa pole mien
var_dump($names->all());

4.4. Transakcie

Databaser podporuje transakcie na zabezpečenie konzistencie dát.

4.4.1. transaction(), commit(), rollback()

Ručné ovládanie transakcií:

$DotApp->DB->transaction();
$DotApp->DB->q(function ($qb) {
    $qb->insert('users', ['name' => 'Jano']);
})->execute();
$DotApp->DB->commit(); // Alebo rollback() pri chybe

Automatická transakcia s transact():

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->insert('users', ['name' => 'Jano']);
    })->execute();
}, function ($result, $db, $debug) {
    echo "Transakcia úspešná!\n";
}, function ($error, $db, $debug) {
    echo "Chyba: {$error['error']}\n";
});

4.5. Debugovanie a práca s výstupom

Každá operácia vracia tri hlavné prvky:

• result: Výsledok dotazu (RAW: pole, ORM: objekty).
• db: Inštancia Databaseru pre ďalšie dotazy.
• debug: Pole s informáciami (napr. query, bindings).

Príklad debugovania:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        echo "SQL: " . $debug['query'] . "\n";
        echo "Bindings: " . implode(', ', $debug['bindings']) . "\n";
        var_dump($result);
    }
);

5. Praktické príklady

V tejto kapitole ukážeme praktické príklady použitia Databaseru v DotApp Frameworku. Zameriame sa na bežné scenáre, ako sú CRUD operácie (Create, Read, Update, Delete), pokročilé dotazy s join a subquery, práca s transakciami a ladenie chýb. Použijeme metódy insertedId() a affectedRows() namiesto priameho prístupu k $db->statement['execution_data'].

5.1. Základné CRUD operácie v RAW móde

Create (Vytvorenie):

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->insert('users', ['name' => 'Jano', 'age' => 25]);
})->execute(
    function ($result, $db, $debug) {
        $id = $db->insertedId(); // Získanie ID nového záznamu
        echo "Nový používateľ s ID: $id bol vytvorený.\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

Read (Čítanie):

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 20);
})->execute(
    function ($result, $db, $debug) {
        foreach ($result as $user) {
            echo "Meno: {$user['name']}, Vek: {$user['age']}\n";
        }
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

Update (Aktualizácia):

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->update('users')->set(['age' => 26])->where('name', '=', 'Jano');
})->execute(
    function ($result, $db, $debug) {
        $rows = $db->affectedRows(); // Počet ovplyvnených riadkov
        echo "$rows riadkov bolo aktualizovaných.\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

Delete (Odstránenie):

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->delete('users')->where('name', '=', 'Jano');
})->execute(
    function ($result, $db, $debug) {
        $rows = $db->affectedRows();
        echo "$rows riadkov bolo odstránených.\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

5.2. Základné CRUD operácie v ORM móde

Create:

$DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->insert('users', ['name' => 'Maria', 'age' => 30]);
})->execute(
    function ($result, $db, $debug) {
        $id = $db->insertedId();
        $user = $db->q(function ($qb) use ($id) {
            $qb->select('*', 'users')->where('id', '=', $id);
        })->first();
        echo "Vytvorený používateľ: {$user->name}\n";
    }
);

Read:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
foreach ($users as $user) {
    echo "Meno: {$user->name}, Vek: {$user->age}\n";
}

Update:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('name', '=', 'Maria');
})->first();
if ($user) {
    $user->age = 31;
    $user->save(
        function ($result, $db, $debug) {
            echo "Používateľ {$user->name} aktualizovaný.\n";
        },
        function ($error, $db, $debug) {
            echo "Chyba: {$error['error']}\n";
        }
    );
}

Delete:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('name', '=', 'Maria');
})->first();
if ($user) {
    $DotApp->DB->q(function ($qb) use ($user) {
        $qb->delete('users')->where('id', '=', $user->id);
    })->execute(
        function ($result, $db, $debug) {
            $rows = $db->affectedRows();
            echo "$rows riadkov bolo odstránených.\n";
        }
    );
}

5.3. Pokročilé príklady s join a subquery

join s viacerými tabuľkami:

$DotApp->DB->return('RAW')->q(function ($qb) {
    $qb->select('users.name, posts.title', 'users')
       ->join('posts', 'users.id', '=', 'posts.user_id')
       ->where('users.age', '>', 25);
})->execute(
    function ($result, $db, $debug) {
        foreach ($result as $row) {
            echo "Používateľ: {$row['name']}, Príspevok: {$row['title']}\n";
        }
    }
);

Subquery v ORM:

$DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')
       ->where('id', '=', function ($subQb) {
           $subQb->select('user_id', 'posts')
                  ->where('title', '=', 'Novinka');
       });
})->execute(
    function ($users, $db, $debug) {
        foreach ($users as $user) {
            echo "Používateľ s novinkou: {$user->name}\n";
        }
    }
);

5.4. Práca s transakciami

Automatická transakcia:

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->insert('users', ['name' => 'Peter', 'age' => 28]);
    })->execute();
    $id = $db->insertedId();
    $db->q(function ($qb) use ($id) {
        $qb->insert('posts', ['user_id' => $id, 'title' => 'Prvý príspevok']);
    })->execute();
}, function ($result, $db, $debug) {
    echo "Transakcia úspešná, ID používateľa: " . $db->insertedId() . "\n";
}, function ($error, $db, $debug) {
    echo "Chyba v transakcii: {$error['error']}\n";
});

Ručná transakcia:

$DotApp->DB->transaction();
$DotApp->DB->q(function ($qb) {
    $qb->insert('users', ['name' => 'Anna', 'age' => 22]);
})->execute(
    function ($result, $db, $debug) {
        $id = $db->insertedId();
        $db->q(function ($qb) use ($id) {
            $qb->insert('posts', ['user_id' => $id, 'title' => 'Test']);
        })->execute(
            function ($result, $db, $debug) {
                $db->commit();
                echo "Transakcia dokončená.\n";
            },
            function ($error, $db, $debug) {
                $db->rollback();
                echo "Rollback: {$error['error']}\n";
            }
        );
    }
);

5.5. Ladenie a riešenie chýb

Debugovanie dotazu:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        echo "SQL: " . $debug['query'] . "\n";
        echo "Bindings: " . implode(', ', $debug['bindings']) . "\n";
        echo "Počet riadkov: " . $db->affectedRows() . "\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']} (kód: {$error['errno']})\n";
        echo "SQL: " . $debug['query'] . "\n";
    }
);

Riešenie chyby:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'neexistujuca_tabuľka'); // Chybný dotaz
})->execute(
    function ($result, $db, $debug) {
        echo "Úspech\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
        // Možné ďalšie dotazy na opravu
        $db->q(function ($qb) {
            $qb->select('*', 'users'); // Skúsime inú tabuľku
        })->execute(
            function ($result, $db, $debug) {
                echo "Opravený dotaz úspešný.\n";
            }
        );
    }
);

6. Práca so SchemaBuilderom

SchemaBuilder je výkonný nástroj v Databaseri, ktorý slúži na definovanie a správu databázovej štruktúry. Umožňuje vytvárať, upravovať a odstraňovať tabuľky priamo z kódu bez nutnosti písania surových SQL príkazov na správu schémy. Je integrovaný do QueryBuildera a používa sa cez metódy ako createTable(), alterTable() a dropTable(). V tejto kapitole vysvetlíme jeho funkcie, vstupy a ukážeme praktické príklady.

6.1. Základné princípy SchemaBuildera

SchemaBuilder je trieda Dotsystems\App\Parts\SchemaBuilder, ktorá sa používa v callbacku metód schema() alebo priamo v createTable(), alterTable() a dropTable(). Jeho cieľom je poskytnúť programový spôsob definovania tabuliek, stĺpcov, indexov a cudzích kľúčov. Výsledné príkazy sú automaticky prevedené na SQL a vykonané cez aktívny driver (MySQLi alebo PDO).

Kľúčové vlastnosti:

• Reťaziteľné metódy: Podobne ako QueryBuilder, aj SchemaBuilder umožňuje reťazenie.
• Abstrakcia: Funguje nezávisle od databázového drivera, hoci niektoré špecifické funkcie môžu závisieť od databázového systému.
• Jednoduchosť: Umožňuje rýchlo definovať schému bez hlbokých znalostí SQL syntaxe.

6.2. Dostupné metódy SchemaBuildera

Tu je prehľad hlavných metód s vysvetlením a vstupmi:

6.2.1. id()

Pridá primárny kľúč typu BIGINT UNSIGNED AUTO_INCREMENT.

Syntax: id($name = 'id')

Parametre:

• $name: Názov stĺpca (predvolené 'id').

SQL ekvivalent: id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY

Príklad:

$schema->id(); // Vytvorí stĺpec `id`

6.2.2. string()

Pridá textový stĺpec typu VARCHAR.

Syntax: string($name, $length = 255, $nullable = false)

Parametre:

• $name: Názov stĺpca.
• $length: Dĺžka (predvolené 255).
• $nullable: Povolí NULL hodnoty (predvolené false).

SQL ekvivalent: VARCHAR(dĺžka) [NOT NULL | NULL]

Príklad:

$schema->string('name', 100, true); // `name` VARCHAR(100) NULL

6.2.3. integer()

Pridá číselný stĺpec typu INT.

Syntax: integer($name, $nullable = false)

Parametre:

• $name: Názov stĺpca.
• $nullable: Povolí NULL hodnoty (predvolené false).

SQL ekvivalent: INT [NOT NULL | NULL]

Príklad:

$schema->integer('age'); // `age` INT NOT NULL

6.2.4. timestamps()

Pridá stĺpce created_at a updated_at pre časové značky.

Syntax: timestamps()

SQL ekvivalent:

created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

Príklad:

$schema->timestamps();

6.2.5. foreign()

Pridá cudzí kľúč.

Syntax: foreign($column, $references = 'id', $on = null)

Parametre:

• $column: Stĺpec s cudzím kľúčom.
• $references: Referenčný stĺpec (predvolené 'id').
• $on: Referenčná tabuľka (ak nie je zadaná, odvodí sa z $column).

SQL ekvivalent: FOREIGN KEY (column) REFERENCES table (references) ON DELETE CASCADE

Príklad:

$schema->foreign('user_id', 'id', 'users'); // Cudzí kľúč na `users(id)`

6.2.6. index()

Pridá index na stĺpec.

Syntax: index($column)

Parametre:

• $column: Názov stĺpca.

SQL ekvivalent: INDEX (column)

Príklad:

$schema->index('name');

6.2.7. addColumn() (pre ALTER TABLE)

Pridá nový stĺpec do existujúcej tabuľky.

Syntax: addColumn($name, $type, $length = null, $nullable = false)

Parametre:

• $name: Názov stĺpca.
• $type: Typ (napr. VARCHAR, INT).
• $length: Dĺžka (voliteľné).
• $nullable: Povolí NULL (predvolené false).

SQL ekvivalent: ADD column type [length] [NOT NULL | NULL]

Príklad:

$schema->addColumn('email', 'VARCHAR', 150, true);

6.2.8. dropColumn() (pre ALTER TABLE)

Odstráni stĺpec z tabuľky.

Syntax: dropColumn($name)

Parametre:

• $name: Názov stĺpca.

SQL ekvivalent: DROP COLUMN column

Príklad:

$schema->dropColumn('email');

6.3. Použitie SchemaBuildera

SchemaBuilder sa používa v kombinácii s metódami QueryBuildera: createTable(), alterTable() a dropTable().

6.3.1. Vytvorenie tabuľky

Metóda createTable() vytvorí novú tabuľku.

Príklad:

$DotApp->DB->q(function ($qb) {
    $qb->createTable('users', function ($schema) {
        $schema->id();
        $schema->string('name', 50);
        $schema->integer('age', true);
        $schema->timestamps();
        $schema->index('name');
    });
})->execute(
    function ($result, $db, $debug) {
        echo "Tabuľka 'users' bola vytvorená.\n";
        echo "SQL: {$debug['query']}\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

Vygenerovaný SQL:

CREATE TABLE users (
    `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    `name` VARCHAR(50) NOT NULL,
    `age` INT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX (`name`)
)

6.3.2. Úprava tabuľky

Metóda alterTable() upraví existujúcu tabuľku.

Príklad:

$DotApp->DB->q(function ($qb) {
    $qb->alterTable('users', function ($schema) {
        $schema->addColumn('email', 'VARCHAR', 100, true);
        $schema->foreign('user_id', 'id', 'users');
        $schema->dropColumn('age');
    });
})->execute(
    function ($result, $db, $debug) {
        echo "Tabuľka 'users' bola upravená.\n";
        echo "SQL: {$debug['query']}\n";
    }
);

Vygenerovaný SQL:

ALTER TABLE users 
    ADD `email` VARCHAR(100) NULL,
    ADD FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE,
    DROP COLUMN `age`

6.3.3. Odstránenie tabuľky

Metóda dropTable() odstráni tabuľku.

Príklad:

$DotApp->DB->q(function ($qb) {
    $qb->dropTable('users');
})->execute(
    function ($result, $db, $debug) {
        echo "Tabuľka 'users' bola odstránená.\n";
    }
);

Vygenerovaný SQL:

DROP TABLE users

6.4. Pokročilé príklady

Vytvorenie tabuľky s cudzími kľúčmi:

$DotApp->DB->q(function ($qb) {
    $qb->createTable('posts', function ($schema) {
        $schema->id();
        $schema->string('title', 200);
        $schema->integer('user_id');
        $schema->foreign('user_id', 'id', 'users');
        $schema->timestamps();
    });
})->execute(
    function ($result, $db, $debug) {
        echo "Tabuľka 'posts' vytvorená.\n";
    }
);

Hromadná migrácia:

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->createTable('users', function ($schema) {
            $schema->id();
            $schema->string('name');
        });
    })->execute();
    $db->q(function ($qb) {
        $qb->createTable('posts', function ($schema) {
            $schema->id();
            $schema->integer('user_id');
            $schema->foreign('user_id');
        });
    })->execute();
}, function ($result, $db, $debug) {
    echo "Migrácia úspešná.\n";
});

6.5. Poznámky a obmedzenia

Kompatibilita: Niektoré funkcie (napr. ON DELETE CASCADE) nemusia fungovať rovnako vo všetkých databázach (napr. SQLite má obmedzenia).

Transakcie: Pri väčších zmenách schémy používajte transact() na zaistenie konzistencie.

Debugovanie: Vždy kontrolujte $debug['query'] na overenie vygenerovaného SQL.

7. CacheDriverInterface

Databaser v DotApp Frameworku podporuje integráciu s cachingom, čo umožňuje ukladať výsledky dotazov a zvyšovať výkon aplikácie pri opakovaných požiadavkách na rovnaké dáta. Aby bolo možné caching využiť, je potrebné implementovať rozhranie CacheDriverInterface, ktoré definuje štandardné metódy pre prácu s cache. V tejto kapitole vysvetlíme, čo toto rozhranie obsahuje, aké metódy musí cache driver podporovať, a ukážeme, ako ho používať s Databaserom.

7.1. Čo je CacheDriverInterface?

CacheDriverInterface je rozhranie, ktoré určuje, ako má vyzerať driver pre ukladanie a načítanie dát z cache. Databaser ho používa na komunikáciu s ľubovoľným caching systémom (napr. Memcached, Redis, súborový systém), pričom logiku ukladania a správy cache si implementuje používateľ. Po nastavení cache drivera cez metódu cache() sa Databaser automaticky pokúsi načítavať výsledky z cache pred vykonaním dotazu a ukladať nové výsledky po jeho úspešnom dokončení.

Výhody:

• Zníženie zaťaženia databázy.
• Rýchlejší prístup k často používaným dátam.
• Flexibilita – môžete použiť akýkoľvek caching systém.

7.2. Zloženie CacheDriverInterface

Rozhranie CacheDriverInterface definuje štyri povinné metódy, ktoré musí každý cache driver implementovať:

interface CacheDriverInterface {
    public function get($key);
    public function set($key, $value, $ttl = null);
    public function delete($key);
    public function deleteKeys($pattern);
}

7.2.1. get($key)

Načíta hodnotu z cache na základe kľúča.

Parameter:

• $key: Reťazec – unikátny kľúč pre uložené dáta.

Návratová hodnota: Uložená hodnota alebo null, ak kľúč neexistuje.

Účel: Databaser volá túto metódu, aby skontroloval, či už výsledok dotazu existuje v cache.

7.2.2. set($key, $value, $ttl = null)

Uloží hodnotu do cache s daným kľúčom.

Parametre:

• $key: Reťazec – kľúč pre uloženie.
• $value: Dáta na uloženie (môžu byť pole, objekt atď.).
• $ttl: Čas životnosti v sekundách (voliteľné, null znamená bez expirácie).

Návratová hodnota: Žiadna (alebo true/false podľa implementácie).

Účel: Po úspešnom vykonaní dotazu Databaser ukladá výsledok do cache.

7.2.3. delete($key)

Odstráni konkrétny kľúč z cache.

Parameter:

• $key: Reťazec – kľúč na odstránenie.

Návratová hodnota: Žiadna (alebo true/false).

Účel: Používa sa na explicitné mazanie konkrétneho záznamu z cache.

7.2.4. deleteKeys($pattern)

Odstráni viacero kľúčov na základe vzoru.

Parameter:

• $pattern: Reťazec – vzor kľúčov (napr. "users:*").

Návratová hodnota: Žiadna (alebo počet odstránených kľúčov).

Účel: Databaser volá túto metódu pri aktualizácii dát (napr. save() v ORM), aby invalidoval súvisiace cache záznamy.

7.3. Implementácia vlastného CacheDrivera

Tu je príklad jednoduchej implementácie cache drivera využívajúceho súborový systém:

class FileCacheDriver implements CacheDriverInterface {
    private $cacheDir;

    public function __construct($cacheDir = '/tmp/cache') {
        $this->cacheDir = $cacheDir;
        if (!is_dir($cacheDir)) {
            mkdir($cacheDir, 0777, true);
        }
    }

    public function get($key) {
        $file = $this->cacheDir . '/' . md5($key);
        if (file_exists($file)) {
            $data = unserialize(file_get_contents($file));
            if ($data['expires'] === null || $data['expires'] > time()) {
                return $data['value'];
            }
            unlink($file); // Expirované, odstránime
        }
        return null;
    }

    public function set($key, $value, $ttl = null) {
        $file = $this->cacheDir . '/' . md5($key);
        $expires = $ttl ? time() + $ttl : null;
        $data = ['value' => $value, 'expires' => $expires];
        file_put_contents($file, serialize($data));
        return true;
    }

    public function delete($key) {
        $file = $this->cacheDir . '/' . md5($key);
        if (file_exists($file)) {
            unlink($file);
            return true;
        }
        return false;
    }

    public function deleteKeys($pattern) {
        $count = 0;
        foreach (glob($this->cacheDir . '/*') as $file) {
            $key = basename($file);
            if (fnmatch($pattern, $key)) {
                unlink($file);
                $count++;
            }
        }
        return $count;
    }
}

Vysvetlenie:

• get(): Načíta dáta zo súboru, ak neexpirovali.
• set(): Uloží dáta do súboru s voliteľným TTL.
• delete(): Odstráni konkrétny súbor.
• deleteKeys(): Odstráni súbory podľa vzoru (používa fnmatch).

7.4. Použitie CacheDrivera s Databaserom

Po implementácii cache drivera ho nastavíte pomocou metódy cache():

$cacheDriver = new FileCacheDriver('/tmp/myapp_cache');
$DotApp->DB->cache($cacheDriver);

// Príklad dotazu s cachingom
$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        echo "Výsledky (z cache alebo DB):\n";
        var_dump($result);
    }
);

Ako to funguje:

• Databaser vygeneruje kľúč (napr. users:RAW:hash_dotazu).
• Skontroluje cache cez get(). Ak nájde platné dáta, vráti ich bez dotazu na DB.
• Ak dáta nie sú v cache, vykoná dotaz a uloží výsledok cez set() s TTL (predvolené 3600 sekúnd).
• Pri aktualizácii (napr. save() v ORM) invaliduje súvisiace kľúče cez deleteKeys().

7.5. Príklad s pokročilým cachingom

Caching s ORM a invalidáciou:

$cacheDriver = new FileCacheDriver();
$DotApp->DB->cache($cacheDriver);

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();

$user = $users->first();
$user->age = 40;
$user->save(
    function ($result, $db, $debug) {
        echo "Používateľ uložený, cache invalidovaná.\n";
    }
);

Čo sa deje:

• Prvý dotaz uloží Collection do cache.
• Pri save() sa zavolá deleteKeys("users:ORM:*"), čím sa invalidujú všetky ORM záznamy pre users.

7.6. Poznámky a tipy

TTL: Nastavte rozumnú hodnotu TTL (napr. 3600 sekúnd) podľa potreby aplikácie.

Vzory kľúčov: Databaser používa formát tabuľka:typ:hash, takže vzory ako "users:*" sú efektívne.

Výkon: Pre produkčné prostredie zvážte rýchle cache systémy ako Redis namiesto súborov.

Testovanie: Overte, či deleteKeys() správne invaliduje cache, aby ste predišli zastaraným dátam.

8. Práca s Entity

Entity je základnou stavebnou jednotkou ORM (Object-Relational Mapping) v Databaseri, ktorá reprezentuje jeden riadok v databázovej tabuľke ako objekt. Umožňuje jednoduchú manipuláciu s dátami, definovanie vzťahov a validáciu. Táto kapitola podrobne vysvetlí jej štruktúru, všetky dostupné metódy a ukáže ich praktické použitie.

8.1. Čo je Entity?

Entity je dynamicky generovaný objekt, ktorý mapuje riadok tabuľky na objekt s atribútmi zodpovedajúcimi stĺpcom. Vytvára sa automaticky, keď nastavíte typ návratu na 'ORM' a vykonáte dotaz vracajúci jeden riadok (napr. cez first()) alebo viac riadkov (v Collection cez all()). Poskytuje objektovo-orientovaný prístup k dátam, čím zjednodušuje prácu s databázou.

Kľúčové vlastnosti:

• Atribúty: Prístup k stĺpcom tabuľky ako k vlastnostiam objektu (napr. $entity->name).
• Vzťahy: Podpora hasOne, hasMany, morphOne, morphMany pre prepojenie tabuliek.
• Validácia: Možnosť definovať pravidlá pred uložením dát.
• Lazy a Eager Loading: Vzťahy sa načítajú lenivo, s možnosťou prednačítania.

8.2. Zloženie Entity

Entity je anonymná trieda definovaná v createMysqliDriver() alebo createPdoDriver(). Obsahuje tieto hlavné prvky:

Súkromné atribúty:

• $attributes: Pole aktuálnych hodnôt stĺpcov (napr. ['id' => 1, 'name' => 'Jano']).
• $originalAttributes: Pôvodné hodnoty pre sledovanie zmien.
• $db: Referencia na inštanciu Databaseru.
• $table: Názov tabuľky (odvodený z dotazu alebo odhadnutý).
• $primaryKey: Primárny kľúč (predvolené 'id').
• $rules: Pole validačných pravidiel.
• $relations: Pole načítaných vzťahov (napr. hasMany).
• $with: Pole vzťahov pre eager loading.
• $morphRelations: Pole polymorfných vzťahov.

Metódy:

• with($relations): Nastaví vzťahy pre eager loading.
• loadRelations(): Načíta vzťahy definované v $with.
• setPrimaryKey($key): Nastaví primárny kľúč.
• setRules(array $rules): Definuje validačné pravidlá.
• save($callbackOk = null, $callbackError = null): Uloží zmeny do databázy.
• hasOne($relatedTable, $foreignKey, $localKey = null, $callback = null): Definuje vzťah jeden k jednému.
• hasMany($relatedTable, $foreignKey, $localKey = null, $callback = null): Definuje vzťah jeden k viacerým.
• morphOne($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null): Definuje polymorfný vzťah jeden k jednému.
• morphMany($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null): Definuje polymorfný vzťah jeden k viacerým.
• toArray(): Vráti atribúty ako pole.

8.3. Základné použitie Entity

Získanie Entity:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();

echo $user->name; // Prístup k atribútu
$user->age = 26;  // Zmena atribútu
$user->save();    // Uloženie zmien

8.4. Podrobný prehľad metód Entity

Tu je detailný popis všetkých verejne dostupných metód Entity:

8.4.1. with($relations)

Nastaví vzťahy, ktoré sa majú prednačítať (eager loading) namiesto lenivého načítania (lazy loading).

Syntax: with($relations)

Parameter:

• $relations: Reťazec alebo pole názvov vzťahov (napr. 'hasMany:posts' alebo ['hasOne:profile', 'hasMany:posts']).

Návratová hodnota: $this (reťaziteľné).

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->with('hasMany:posts');
$user->loadRelations();
foreach ($user->hasMany('posts', 'user_id') as $post) {
    echo $post->title . "\n";
}

8.4.2. loadRelations()

Načíta všetky vzťahy definované v $with.

Syntax: loadRelations()

Návratová hodnota: Žiadna.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->with(['hasOne:profile', 'hasMany:posts']);
$user->loadRelations();
echo $user->hasOne('profiles', 'user_id')->bio;

8.4.3. setPrimaryKey($key)

Nastaví primárny kľúč namiesto predvoleného 'id'.

Syntax: setPrimaryKey($key)

Parameter:

• $key: Reťazec – názov stĺpca (napr. 'user_id').

Návratová hodnota: $this.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('user_id', '=', 1);
})->first();
$user->setPrimaryKey('user_id');
$user->user_id = 2;
$user->save();

8.4.4. setRules(array $rules)

Definuje validačné pravidlá pre atribúty pred uložením.

Syntax: setRules(array $rules)

Parameter:

• $rules: Asociatívne pole (napr. 'name' => ['required', 'string', 'max:50']).

Podporované pravidlá: required, integer, string, min:X, max:X, email.

Návratová hodnota: $this.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->setRules([
    'name' => ['required', 'string', 'max:50'],
    'age' => ['integer', 'min:18']
]);
$user->name = '';
$user->save(
    null,
    function ($error, $db, $debug) {
        echo "Validácia zlyhala: {$error['error']}\n";
    }
);

8.4.5. save($callbackOk = null, $callbackError = null)

Uloží zmeny v Entity do databázy (vkladá nový záznam alebo aktualizuje existujúci).

Syntax: save($callbackOk = null, $callbackError = null)

Parametre:

• $callbackOk: Callback pri úspechu (function ($result, $db, $debug)).
• $callbackError: Callback pri chybe (function ($error, $db, $debug)).

Návratová hodnota: Žiadna.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->age = 27;
$user->save(
    function ($result, $db, $debug) {
        echo "Používateľ uložený, SQL: {$debug['query']}\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

Vkladanie nového záznamu:

$user = $DotApp->DB->newEntity();
$user->table('users'); // Nastavenie tabuľky
$user->name = 'Maria';
$user->age = 30;
$user->save(
    function ($result, $db, $debug) {
        echo "Nový používateľ s ID: {$db->insertedId()} vytvorený.\n";
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

8.4.6. hasOne($relatedTable, $foreignKey, $localKey = null, $callback = null)

Definuje vzťah jeden k jednému.

Syntax: hasOne($relatedTable, $foreignKey, $localKey = null, $callback = null)

Parametre:

• $relatedTable: Názov súvisiacej tabuľky.
• $foreignKey: Cudzí kľúč v súvisiacej tabuľke.
• $localKey: Lokálny kľúč (predvolené 'id').
• $callback: Closure na úpravu dotazu.

Návratová hodnota: Entity alebo null.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$profile = $user->hasOne('profiles', 'user_id', 'id', function ($qb) {
    $qb->where('active', '=', 1);
});
echo $profile->bio;

8.4.7. hasMany($relatedTable, $foreignKey, $localKey = null, $callback = null)

Definuje vzťah jeden k viacerým.

Syntax: hasMany($relatedTable, $foreignKey, $localKey = null, $callback = null)

Parametre: Rovnaké ako hasOne.

Návratová hodnota: Pole Entity objektov.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$posts = $user->hasMany('posts', 'user_id', null, function ($qb) {
    $qb->orderBy('created_at', 'DESC')->limit(2);
});
foreach ($posts as $post) {
    echo $post->title . "\n";
}

8.4.8. morphOne($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null)

Definuje polymorfný vzťah jeden k jednému.

Syntax: morphOne($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null)

Parametre:

• $typeField: Stĺpec s typom (napr. 'imageable_type').
• $idField: Stĺpec s ID (napr. 'imageable_id').
• $typeValue: Hodnota typu (napr. 'User').

Návratová hodnota: Entity alebo null.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$image = $user->morphOne('images', 'imageable_type', 'imageable_id', 'User');
echo $image->url;

8.4.9. morphMany($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null)

Definuje polymorfný vzťah jeden k viacerým.

Syntax: morphMany($relatedTable, $typeField, $idField, $typeValue, $localKey = null, $callback = null)

Parametre: Rovnaké ako morphOne.

Návratová hodnota: Pole Entity objektov.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$images = $user->morphMany('images', 'imageable_type', 'imageable_id', 'User');
foreach ($images as $image) {
    echo $image->url . "\n";
}

8.4.10. toArray()

Vráti atribúty Entity ako asociatívne pole.

Syntax: toArray()

Návratová hodnota: Pole s aktuálnymi hodnotami $attributes.

Príklad:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$data = $user->toArray();
var_dump($data); // ['id' => 1, 'name' => 'Jano', 'age' => 26]

8.5. Praktické príklady

Úprava a uloženie s validáciou:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->setRules(['name' => 'required', 'age' => 'integer']);
$user->name = 'Peter';
$user->age = 28;
$user->save(
    function ($result, $db, $debug) {
        echo "Používateľ uložený: {$user->name}, vek: {$user->age}\n";
    }
);

Eager Loading viacerých vzťahov:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first()->with(['hasOne:profile', 'hasMany:posts']);
$user->loadRelations();
echo $user->hasOne('profiles', 'user_id')->bio . "\n";
foreach ($user->hasMany('posts', 'user_id') as $post) {
    echo $post->title . "\n";
}

Polymorfný vzťah s filtrom:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$recentImages = $user->morphMany('images', 'imageable_type', 'imageable_id', 'User', null, function ($qb) {
    $qb->orderBy('created_at', 'DESC')->limit(3);
});
foreach ($recentImages as $image) {
    echo "Najnovší obrázok: {$image->url}\n";
}

8.6. Poznámky

Lazy vs. Eager Loading: Pre časté prístupy k vzťahom vždy používajte with() a loadRelations(), aby ste znížili počet dotazov.

Validácia: Pravidlá kontrolujte pred save(), inak sa uložia nevalidné dáta.

Prispôsobenie: Callbacky v save() a vzťahoch umožňujú flexibilitu bez potreby rozširovania triedy.

9. Práca s Collection

Collection je trieda v ORM (Object-Relational Mapping) vrstve Databaseru, ktorá slúži na správu viacerých Entity objektov – teda súbor riadkov z databázy. Umožňuje iteráciu, filtrovanie, transformáciu a hromadné operácie nad dátami. Táto kapitola podrobne vysvetlí jej štruktúru, všetky dostupné metódy a ukáže ich praktické použitie s HTML výstupmi.

9.1. Čo je Collection?

Collection je dynamicky generovaný objekt, ktorý uchováva zoznam Entity objektov vrátených z dotazu, keď nastavíte typ návratu na 'ORM' a použijete metódu all() alebo získate vzťah typu hasMany/morphMany. Poskytuje objektovo-orientovaný prístup k viacerým záznamom naraz, čím zjednodušuje manipuláciu s dátami.

Kľúčové vlastnosti:

• Iterovateľnosť: Implementuje IteratorAggregate pre jednoduchú iteráciu cez foreach.
• Hromadné operácie: Podpora metód ako saveAll() na uloženie zmien vo všetkých entitách.
• Filtrovanie a transformácia: Metódy ako filter(), map(), pluck() na prácu s dátami.
• Vzťahy: Možnosť eager loadingu vzťahov pre optimalizáciu dotazov.

9.2. Zloženie Collection

Collection je trieda definovaná v Databaseri. Obsahuje tieto hlavné prvky:

Súkromné atribúty:

• $items: Pole Entity objektov (napr. [0 => Entity, 1 => Entity]).
• $db: Referencia na inštanciu Databaseru.
• $with: Pole vzťahov pre eager loading (napr. ['hasMany:posts']).

Metódy:

• with($relations): Nastaví vzťahy pre eager loading.
• loadRelations(): Načíta vzťahy definované v $with.
• all(): Vráti pole všetkých Entity objektov.
• first(): Vráti prvú Entity alebo null.
• filter($callback): Filtruje entity podľa podmienky.
• map($callback): Transformuje entity pomocou callbacku.
• pluck($field): Extrahuje hodnoty konkrétneho stĺpca.
• saveAll($callbackOk = null, $callbackError = null): Uloží zmeny vo všetkých entitách.
• toArray(): Vráti kolekciu ako pole polí.
• count(): Vráti počet entít v kolekcii.

9.3. Základné použitie Collection

Získanie Collection:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();

foreach ($users as $user) {
    echo "Meno: {$user->name}, Vek: {$user->age}\n";
}
    

9.4. Podrobný prehľad metód Collection

Tu je detailný popis všetkých verejne dostupných metód Collection:

9.4.1. with($relations)

Nastaví vzťahy, ktoré sa majú prednačítať (eager loading) namiesto lenivého načítania.

Syntax: with($relations)

Parameter:

• $relations: Reťazec alebo pole názvov vzťahov (napr. 'hasMany:posts' alebo ['hasOne:profile', 'hasMany:posts']).

Návratová hodnota: $this (reťaziteľné).

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all()->with('hasMany:posts');
$users->loadRelations();

$html = "<table border='1'><tr><th>Meno</th><th>Príspevky</th></tr>";
foreach ($users as $user) {
    $posts = implode(', ', array_map(fn($post) => $post->title, $user->hasMany('posts', 'user_id')));
    $html .= "<tr><td>{$user->name}</td><td>{$posts}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>Meno</th><th>Príspevky</th></tr>
    <tr><td>Jano</td><td>Príspevok 1, Príspevok 2</td></tr>
    <tr><td>Maria</td><td>Novinka</td></tr>
</table>
    

9.4.2. loadRelations()

Načíta všetky vzťahy definované v $with.

Syntax: loadRelations()

Návratová hodnota: Žiadna.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all()->with(['hasOne:profile']);
$users->loadRelations();

$html = "<ul>";
foreach ($users as $user) {
    $html .= "<li>{$user->name} - Profil: {$user->hasOne('profiles', 'user_id')->bio}</li>";
}
$html .= "</ul>";
echo $html;
    

Výstup:

<ul>
    <li>Jano - Profil: Milovník technológií</li>
    <li>Maria - Profil: Cestovateľka</li>
</ul>
    

9.4.3. all()

Vráti pole všetkých Entity objektov v kolekcii.

Syntax: all()

Návratová hodnota: Pole Entity objektov.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$allUsers = $users->all();

$html = "<table border='1'><tr><th>ID</th><th>Meno</th></tr>";
foreach ($allUsers as $user) {
    $html .= "<tr><td>{$user->id}</td><td>{$user->name}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>ID</th><th>Meno</th></tr>
    <tr><td>1</td><td>Jano</td></tr>
    <tr><td>2</td><td>Maria</td></tr>
</table>
    

9.4.4. first()

Vráti prvú Entity z kolekcie alebo null, ak je prázdna.

Syntax: first()

Návratová hodnota: Entity alebo null.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$firstUser = $users->first();

$html = $firstUser ? "<p>Prvý používateľ: {$firstUser->name}</p>" : "<p>Žiadni používatelia</p>";
echo $html;
    

Výstup:

<p>Prvý používateľ: Jano</p>
    

9.4.5. filter($callback)

Filtruje kolekciu na základe podmienky definovanej v callbacku.

Syntax: filter($callback)

Parameter:

• $callback: Funkcia (function ($entity)) vracajúca true pre zachovanie položky.

Návratová hodnota: Nová inštancia Collection.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$adults = $users->filter(function ($user) {
    return $user->age >= 18;
});

$html = "<ul>";
foreach ($adults as $adult) {
    $html .= "<li>{$adult->name} ({$adult->age})</li>";
}
$html .= "</ul>";
echo $html;
    

Výstup:

<ul>
    <li>Jano (25)</li>
    <li>Maria (30)</li>
</ul>
    

9.4.6. map($callback)

Transformuje každú Entity v kolekcii pomocou callbacku.

Syntax: map($callback)

Parameter:

• $callback: Funkcia (function ($entity)) vracajúca upravenú Entity.

Návratová hodnota: Nová inštancia Collection.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$updated = $users->map(function ($user) {
    $user->age += 1;
    return $user;
});

$html = "<table border='1'><tr><th>Meno</th><th>Nový vek</th></tr>";
foreach ($updated as $user) {
    $html .= "<tr><td>{$user->name}</td><td>{$user->age}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>Meno</th><th>Nový vek</th></tr>
    <tr><td>Jano</td><td>26</td></tr>
    <tr><td>Maria</td><td>31</td></tr>
</table>
    

9.4.7. pluck($field)

Extrahuje hodnoty konkrétneho atribútu zo všetkých Entity v kolekcii.

Syntax: pluck($field)

Parameter:

• $field: Názov atribútu (napr. 'name').

Návratová hodnota: Pole hodnôt.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$names = $users->pluck('name');

$html = "<ul>";
foreach ($names as $name) {
    $html .= "<li>{$name}</li>";
}
$html .= "</ul>";
echo $html;
    

Výstup:

<ul>
    <li>Jano</li>
    <li>Maria</li>
</ul>
    

9.4.8. saveAll($callbackOk = null, $callbackError = null)

Uloží zmeny vo všetkých Entity v kolekcii do databázy.

Syntax: saveAll($callbackOk = null, $callbackError = null)

Parametre:

• $callbackOk: Callback pri úspechu (function ($result, $db, $debug)).
• $callbackError: Callback pri chybe (function ($error, $db, $debug)).

Návratová hodnota: Žiadna.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$updated = $users->map(function ($user) {
    $user->age += 1;
    return $user;
});
$updated->saveAll(
    function ($result, $db, $debug) {
        $html = "<p>Zmeny uložené, ovplyvnených riadkov: {$db->affectedRows()}</p>";
        echo $html;
    },
    function ($error, $db, $debug) {
        echo "Chyba: {$error['error']}\n";
    }
);

$html = "<table border='1'><tr><th>Meno</th><th>Nový vek</th></tr>";
foreach ($updated as $user) {
    $html .= "<tr><td>{$user->name}</td><td>{$user->age}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<p>Zmeny uložené, ovplyvnených riadkov: 2</p>
<table border="1">
    <tr><th>Meno</th><th>Nový vek</th></tr>
    <tr><td>Jano</td><td>26</td></tr>
    <tr><td>Maria</td><td>31</td></tr>
</table>
    

9.4.9. toArray()

Vráti kolekciu ako pole asociatívnych polí.

Syntax: toArray()

Návratová hodnota: Pole polí.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$data = $users->toArray();

$html = "<table border='1'><tr><th>ID</th><th>Meno</th><th>Vek</th></tr>";
foreach ($data as $user) {
    $html .= "<tr><td>{$user['id']}</td><td>{$user['name']}</td><td>{$user['age']}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>ID</th><th>Meno</th><th>Vek</th></tr>
    <tr><td>1</td><td>Jano</td><td>25</td></tr>
    <tr><td>2</td><td>Maria</td><td>30</td></tr>
</table>
    

9.4.10. count()

Vráti počet Entity objektov v kolekcii.

Syntax: count()

Návratová hodnota: Celé číslo.

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$count = $users->count();

$html = "<p>Počet používateľov: {$count}</p>";
echo $html;
    

Výstup:

<p>Počet používateľov: 2</p>
    

9.5. Praktické príklady

Filtrovanie a hromadné uloženie:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$adults = $users->filter(function ($user) {
    return $user->age >= 18;
})->map(function ($user) {
    $user->status = 'Dospelý';
    return $user;
})->saveAll(
    function ($result, $db, $debug) {
        echo "Dospelí používatelia aktualizovaní.\n";
    }
);

$html = "<table border='1'><tr><th>Meno</th><th>Stav</th></tr>";
foreach ($adults as $user) {
    $html .= "<tr><td>{$user->name}</td><td>{$user->status}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>Meno</th><th>Stav</th></tr>
    <tr><td>Jano</td><td>Dospelý</td></tr>
    <tr><td>Maria</td><td>Dospelý</td></tr>
</table>
    

Eager Loading vzťahov:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all()->with(['hasMany:posts', 'hasOne:profile']);
$users->loadRelations();

$html = "<table border='1'><tr><th>Meno</th><th>Profil</th><th>Príspevky</th></tr>";
foreach ($users as $user) {
    $posts = implode(', ', array_map(fn($post) => $post->title, $user->hasMany('posts', 'user_id')));
    $html .= "<tr><td>{$user->name}</td><td>{$user->hasOne('profiles', 'user_id')->bio}</td><td>{$posts}</td></tr>";
}
$html .= "</table>";
echo $html;
    

Výstup:

<table border="1">
    <tr><th>Meno</th><th>Profil</th><th>Príspevky</th></tr>
    <tr><td>Jano</td><td>Milovník technológií</td><td>Príspevok 1, Príspevok 2</td></tr>
    <tr><td>Maria</td><td>Cestovateľka</td><td>Novinka</td></tr>
</table>
    

9.6. Poznámky

• Výkon: Pri veľkých kolekciách zvážte použitie limit() v dotaze, aby ste znížili zaťaženie pamäte.
• Eager Loading: Používajte with() a loadRelations() na zníženie počtu dotazov pri práci so vzťahmi.
• Flexibilita: Reťazenie metód ako filter() a map() umožňuje plynulé spracovanie dát.

10. Migrácie

Migrácie v Databaseri umožňujú definovať a spravovať štruktúru databázy pomocou kódu. Používajú sa na vytváranie, úpravu alebo odstraňovanie tabuliek a ich stĺpcov, pričom podporujú transakcie pre hromadné operácie. Táto kapitola podrobne popisuje prácu s migráciami, vrátane ich definície, dostupných metód a praktických príkladov.

10.2. Čo sú migrácie?

Migrácie sú nástroj na správu databázovej schémy, ktorý umožňuje programovo definovať štruktúru tabuliek a ich vzťahov. V Databaseri sa migrácie realizujú cez SchemaBuilder a môžu byť zabalené do transakcií pomocou metódy transact(). Hlavné výhody:

• Automatizácia: Zmena databázy je súčasťou kódu a môže byť verzionovaná.
• Transakcie: Hromadné operácie sú bezpečné a reverzibilné pri chybe.
• Multiplatformovosť: Podpora rôznych driverov (MySQLi, PDO) s prispôsobením syntaxe.

10.3. Základné princípy migrácií

Migrácie v Databaseri fungujú na základe týchto princípov:

• SchemaBuilder: Používa sa na definovanie tabuliek a stĺpcov (napr. id(), string(), foreign()).
• Metóda migrate(): Slúži na spúšťanie migrácií ('up' pre vytvorenie, 'down' pre rollback).
• Transakcie: Hromadné migrácie sa vykonávajú cez transact(), kde sa viaceré operácie spúšťajú ako jeden celok.
• Podpora driverov: MySQLi aj PDO prispôsobujú syntax podľa typu databázy (napr. MySQL, PostgreSQL, SQLite).

10.4. Použitie migrácií

Základné použitie migrácií zahŕňa definovanie štruktúry databázy a jej aplikáciu. Príklad vytvorenia tabuľky:

$DotApp->DB->schema(function ($schema) {
    $schema->createTable('users', function ($table) {
        $table->id();
        $table->string('name');
    });
}, function ($result, $db, $debug) {
    echo "Tabuľka 'users' bola úspešne vytvorená.\n";
});
    

Výstup:

Tabuľka 'users' bola úspešne vytvorená.
    

Hromadná migrácia s transakciou (viac tabuliek):

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->createTable('users', function ($schema) {
            $schema->id();
            $schema->string('name');
        });
    })->execute();
    $db->q(function ($qb) {
        $qb->createTable('posts', function ($schema) {
            $schema->id();
            $schema->integer('user_id');
            $schema->foreign('user_id');
        });
    })->execute();
}, function ($result, $db, $debug) {
    echo "Migrácia úspešná.\n";
});
    

Výstup:

Migrácia úspešná.
    

10.5. Dostupné metódy pre migrácie

Databaser ponúka nasledujúce metódy pre prácu s migráciami:

10.5.1. schema($callback, $success, $error)

Definuje a vykoná jednu migračnú operáciu (napr. vytvorenie tabuľky).

Syntax: schema(callable $callback, callable $success = null, callable $error = null)

Parametre:

• $callback: Closure, ktorá definuje operáciu cez SchemaBuilder.
• $success: Callback pri úspechu.
• $error: Callback pri chybe.

Príklad:

$DotApp->DB->schema(function ($schema) {
    $schema->createTable('users', function ($table) {
        $table->id();
        $table->string('email', 100);
    });
}, function ($result, $db, $debug) {
    echo "<p>Tabuľka vytvorená.</p>";
});
    

Výstup:

<p>Tabuľka vytvorená.</p>
    

10.5.2. migrate($direction, $success, $error)

Spúšťa migráciu v smere 'up' (vytvorenie) alebo 'down' (odstránenie).

Syntax: migrate(string $direction = 'up', callable $success = null, callable $error = null)

Parametre:

• $direction: 'up' alebo 'down'.
• $success: Callback pri úspechu.
• $error: Callback pri chybe.

Príklad:

$DotApp->DB->migrate('up', function ($result, $db, $debug) {
    echo "<p>Migrácia 'up' dokončená.</p>";
});
    

Výstup:

<p>Migrácia 'up' dokončená.</p>
    

10.5.3. transact($operations, $success, $error)

Spúšťa hromadnú migráciu v rámci transakcie.

Syntax: transact(callable $operations, callable $success = null, callable $error = null)

Parametre:

• $operations: Closure s viacerými migračnými operáciami.
• $success: Callback pri úspechu.
• $error: Callback pri chybe.

Príklad:

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->createTable('comments', function ($schema) {
            $schema->id();
            $schema->integer('post_id');
        });
    })->execute();
}, function ($result, $db, $debug) {
    echo "<p>Hromadná migrácia úspešná.</p>";
});
    

Výstup:

<p>Hromadná migrácia úspešná.</p>
    

10.5.4. SchemaBuilder::createTable($table, $callback)

Vytvorí novú tabuľku s definovanou štruktúrou.

Syntax: createTable(string $table, callable $callback)

Príklad:

$DotApp->DB->schema(function ($schema) {
    $schema->createTable('products', function ($table) {
        $table->id();
        $table->string('name');
        $table->decimal('price', 8, 2);
    });
});
    

10.5.5. SchemaBuilder::alterTable($table, $callback)

Upraví existujúcu tabuľku (napr. pridá stĺpec).

Syntax: alterTable(string $table, callable $callback)

Príklad:

$DotApp->DB->schema(function ($schema) {
    $schema->alterTable('users', function ($table) {
        $table->addColumn('age', 'INT', null, true);
    });
});
    

10.5.6. SchemaBuilder::dropTable($table)

Odstráni tabuľku.

Syntax: dropTable(string $table)

Príklad:

$DotApp->DB->schema(function ($schema) {
    $schema->dropTable('users');
});
    

10.6. Praktické príklady

Vytvorenie tabuliek s cudzím kľúčom:

$DotApp->DB->transact(function ($db) {
    $db->q(function ($qb) {
        $qb->createTable('users', function ($schema) {
            $schema->id();
            $schema->string('username');
        });
    })->execute();
    $db->q(function ($qb) {
        $qb->createTable('posts', function ($schema) {
            $schema->id();
            $schema->string('title');
            $schema->integer('user_id');
            $schema->foreign('user_id', 'id', 'users');
        });
    })->execute();
}, function ($result, $db, $debug) {
    echo "<p>Migrácia tabuliek dokončená.</p>";
});
    

Výstup:

<p>Migrácia tabuliek dokončená.</p>
    

Úprava tabuľky (pridanie stĺpca):

$DotApp->DB->schema(function ($schema) {
    $schema->alterTable('users', function ($table) {
        $table->string('email', 100);
    });
}, function ($result, $db, $debug) {
    echo "<p>Email stĺpec pridaný.</p>";
});
    

Výstup:

<p>Email stĺpec pridaný.</p>
    

Rollback migrácie:

$DotApp->DB->migrate('down', function ($result, $db, $debug) {
    echo "<p>Tabuľka 'migrations' odstránená.</p>";
});
    

Výstup:

<p>Tabuľka 'migrations' odstránená.</p>
    

10.7. Poznámky

• Transakcie: Používajte transact() pre hromadné migrácie, aby ste zaistili konzistenciu.
• Podpora driverov: Syntax sa prispôsobuje podľa drivera (napr. MySQL vs. SQLite), ale niektoré funkcie (napr. ON UPDATE v Oracle) nemusia byť plne podporované.
• Obmedzenia: Metóda migrate() aktuálne podporuje len základné operácie; pre komplexné migrácie použite schema() alebo transact().

11. Prípadová štúdia: E-shop s ORM

Táto kapitola predstavuje praktickú prípadovú štúdiu, ktorá ukazuje, ako použiť Databaser a jeho ORM na vytvorenie jednoduchého e-shopu. Navrhneme databázovú štruktúru, vytvoríme tabuľky, naplníme ich dátami a ukážeme, ako pracovať s dátami pomocou Entity a Collection. Súčasťou budú aj error callbacky na správu chýb, aby sa používatelia naučili robustné techniky.

11.1. Návrh databázovej štruktúry

Pre e-shop navrhneme tieto tabuľky:

• users: Používatelia (zákazníci a administrátori).
• products: Produkty v ponuke.
• product_descriptions: Popisy produktov (jeden produkt môže mať viac popisov, napr. v rôznych jazykoch).
• orders: Objednávky.
• order_items: Položky v objednávkach (prepojenie produktov a objednávok).

SQL na vytvorenie tabuliek

Používateľ môže tieto príkazy skopírovať a spustiť v MySQL databáze:

-- Tabuľka používateľov
CREATE TABLE users (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL UNIQUE,
    role ENUM('customer', 'admin') DEFAULT 'customer',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Tabuľka produktov
CREATE TABLE products (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    stock INT NOT NULL DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Tabuľka popisov produktov
CREATE TABLE product_descriptions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    product_id BIGINT UNSIGNED NOT NULL,
    language VARCHAR(10) NOT NULL,
    description TEXT NOT NULL,
    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE
);

-- Tabuľka objednávok
CREATE TABLE orders (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT UNSIGNED NOT NULL,
    total_price DECIMAL(10, 2) NOT NULL,
    status ENUM('pending', 'shipped', 'delivered') DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Tabuľka položiek objednávok
CREATE TABLE order_items (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT UNSIGNED NOT NULL,
    product_id BIGINT UNSIGNED NOT NULL,
    quantity INT NOT NULL DEFAULT 1,
    price DECIMAL(10, 2) NOT NULL,
    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE
);

SQL na naplnenie dát

Tieto príkazy naplnia tabuľky ukážkovými dátami:

-- Používatelia
INSERT INTO users (name, email, role) VALUES
('Jano Novák', 'jano@example.com', 'customer'),
('Admin Peter', 'admin@example.com', 'admin');

-- Produkty
INSERT INTO products (name, price, stock) VALUES
('Tričko biele', 15.99, 50),
('Topánky čierne', 49.99, 20),
('Bunda zimná', 89.99, 10);

-- Popisy produktov
INSERT INTO product_descriptions (product_id, language, description) VALUES
(1, 'sk', 'Pohodlné biele tričko z bavlny.'),
(1, 'en', 'Comfortable white cotton t-shirt.'),
(2, 'sk', 'Elegantné čierne topánky na každú príležitosť.'),
(3, 'sk', 'Teplá zimná bunda s kapucňou.');

-- Objednávky
INSERT INTO orders (user_id, total_price, status) VALUES
(1, 65.98, 'pending'),
(1, 89.99, 'shipped');

-- Položky objednávok
INSERT INTO order_items (order_id, product_id, quantity, price) VALUES
(1, 1, 2, 15.99),
(1, 2, 1, 49.99),
(2, 3, 1, 89.99);

11.2. Implementácia v Databaser s ORM

Predpokladáme, že Databaser je nakonfigurovaný a pripojený k databáze (viď kapitola 2). Použijeme ORM na prácu s týmito tabuľkami, vrátane správy chýb.

11.2.1. Získanie používateľa a jeho objednávok

Ukážeme, ako získať používateľa s jeho objednávkami a položkami.

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first(
    function ($user, $db, $debug) {
        $user->with(['hasMany:orders']);
        $user->loadRelations(
            function ($result, $db, $debug) {
                echo "Používateľ: {$user->name} ({$user->email})\n";
                foreach ($user->hasMany('orders', 'user_id') as $order) {
                    echo "Objednávka #{$order->id}, Celková cena: {$order->total_price}, Stav: {$order->status}\n";
                }
            },
            function ($error, $db, $debug) {
                echo "Chyba pri načítaní vzťahov: {$error['error']}\n";
            }
        );
    },
    function ($error, $db, $debug) {
        echo "Chyba pri načítaní používateľa: {$error['error']}\n";
    }
);

11.2.2. Pridanie nového produktu s popisom

Vytvoríme nový produkt a pridáme mu popis v slovenčine.

$DotApp->DB->transact(function ($db) {
    $product = $db->newEntity();
    $product->table('products');
    $product->name = 'Šál zelený';
    $product->price = 19.99;
    $product->stock = 30;
    $product->save(
        function ($result, $db, $debug) {
            $productId = $db->insertedId();
            $description = $db->newEntity();
            $description->table('product_descriptions');
            $description->product_id = $productId;
            $description->language = 'sk';
            $description->description = 'Teplý zelený šál na zimu.';
            $description->save(
                null,
                function ($error, $db, $debug) {
                    echo "Chyba pri ukladaní popisu: {$error['error']}\n";
                }
            );
        },
        function ($error, $db, $debug) {
            echo "Chyba pri ukladaní produktu: {$error['error']}\n";
        }
    );
}, function ($result, $db, $debug) {
    echo "Produkt 'Šál zelený' pridaný s popisom.\n";
}, function ($error, $db, $debug) {
    echo "Chyba v transakcii: {$error['error']}\n";
});

11.2.3. Zobrazenie produktu s popismi

Získame produkt a jeho popisy pomocou hasMany.

$product = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'products')->where('id', '=', 1);
})->first(
    function ($product, $db, $debug) {
        $product->with('hasMany:product_descriptions');
        $product->loadRelations(
            function ($result, $db, $debug) {
                echo "Produkt: {$product->name}, Cena: {$product->price} €\n";
                foreach ($product->hasMany('product_descriptions', 'product_id') as $desc) {
                    echo "Popis ({$desc->language}): {$desc->description}\n";
                }
            },
            function ($error, $db, $debug) {
                echo "Chyba pri načítaní popisov: {$error['error']}\n";
            }
        );
    },
    function ($error, $db, $debug) {
        echo "Chyba pri načítaní produktu: {$error['error']}\n";
    }
);

11.2.4. Vytvorenie objednávky

Vytvoríme novú objednávku pre používateľa a pridáme položky.

$DotApp->DB->transact(function ($db) {
    $order = $db->newEntity();
    $order->table('orders');
    $order->user_id = 1;
    $order->total_price = 35.98;
    $order->status = 'pending';
    $order->save(
        function ($result, $db, $debug) {
            $orderId = $db->insertedId();
            $item = $db->newEntity();
            $item->table('order_items');
            $item->order_id = $orderId;
            $item->product_id = 1;
            $item->quantity = 2;
            $item->price = 15.99;
            $item->save(
                function ($result, $db, $debug) {
                    $product = $db->return('ORM')->q(function ($qb) {
                        $qb->select('*', 'products')->where('id', '=', 1);
                    })->first(
                        function ($product, $db, $debug) {
                            $product->stock -= 2;
                            $product->save(
                                null,
                                function ($error, $db, $debug) {
                                    echo "Chyba pri aktualizácii skladu: {$error['error']}\n";
                                }
                            );
                        },
                        function ($error, $db, $debug) {
                            echo "Chyba pri načítaní produktu: {$error['error']}\n";
                        }
                    );
                },
                function ($error, $db, $debug) {
                    echo "Chyba pri ukladaní položky: {$error['error']}\n";
                }
            );
        },
        function ($error, $db, $debug) {
            echo "Chyba pri ukladaní objednávky: {$error['error']}\n";
        }
    );
}, function ($result, $db, $debug) {
    echo "Objednávka vytvorená a sklad aktualizovaný.\n";
}, function ($error, $db, $debug) {
    echo "Chyba v transakcii: {$error['error']}\n";
});

11.2.5. Zobrazenie objednávky s položkami

Získame objednávku a jej položky.

$order = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'orders')->where('id', '=', 1);
})->first(
    function ($order, $db, $debug) {
        $order->with('hasMany:order_items');
        $order->loadRelations(
            function ($result, $db, $debug) {
                echo "Objednávka #{$order->id}, Celková cena: {$order->total_price}, Stav: {$order->status}\n";
                foreach ($order->hasMany('order_items', 'order_id') as $item) {
                    $db->return('ORM')->q(function ($qb) use ($item) {
                        $qb->select('name', 'products')->where('id', '=', $item->product_id);
                    })->first(
                        function ($product, $db, $debug) use ($item) {
                            echo "Položka: {$product->name}, Množstvo: {$item->quantity}, Cena: {$item->price} €\n";
                        },
                        function ($error, $db, $debug) {
                            echo "Chyba pri načítaní produktu: {$error['error']}\n";
                        }
                    );
                }
            },
            function ($error, $db, $debug) {
                echo "Chyba pri načítaní položiek: {$error['error']}\n";
            }
        );
    },
    function ($error, $db, $debug) {
        echo "Chyba pri načítaní objednávky: {$error['error']}\n";
    }
);

11.3. Použitie validácie

Pridáme validáciu pre produkt pred uložením.

$product = $DotApp->DB->newEntity();
$product->table('products');
$product->setRules([
    'name' => ['required', 'string', 'max:100'],
    'price' => ['required', 'numeric', 'min:0'],
    'stock' => ['integer', 'min:0']
]);
$product->name = 'Dlhý názov produktu, ktorý presahuje 100 znakov a je neplatný kvôli maximálnej dĺžke';
$product->price = -5;
$product->stock = 10;
$product->save(
    function ($result, $db, $debug) {
        echo "Produkt úspešne uložený.\n";
    },
    function ($error, $db, $debug) {
        echo "Validácia zlyhala: {$error['error']}\n";
    }
);

11.4. Poznámky k štúdii

Transakcie: Použitie transact() zaisťuje konzistenciu; error callbacky informujú o zlyhaniach.

Vzťahy: hasMany a eager loading (with()) zjednodušujú prácu s dátami, s chybovou kontrolou.

Validácia: Pravidlá chránia pred neplatnými dátami, s jasným hlásením chýb.

Chybová správa: error callbacky umožňujú používateľovi reagovať na problémy (napr. logovanie, upozornenia).

12. Tipy a triky

V tejto kapitole ponúkneme praktické rady, ako efektívne využívať Databaser v DotApp Frameworku. Zameriame sa na optimalizáciu dotazov, zabezpečenie bezpečnosti a možnosti rozšírenia.

12.1. Optimalizácia dotazov

Efektívne dotazy sú kľúčom k rýchlej aplikácii. Tu je niekoľko tipov:

• Vyberajte len potrebné stĺpce: Namiesto select('*', 'users') používajte konkrétne stĺpce, napr. select('id, name', 'users'). Znižuje to objem prenesených dát.

$DotApp->DB->q(function ($qb) {
    $qb->select('id, name', 'users')->where('age', '>', 18);
})->execute(
    function ($result, $db, $debug) {
        var_dump($result);
    }
);

• Využívajte indexy: Pri častých filtroch v where() (napr. id, age) pridajte indexy v databáze pomocou schema():

$DotApp->DB->schema(function ($schema) {
    $schema->alterTable('users', function ($table) {
        $table->index('age');
    });
});

• Limitujte výsledky: Používajte limit() a offset() na stránkovanie, aby ste neťahali zbytočne veľké dátové sady.

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->limit(10)->offset(20);
})->all();

• Cache pri opakovaných dotazoch: Ak máte cache driver implementovaný, využite ho na ukladanie výsledkov:

$DotApp->DB->cache($myCacheDriver)->q(function ($qb) {
    $qb->select('*', 'users');
})->execute(
    function ($result, $db, $debug) {
        echo "Výsledky z cache alebo DB: ";
        var_dump($result);
    }
);

12.2. Bezpečnosť (SQL Injection prevencia)

Databaser je navrhnutý s ohľadom na bezpečnosť, no je dobré poznať osvedčené postupy:

• Vždy používajte prepared statements: QueryBuilder automaticky escapuje hodnoty, takže nikdy nevkladajte premenné priamo do dotazu.

Správne:

$DotApp->DB->q(function ($qb) {
    $qb->select('*', 'users')->where('name', '=', 'Jano');
})->execute();

Nesprávne:

$name = "Jano'; DROP TABLE users; --";
$DotApp->DB->q(function ($qb) use ($name) {
    $qb->raw("SELECT * FROM users WHERE name = '$name'");
})->execute(); // Nebezpečné!

• Surové dotazy s RAW: Ak používate raw(), vždy zadávajte hodnoty cez bindings:

$DotApp->DB->q(function ($qb) {
    $qb->raw('SELECT * FROM users WHERE age > ?', [18]);
})->execute();

• Validačné pravidlá v ORM: Pri ukladaní dát cez Entity nastavte pravidlá:

$user = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users')->where('id', '=', 1);
})->first();
$user->setRules(['name' => 'required|string|max:50']);
$user->name = 'Jano';
$user->save();

12.3. Rozšírenie Databaseru o vlastné drivery

Databaser umožňuje pridať vlastné databázové drivery pomocou metódy addDriver(). Napríklad, ak chcete podporu pre neštandardnú databázu:

Príklad vlastného drivera (simulovaný):

$DotApp->DB->addDriver('custom', 'execute', function ($success, $error) use ($DotApp) {
    $queryData = $this->qb->getQuery();
    $query = $queryData['query'];
    $bindings = $queryData['bindings'];
    // Simulácia vlastnej logiky
    $result = ['id' => 1, 'name' => 'Test']; // Napr. volanie API alebo iného systému
    if ($result) {
        if (is_callable($success)) {
            $success($result, $this, ['query' => $query, 'bindings' => $bindings]);
        }
    } else {
        if (is_callable($error)) {
            $error(['error' => 'Custom driver failed'], $this, ['query' => $query]);
        }
    }
});

// Použitie
$DotApp->DB->driver('custom')->q(function ($qb) {
    $qb->select('*', 'users');
})->execute(
    function ($result, $db, $debug) {
        echo "Výsledok z vlastného drivera: ";
        var_dump($result);
    }
);

Kroky:

• Definujte logiku pre kľúčové operácie (select_db, execute, atď.).
• Pridajte ich cez addDriver().
• Prepínajte na driver pomocou driver('custom').

Toto umožňuje integrovanie Databaseru s akýmkoľvek databázovým systémom, pokiaľ implementujete potrebné metódy.

12.4. Eager Loading vzťahov v ORM

Pri práci s ORM môžete optimalizovať načítanie vzťahov pomocou with():

Príklad:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all()->with('hasMany:posts');
foreach ($users as $user) {
    foreach ($user->hasMany('posts', 'user_id') as $post) {
        echo "Používateľ: {$user->name}, Príspevok: {$post->title}\n";
    }
}

Výhoda: Zníži počet dotazov z N+1 na jeden hromadný dotaz.

12.5. Hromadné operácie s Collection

Collection v ORM ponúka metódy na hromadné spracovanie:

$users = $DotApp->DB->return('ORM')->q(function ($qb) {
    $qb->select('*', 'users');
})->all();
$users->map(function ($user) {
    $user->age += 1;
    return $user;
})->saveAll(
    function ($result, $db, $debug) {
        echo "Všetci používatelia boli aktualizovaní.\n";
    }
);

Metódy: filter(), map(), pluck(), saveAll().