Skip to content

Popis tříd k přístupu k databázi

Tento dokument popisuje hlavní PHP třídy v core/database. Cílem je přiblížit novému vývojáři, jak třídy fungují, jak spolu souvisejí a co je jejich odpovědnost.

Třída DB

Statická brána k databázovému rozhraní. Poskytuje přístup k metodám přes statické volání, ale veškerou práci deleguje na vnitřní instanci třídy PDOHandler.

Automatická inicializace (lazy loading)

Třída DB využívá lazy initialization - připojení k databázi se vytvoří automaticky při prvním volání libovolné metody (query(), results(), row(), atd.).

Není potřeba:

  • Manuálně volat DB::init()
  • Includovat app/database.php
  • Dělat cokoliv na inicializaci - DB se postará automaticky

Příklad: 

// Automaticky se inicializuje při prvním dotazu - bez jakéhokoli require
$users = DB::results("SELECT * FROM users");
echo count($users);  // Funguje okamžitě!

Interně je připojení inicializováno prostřednictvím ensureInitialized() metody, která se volá automaticky před prvním SQL dotazem.

Klíčové public metody

  • DB::init(...) – inicializuje spojení s databází (voláno automaticky)
  • DB::query($sql, $params = []) – provede SQL dotaz
  • DB::results($sql, $params = []) – vrátí více řádků
  • DB::row($sql, $params = []) – vrátí jeden řádek
  • DB::var($sql, $params = []) – vrátí jednu hodnotu
  • DB::col($sql, $params = []) – vrátí jeden sloupec
  • DB::prepare($sql) – připraví SQL příkaz
  • DB::test($sql, $params = []) – debug helper: vypíše finální SQL s dosazením parametrů (bez spuštění)
  • DB::beginTransaction(), commit(), rollBack() – správa transakcí
  • DB::set($fields) – generuje SET část dotazu
  • DB::escape($string) – escapuje string (výjimečně)

Třída PDOHandler

Třída, která drží instanci PDO a vykonává reálné SQL operace. Je použita v rámci DB::$DB.

Klíčové public metody

  • __construct(...) – vytvoření připojení.
  • query($sql, $params = [])
  • prepare($sql)
  • beginTransaction(), commit(), rollBack()
  • getLastInsertId()
  • getLastError()

Třída Base

Poskytuje základní infrastrukturu – výsledky dotazů, stavové proměnné a možnosti nastavení.

Klíčové vlastnosti

  • $lastQuery, $lastError, $queryError, $lastResult, $insertId, $affectedRows, $numRows
  • setting(array $array)

Vztahy mezi třídami

classDiagram
    class DB {
        +static init()
        +static query()
        +static prepare()
        +static beginTransaction()
        +static getLastInsertId()
    }

    class PDOHandler {
        +query()
        +prepare()
        +getLastInsertId()
        +getLastError()
    }

    class Base {
        +lastQuery
        +lastError
        +setting()
    }

    DB --> PDOHandler : obsahuje instanci
    PDOHandler --> Base : dědí

Třída DB2

Druhá instance databázového připojení pro výjimečné případy, kdy je potřeba připojení k externí nebo sekundární databázi.

Klíčové rozdíly oproti DB

Aspekt DB DB2
Inicializace Automatická (lazy loading) Ručně DB2::init()
Kdy se připojit Při prvním dotazu Předtím, než se jí začne používat
API Stejné metody Stejné metody
Připojení Primární (z .env) Sekundární (vlastní parametry)
Částé použití Vždy (100% případů) Velmi zřídka (<1% případů)

Vlastnosti DB2

  • Bez lazy loadingu – nemá ensureInitialized(), musíš ručně volat DB2::init()
  • Explicitní inicializace – vyžaduje zadat host, uživatele, heslo, databázi
  • Oddělené připojení – nemá vliv na primární DB
  • Stejné metody – jakmile je inicializován, používá se úplně stejně jako DB

Praktické použití

use Petrovo\Database\DB2;

// 1. Inicializuj druhou databázi (POVINNÉ!)
DB2::init('external_user', 'password', 'external_db', 'external.host.com');

// 2. Pak můžeš používat stejně jako DB
$product = DB2::row("SELECT * FROM products WHERE id = ?", [$id]);
$count = DB2::var("SELECT COUNT(*) FROM orders");

Poznámka: Používá se velmi zřídka – pouze když potřebuješ připojit se k externí databázi (např. integrace se starším systémem, datový sklad, API databáze). V 99% projektů na Petrovo CMS se DB2 vůbec nepoužívá.

Shrnutí (důležité pro vývojáře)

  • Používej DB:: pro veškeré databázové operace – je to stabilní a připravené API
  • Nevyžaduje manuální inicializaci - připojí se automaticky při prvním dotazu
  • Třída PDOHandler je interní vrstva — nemusíš ji používat přímo
  • Vždy používej parametrizované dotazy (DB::query($sql, $params))
  • Výsledky dotazů vrací objekty (PDO::FETCH_OBJ), tzn. přístup přes ->columnName
  • Třída Base poskytuje metadata jako poslední dotaz, počet řádků, chybové hlášky atd.
  • Pro druhou databázi použij DB2 s explicitní inicializací