PClib - PHP component library

Current version is 1.6.0, last update 28. March, 2012

What is it?
What does it consist from?
Search site
Philosophy
Drawbacks
Non-FAQ
Examples
Video tutorials
Screenshots

What is it?

Open source library for PHP 4 and PHP 5
Features: template engine, managing forms and datagrids, authentication module, database layer, multilanguage support, eventlog and more.
It consists from independent modules. No problem use only templates or only authentication module.
Simple, yet flexible API. Focused on support of most frequent tasks in developing of common web-applications.
It's free for any (commercial or non-commercial) applications (LGPL licence)

What does it consist from?

Core of the library consists from these classes:

tpl - basic class which implements HTML-template.
form derived from tpl. Creating of the form, load and save form to the database, validation, sending by mail etc.
grid derived from tpl. Database grid with sorting and pagging, filtering support, summarization rows, formatting of the fields etc.
auth, authc - Authentication and user account management with roles and hiearchical rights.
db - Database layer.
mls - Multilanguage support.
eventlog - Application event logger.

Search site

Philosophy

Simplicity. Simple task should lead to simple code. PClib don't use code generators. Instead of that, we prefer keep code simple and short and avoid tens directories, hundred rows of initialization and thousands source files. Also, we prefer only modest using of OOP.
Practice. Our goal is help with programming of common web applications. Pclib is result of real experience, no theory. New functions are added, if they are necessary in practice. It focus on concrete things: - datagrid and form is important part of the library.
Freedom. PClib is trying to be flexible and not "stand in the way". We do not believe very much in forcing programmers do things only one right way. PClib is more "library" than "framework". Good programmer will be good even in liberal enviroment, bad will be bad in any framework. Some organization is necessary, but strict regulations leads to ugly limitations - at least it's my experience.
PClib rather do something, than throw error on any discrepancy. It is trying to be benevolent tool like PHP4, MySQL or HTML. Today most of programmers thinks that, for example, strict type control leads to less buggy code. In my experience benevolent concepts like PHP array, where you can add anything anywhere and read anything even if it does not exists, makes possible create shorter and more simple code and because - in my opinion - less buggy.

Drawbacks

Only MySQL is supported in current version
Some features common in other frameworks are not supported (e.g. cache)
It is not tested extensively
Friendly and welcoming community does not exists. (so far)
Incomplete documentation

Non-FAQ

The questions which nobody ask me.

This site looks ugly. - Yes. We like it ugly.
Your english is lame. - Yes, I know.
The truth about what 'brambor' means: - brambor
Your philosophy - simplicity, anarchy, revolution, ugliness, rotting - seems like punk... - No future, dude.

Examples

Some frameworks says that they are simple. The pclib is different - it is simple. Our credo is "simple task == simple code". With pclib you can start solve your problem immediatelly and don't fight with programming bureaucracy. But still you can solve complex tasks, if you need it. 0.0 Class tpl Showing template




$t = new tpl ('tpl/mytemplate.tpl');

$t->values['A'] = 'Insert text from php to the template.';

$t->values['B'] = 123456.789;

$t->values['C'] = date("Y-m-d H:i:s");

$t->out();

At first we create object $t from template file "mytemplate.tpl". Next, we put few values into template and finally we show template with function $t->out(). Values inserted into template can be transformed/formatted according instructions in section elements at template file (This section is loaded into array $t->elements in class constructor).
Look here for example of template file.

Hint: It is common that we need place a template into another one. (Most websites has fixed header and footer, for example, and only content in the middle is changing) Function $t->html() returns content of the template (i.e. resulting html). So for placing $t into covering template just do: $website->values['CONTENT'] = $t->html() 0.1 Class grid Showing datagrid




$products = new grid ('tpl/mygrid.tpl');

$products->setquery('select * from PRODUCTS');

$products->out();

These three lines will show content of database table PRODUCTS as datagrid similar to this example.
In case that you are interested how grid template looks like, click on "source" in the link above - it contains complete source code including template file. With simple changes of html and css you can get for example this look.
To enable sorting add keyword "sort" at column definition in template file. Changing format of the pager is easy too. Another posibilites includes date formatting, string clipping, using lookup tables and so on.

Note: One of the important concepts is do not have application logic in template. It's the reason why templates doesn't contain loops, conditional statements and similar program structures. We do not want template metalanguage, but it is still possible control these things from php code. You can enable block or any element of the template $products->enable('block'); or set any attribute of column (here sorting): $products->set('productName/sort', 1); and many more. 0.2 Class form Showing form




