DOMFRAMEWORK DOCUMENTATION
==========================
1. Introduction
---------------
The DomFramework is a PHP framework used in CLI or Web sites.
It actually supports some mandatory functionnalities of a framework : routing,
url beautifier, authentication, outputs multiple formats (like html, csvn, json,
xml...).
PHP 5.2 minimum
2. Starting a new project
-------------------------
To start a new project with this framework, put the domframework dir in a folder
defined in "include_path" constant of PHP.ini. Usually, there is a . in it, so
you can add the framework directely in the base of a project if you want, or in
a global system directory.
You can start a new project. The following text will be project in
/var/www/project.
You must add a .htaccess file with :
Options -Indexes
RewriteEngine on
# if your app is in a subfolder
# RewriteBase /my_app/
# test string is a valid files
RewriteCond %{SCRIPT_FILENAME} !-f
# test string is a valid directory
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteRule ^(.*)$ index.php?uri=/$1 [NC,L,QSA]
# with QSA flag (query string append),
# forces the rewrite engine to append a query string part of the
# substitution string to the existing string, instead of replacing it.
# Allow to see a /.html file without having a Forbidden due to Apache conf
Satisfy Any
Allow from all
Then start a index.php in the same directory. That's it, the project is started.
3. Creating the folder structure
--------------------------------
DomFramework waits for at least one special folder : controllers.
In this folder, you will create the controllers for your application, with the
name "controller_.php". This file will contain the class .
DomFramework use a folder named "views". It will contains the differents HTML
views rendered on the user browser.
You can create a folder "models" to respect the MVC model. DomFramework forbid
access to this directory directely.
4. Controllers
--------------
A controller is a PHP class which will do something. It shouldn't access to
databases directely (as it is the model part). It can provide methods to access
to database model.
The methods in the controller will be the only access from the framework.
The controllers shouldn't write directly to stdout. They should return the
result of their work to the caller.
Example :
"Article very important");
throw new Exception (_("Article not found"), 404);
}
}
The errors can be returned with an Exception.
5. Routing and beautifier URL
-----------------------------
In a Web site, the philosophy is to have a URL for each action.
You can do a beautiful URL with DomFramework http://localhost/project/blog/page
you will allow the class "blog" to be launch with the parameter "page".
This is the routing. You need to add the routes in your index.php file with :
require_once ("domframework/route.php");
$route = new route ();
$route->get ("home", function () { echo "YESY"; });
$route->post ("home", function () { echo "YESY"; });
$route->put ("home", function () { echo "YESY"; });
$route->delete ("home", function () { echo "YESY"; });
The definition match on the HTTP method (GET,POST,PUT or DELETE). It can be
surcharged by using the _METHOD variable in POST method, with the wanted method
to use.
The routes are read sequentially. The first which match the class/method wins.
You should carrefully order the rules.
Add the debug on routing with
$route->debug=TRUE;
to help to see the matches.
We can use some variables to be passed to the called function :
$route->get ("home3/{plo}/{str}", function ($str, $plo) {echo "$str $plo";});
There is a special action named "redirect" in the "route" class. It provide the
capability to re-route the Web browser to another page. Put in action :
function () use ($route) {$route->redirect("/home4", FALSE);}
If the URL match the requested search, the Web browser will load immediately a
new page named "nextPage/". The FALSE will be change in case of modular
application (see the MODULAR APPLICATION chapter)
The Ending slash can be a problem and can be removed by using :
// If there is a no catch route ending with slash, try to reroute without slash
$route->get ("{string}/",
function ($string)
{
$r=new route ();
$r->redirect ($r->baseURL().$string);
});
6. Output : the renderer
------------------------
When a controller has finished his job, the result returned to the main class of
routing to be displayed. It can be displayed in a lot of formats : HTML, csv,
json, xml.
The allowed extensions are puts in the routingCollection in the position you
want by adding them between parenthesis. Example :
require_once ("domframework/route.php");
$route = new route ();
$res = $route->routingCollection (array (
"{page}" => array ("class", "method", "{parameter}"),
));
print_r ($res);
It can be used by the renderer system (generally run by controller) :
$renderer = new renderer ();
$renderer->result = $res;
$renderer->output = "html";
$renderer->run ();
In controllers, the renderer can be called too. There is a flash method. The
flash messages will be displayed on next page, in case of HTML page. In CLI, it
is immediately displayed.
7. Layout
---------
In HTML, there is a presentation layer, named layout. The layout is common to
all the site pages.
All the pages are coded in "views" directory. The renderer call them before
displaying the result.
By default, the layout is a page named "layout.html", in the views directory.
It contains the HTML page with some special parts : the tokens. Tokens are
written like {content} or {title}. The renderer replace them by the result of
replacement attibute.
It is also possible to define some variable and pass them to the view. The view
will treat them as it want and modify the displayed content as needed.
8. Debug
--------
When creating a routingCollection, a lot of errors can be done. There is in
DomFramework the capability to debug the application. You can activate the debug
by putting 1 in the associated method. Example :
$route = new route ();
$route->debug = 1;
The screen will display the actions to help the debug :
==== DEBUG : ROUTING START ====
blog/5 ?? blog/{page} => blog->get({page}) : FOUND : URL === REGEX : Call blog()->get(5)
==== DEBUG : ROUTING END ====
9. Forms
--------
The forms module is the easiest way to display HTML forms for users. It
integrate the CSRF security with a hidden field, can display a notice, warning
or error to the user.
To use it :
require ("domframework/form.php");
$errors = array ();
$f = new form ();
// Check CSRF and get the provided values if they exists
$values = $f->values ();
// Define here the fields (can be done multiple times)
$field = new formfield ($name, $label);
// Add the parameters to the field
$fields[] = $field;
unset ($field);
$f->fields ($fields);
// Display the form
echo $f->printHTML ("post", $values, $errors);
The fields are defined by :
- name : name of the field in the HTML page
- label : label written to the describe the field
- [titles] : text written in radio/checkboxes
- [defaults] : default values. Must be array for checkbox/select, and
string for others
- [type] : text, password, hidden, checkbox, select, radio, submit
text by default
- [multiple] : Multiple selection are possible (if the type supports it)
- [group] : define a fieldset and define the title with groupe name
Warning : all the elements of the same group must be consecutive !
- [readonly] : put a read-only flag on the field (the user see it but
can't interract on it. The value will be sent to next page
- [mandatory] : boolean to add a red star at end of label
The CSRF parameter is verify automatically when using $f->values ();
In case of error, an exception is raised.
10. Authentication / Authorization
----------------------------------
The Authentication/Authorization module permits to allow/deny access to objects.
The user must be validated before using a information. It is based on Unix
model, with users/groups/modbits, files (objects) with owner/group/modbits.
To do that, you can use a table in your database:
$auth = new authorizationdb ();
$auth->connectdb ($this->database["dsn"], $this->database["username"],
$this->database["password"],
$this->database["driver_options"]);
Then add the objects with the rights :
$auth->add ("/module/