English
version 2.9.5

  PClib - PHP component library

Quickstart - jak začít?

Těžiště knihovny tvoří tyto třídy:
TřídaPopis
TplZákladní třída implementující HTML-šablonu.
FormVytváření formuláře, nahrávání a ukládání formuláře do databáze, validace, odesílání emailem atd.
GridVýpis údajů z databáze ve formě tabulky s možností řazení, stránkování, filtrování, sumarizačních řádků apod.
AuthAutentizace a správa uživatelských účtů s rolemi a hiearchickými právy.
DbNadstavba pro práci s databází.
TranslatorVícejazyčná podpora (překlad).
AppRozhraní pro přístup k aplikačním službám (konfigurace, spouštění akcí aplikace, logování atd.)

0.0 Class pclib\Tpl Zobrazení šablony
$t 
= new PCTpl('tpl/mojesablona.tpl');
$t->values['A'] = 'Vložíme text z php do šablony.';
$t->values['B'] = 123456.789;
$t->values['C'] = date("Y-m-d H:i:s");
$t->out();
 
Nejprve utvoříme objekt $t ze souboru šablony "mojesablona.tpl". Pak do šablony vložíme několik hodnot a nakonec ji zobrazíme funkcí $t->out(). Hodnoty vložené do šablony můžeme dodatečně upravovat a zformátovat, instrukce pro jejich zformátování se nalézají v souboru šablony v sekci elements (Tato sekce je při vytvoření objektu načtena do pole $t->elements).

Tip: Často se vyskytne potřeba vložit jednu šablonu do druhé. (Většina websites má kupříkladu pevně danou patičku a hlavičku s nadpisem a menu do které se vkládají konkrétní stránky - tzv. layout) Funkce $t->html() vrátí výsledný obsah šablony do proměnné. Vložení $t do druhé šablony tedy může vypadat například takto: $website->values['CONTENT'] = $t->html(). Nebo použijte metodu $app->setLayout().

0.1 Class pclib\Grid Zobrazení datagridu
$products 
= new PCGrid('tpl/mygrid.tpl');
$products->setQuery('select * from PRODUCTS');
$products->out();
 
Tyto tři řádky zobrazí výpis databázové tabulky PRODUCTS, velmi podobný tomuto.
Jestliže vás zajímá, jak šablona gridu vypadá, klikněte ve výše uvedeném odkazu na "source" - obsahuje kompletní zdrojový kód příkladu včetně šablony. Jednoduchou úpravou šablony se stylováním lze docílit např. takovéhoto vzhledu.
Pokud chcete aktivovat možnost řazení, stačí přidat za definici pole v šabloně klíčové slovo "sort". Podobně snadno lze modifikovat i formátování pageru (stránkovátka). Další možnosti zahrnují namátkou formátování datumů, ořezávání dlouhých textů a snadné zobrazení číselníkových údajů (převod číselného ID na textový popis).

0.2 Class pclib\Form Zobrazení formuláře.
$productForm 
= new PCForm('tpl/productform.tpl');
$productForm->values $db->select('PRODUCTS''ID=100');
$productForm->out();
 
Jak vidíte, je to stejně jednoduché jako s gridem. Výsledu bude vypadat přibližně jako zde. Na druhém řádku naplníme asociativní pole values, které obsahuje všechny hodnoty vyplněné do políček formuláře. Kdybychom tento krok vynechali, bude formulář zobrazen prázdný. Využijeme k tomu s výhodou funkci třídy db, která vrátí řádek z tabulky PRODUCTS jako asociativní pole.

