Dominique Fournier
34b0dfe095
git-svn-id: https://svn.fournier38.fr/svn/ProgSVN/trunk@1565 bf3deb0d-5f1a-0410-827f-c0cc1f45334c
268 lines
10 KiB
Plaintext
268 lines
10 KiB
Plaintext
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
|
|
<IfModule mod_rewrite.c>
|
|
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.
|
|
</IfModule>
|
|
|
|
# Allow to see a /.html file without having a Forbidden due to Apache conf
|
|
<FilesMatch "^\.html">
|
|
Satisfy Any
|
|
Allow from all
|
|
</FilesMatch>
|
|
|
|
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_<CLASS>.php". This file will contain the class <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 :
|
|
<?php
|
|
class blog
|
|
{
|
|
public function get ($articleid = FALSE)
|
|
{
|
|
if ($articleid === "5" || $articleid === FALSE)
|
|
return array ("5"=>"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/<object>", $auth->authiduser,
|
|
reset ($auth->authgroups), 0755);
|
|
You can remove the objects with :
|
|
$auth->del ("/module/<object>");
|
|
You can see if the user can access to the object with READ, WRITE, EXECUTE :
|
|
$auth->validate ("/module/<object>")
|
|
|
|
XX. CLI usage
|
|
-------------
|
|
The DomFramework is designed to be used in console line too.
|
|
You can pass the arguments like a string or an array with this syntax :
|
|
./cli/cli.php <controller class> <method> <param1> <param2>
|
|
Example : ./cli/cli.php zones update data1 data2 "zone=newvalue1¶m4=new"
|
|
In the example, the param3 provided to the method will be an array containing
|
|
two keys ("zone" and "param4" with the associated values)
|
|
|
|
It is possible to have one dash (-) in the parameters. In this case, the
|
|
informations are readed from the stdin.
|
|
|
|
XX. Modular application
|
|
-----------------------
|
|
THe DomFramework can be used on modular applications. Each application (or
|
|
module) will have a complete autonomy. The structure will be :
|
|
/Project/
|
|
/Project/module1/
|
|
/Project/module2/
|
|
[/Project/domframework/ is optional]
|
|
/ ... /
|
|
|
|
Only one instance of DomFramework is needed. It can be put outside the project.
|
|
In this mode, the routing must be adapted to use the modular mode :
|
|
$route = new route ();
|
|
$route->module = TRUE;
|
|
If you use the route redirect method, think to change the last parameter to
|
|
TRUE.
|
|
|
|
Each module will have its controllers/models/views folders.
|
|
|
|
XX. Plugin developpment
|
|
-----------------------
|
|
DomFramework is based on plugins. You can develop a new plugin to an other
|
|
output type (like a graph...), a new authentication method, etc.
|
|
|
|
Usually, this is done by extending the main class and adding the specificity of
|
|
the new methods.
|