$productform = new form('tpl/productform.tpl');

$productform->values = $db->select('PRODUCTS', 'ID=100');

$productform->out();

As you can see, it is as simple as datagrid. Result will look roughly like in here. On the second line we fill associative array values, which contains all data filled in the fields of the form. If we omit this step, form will be shown empty. We are using function of class db here, which returns row from table PRODUCTS as associative array.

Class form integrates all fuctions for working with forms, including form validation, storing in database or showing error messages if form was not filled properly. 0.3 Class form Storing form




if ($productform->submitted) {

  $ok = $productform->validate();

  if ($ok) $productform->insert('PRODUCTS');

  else $productform->out();

}

The above code says: When form was submitted, do validation (validation rules for the form fields are specified in template). If we pass, insert filled values into table PRODUCTS. If not, show form again with error messages.

Note: Data filled by the user are stored in array $productform->values. If form is not valid, function validate() fill array $productform->invalid with error messages. These messages can be shown in template. 0.4 Class db Read/write row from database table.




$db = new db("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 is not using concept of DAO, but often works with associative array containing row / rows of the table. These arrays can be loaded into form very easy, read back from form filled by user, loaded into grid etc. Class db supports working with these arrays directly. In our example we read row of the table into array $product, raise product price by 20 percent and store it back into database.

Note: Function paramstr() put values from associative array $product into text string. Keys are in curly brackets - just like in template.
Hint: It can be useful, for debugging purposes, check how resulting SQL sent to the database server looks like. To do this, enable query logger: $db->logging = 2; and write content of array $db->messages at the end of your script. It will show you all executed queries.

0.5 Class mls Filling table with multilanguage strings.




$mls = new mls();

$mls->setlang('en');

$mls->autoupdate = true;

Maybe you have noticed that labels of the fields in grid or form can be shown by modificator {FIELD.lb}. If we create object $mls and set $mls->autoupdate to true, all labels will be stored into database table MLS (multilanguage strings) when template is shown. This table can be exported into text file ($mls->export()) for translation and translated text can be imported back ($mls->import()).
If proper translation for active language exists, labels in template will be automatically translated.
With class mls you can do a lot more, however. For example multilanguage string can be marked with special tag <M:test>This sentence is part of translation texts.</M> Content of this tag will be stored as multilanguage text with identificator "test". 0.6 Class auth PClib authentization / logging in.




$auth = new auth('authdemo');

$ok = $auth->login('username', 'password');

if (!$ok) { var_dump($auth->errors); die(); }



$user = $auth->getuser();

print paramstr("User {FULLNAME} has been logged in.", $user);



if ($auth->hasright('demo/products/delete')) print "User has permission delete products.";

$auth->logout();

A few words to above code: Function login() check user name and password and authorize user. If name or password is wrong, we write errors and quit. If user has been authorised, we read his account information into array $user (Which is row from table AUTH_USERS) and write his name. At least we test if he has permission "demo/product/delete" and perform logout. For configuration of user accounts and permissions you can use authentization console ATERM. See demo of auth, including console, in this example. It's even possible prepare batch file with roles and permissions for your project. Here is the example: Auth policy

Note: Class auth uses database, so you must establish db conection before using it. Also setting of configuration variable AUTH_SALT is required. Look at demo source.
Hint: You can assign permission with wildcard "*" to the user or role. Say "demo/products/*" grant all permissions beginning with "demo/products/": "demo/products/delete", "demo/products/edit" ...etc.
By assigning just "*" i.e. $authc->ugrant('username', '*'); (class authc) or username +right * in console, give all rights to the user. 0.7 Class eventlog Write login event to the log.




$eventlog = new eventlog('demo');

$eventlog->notice('authdemo/login');

If we would put this two lines into previous example, event 'authdemo/login' will be stored into database log.
The eventlog is 'binary', which means: only integer IDs are stored into database table (because of speed and saving space on big amounts of logged data) Function notice() write event with severity 'notice' - 'authdemo/login' is the label of the event. You can choose label arbitrary, function will check lookup table ELOG_LABELS and add your label, if necessary. Event data are stored into table ELOG. Record contains date and time of the event, IP address, browser and OS, and - if you are using class auth - ID of user which raise event. Optionally it's possible store id of object which is target of the event.

Videotutorials

Screenshots

grid

grid+search

form

gridform (grid with inputs)

lazyform (generic form)

improved error messages

authentization console