Třída Form integruje všechny funkce potřebné k práci s formuláři, jako např. validace vyplněných údajů, ukládání do databáze nebo výpis chybových hlášení. 0.3 Class Form Uložení formuláře.
if ($productForm->submitted) {
  
$ok $productForm->validate();
  if (
$ok$productForm->insert('PRODUCTS');
  else 
$productForm->out();
}
 
Tedy: jestliže byl formulář odeslán, proveď validaci (tj. např. zda jsou vyplněná povinná pole - validační pravidla se zadávají v šabloně), pokud je vše v pořádku, vlož vyplněné hodnoty do tabulky PRODUCTS. Jestliže ne, vypiš formulář znovu včetně chybových hlášení.

Poznámka: Data vyplněná uživatelem jsou po odeslání uložena v poli $productForm->values. Jestliže je formulář nevalidní, funkce validate() naplní pole $productForm->invalid chybovými hlášeními. Tato hlášení lze zobrazit v šabloně.

0.4 Class pclib\Db Načtení/uložení řádku z databázové tabulky.
$db 
= new PCDb("pdo_mysql://user:password@mysql.host.cz/databasename");

$product $db->select('PRODUCTS''ID=100');
$product['buyPrice'] *= 1.2;
$db->update('PRODUCTS'$product'ID=100');

print 
paramStr("Product {productName} has new price {buyPrice}."$product);
 
PClib v současné verzi nemá přímou podporu modelů a návrhových vzorů jako je ActiveRecord, ale jednoduše používá asociativní pole reprezentující řádek / řádky tabulky. Takové pole pak lze velmi snadno načíst do formuláře, přečíst zpět z formuláře vyplněného uživatelem, nebo načíst do gridu. Třída Db mimo jiné přímo podporuje práci s těmito poli. V našem příkladu přečteme řádek tabulky do pole $product, zvýšíme cenu produktu o dvacet procent a uložíme ho zpět do databáze.

Poznámka: Funkce paramstr() vloží hodnoty z asociativního pole $product do textového řetězce. Klíče jsou ve složených závorkách - formát stejný jako u šablony.
Tip: Často je potřeba podívat se, jak vypadá výsledné SQL odesílané databázovému serveru. K tomu obvyčejně použijeme debugbar, který se aktivuje příkazem $app->debugMode = true;
Lze také vypsat kód posledního SQL příkazu, který je v proměnné $db->lastQuery.

0.5 Překlad vícejazyčných textů.
$translator 
= new pclib\Translator();
$translator->language 'en';
print 
$translator->translate('Hello!');
 
Translátor umí překládat texty ve zdrojovém kódu pomocí tabulky textů uložených v databázi (nebo v souboru). Nejprve musí existovat tabulka textů ve zdrojovém kódu uložená jako jazyk 'source' a pak k ní můžete vytvářet překlady například pomocí nástroje padmin.
Obvykle inicializujeme translátor nepřímo nastavením jazyka aplikace (a můžeme pak místo $translator->translate použít zkratku $app->text()):
$app
->language 'en';
print 
$app->text('Hello!');
 
Jestliže nastavíme jazyk 'source', translátor bude při používání automaticky plnit tabulku zdrojových textů. Translátor ví o popiscích šablon, chybových hlášeních a popiscích pclib a zahrne je automaticky do překladu. Texty v šablonách lze označit jako určené k překladu pomocí tagu <M>Nějaký text</M>

Tip: Uložte formát data nebo ceny do textů k překladu: $dateFormat = $app->text('%d/%m/%Y');
Pokud používáte různé jazykové verze celého souboru, můžete si uložit cestu k souboru:
print file_get_contents($app->text('views/en/aboutus.html'));
V textu můžete používat zástupné značky: $app->text('Vítejte %s na našem webu!', $name);

0.6 Class Auth Autorizace a autentizace.
$auth 
= new PCAuth();
$ok $auth->login('username''password');
if (!
$ok) { var_dump($auth->errors); die(); }

$user $auth->getUser();
print 
paramstr("Uzivatel {FULLNAME} byl uspesne prihlasen."$user->toArray());

if (
$auth->hasRight('demo/products/delete')) print "Ma pravo mazat produkty.";
$auth->logout();
 
Funkcí login() provedeme přihlášení uživatele. Jestliže je jméno nebo heslo chybné, vypíšeme chyby a ukončíme program. Jinak načteme údaje o přihlášeném uživateli a vypíšeme jeho jméno. Nakonec otestujeme, zda má právo "demo/product/delete" a odhlásíme ho. Ke konfiguraci uživatelských účtů a práv lze použít konzoli aterm v programu padmin. Lze si dokonce připravit pro první inicializaci dávkový soubor s definici rolí a oprávnění. Ukázka

Poznámka: Třída Auth využívá databázi, a proto před jejím použítím musíme vytvořit aktivní připojení. Dále je vyžadováno nastavení konfigurační proměnné 'pclib.auth.secret'. Viz ukázka v demonstračních příkladech.

Tip: Uživateli nebo roli lze přidělit právo s hvězdičkou - například "demo/products/*" zajistí, že bude mít všechna práva ve skupině "produkty": "demo/products/delete", "demo/products/edit" ...atd.
Přidělení práva "*" tedy $authc->uGrant('username', '*'); (třída AuthC) nebo username +right * v konzoli, zajistí uživateli všechna práva.

0.7 Class Logger - Logování událostí.
$logger 
= new PCLogger();
$logger->log('NOTICE''user-login');
 
Kdybychom do předchozího příkladu vsunuli tyto dva řádky, provede se zalogování přihlášení uživatele do databázového logu.

Tip: K logování můžete použít aplikační log: $app->log('NOTICE', 'user-login'); Bude fungovat, pokud ho na začátku nastavíte: $app->logger = new PCLogger(); Logování vypnete zakomentováním tohoto řádku - metoda pak neudělá nic.
Uložené logy lze prohlížet, prohledávat a mazat v aplikaci padmin.

0.8 Použití třídy App. Vytvoření objektu třídy App je od verze 1.8.8 povinné. Třída App obsahuje kontejner globálních služeb $app->services, které využívají ostatní třídy, takže pokud chcete aby nějakou službu viděly, je nutné ji zaregistrovat do aplikace:
$app 
= new PCApp('nazev-aplikace');
$app->db = new PCDb('pdo_mysql://...');
 
Dál můžete vytvářet kód jak jste zvyklí z předchozích verzí. Můžete ale třídě App přenechat řízení a směrování požadavků. Pak v souboru index.php můžete mít jen toto:
$app 
= new PCApp('nazev-aplikace');
//inicializace sluzeb aj.
$app->run();
$app->out();
 
Metoda $app->run() přijme požadavek z prohlížeče, přeloží ho na volání metody třídy pclib\Controller a tu se pokusí najít v adresáři controllers/. Pokud ji nalezne, zavolá metodu včetně požadovaných parametrů. Metoda $app->out() vypíše výstup vrácený metodou kontroleru. Ve vámi vytvářeném kontroleru můžete přistupovat k objektu App pomocí klauzule $this->app:
//file /controllers/CartController.php
class CartController extends PCController
{
  
//executed on url '?r=cart/show&id=123' or '/cart/show?id=123'
  
function showAction($id) {
    
$cart = new Form('/tpl/cart/form.tpl');
    
$cart->values $this->app->db->select('shop_cart'pri($id));
    return 
$cart->html();
  }
}
 
Objekt $app obsahuje i jiné entity náležející celé aplikaci např.
$app->config (konfigurace pclib - můžete si přidat vlastní konfig. soubor pomocí $app->addConfig(soubor);
$app->layout - layout aplikace, je nutné nastavit šablonu pomoci $app->setLayout('website.tpl');
$app->environment - prostředí: test, production, develop apod.
$app->debugMode - true/false - zapne režim ladění

Z hlediska architektury představuje třída app návrhový vzor facade: Máme zjednodušený přístup k řadě specializovaných tříd prostřednictvím jednoho vstupního bodu. Tak například nastavením $app->debugMode používáme třídu DebugBar, nastavením $app->language inicializujeme službu $app->translator (třída Translator), metody jako je $app->log() (třída Logger) nebo $app->text() pro překlad (třída Translator) jsou noop, pokud tyto služby nejsou aktivovány.