PClib - PHP component library

Quickstart - jak začít?

Těžiště knihovny tvoří tyto třídy:

Třída	Popis
`Tpl`	Základní třída implementující HTML-šablonu.
`Form`	Vytváření formuláře, nahrávání a ukládání formuláře do databáze, validace, odesílání emailem atd.
`Grid`	Výpis údajů z databáze ve formě tabulky s možností řazení, stránkování, filtrování, sumarizačních řádků apod.
`Auth`	Autentizace a správa uživatelských účtů s rolemi a hiearchickými právy.
`Db`	Nadstavba pro práci s databází.
`Translator`	Vícejazyčná podpora (překlad).
`App`	Rozhraní 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.

PClib - PHP component library

Quickstart - jak začít?

Vyhledávání

Kam dál?