First release of domframework
git-svn-id: https://svn.fournier38.fr/svn/ProgSVN/trunk@1207 bf3deb0d-5f1a-0410-827f-c0cc1f45334c
This commit is contained in:
185
docs/USAGE
Normal file
185
docs/USAGE
Normal file
@@ -0,0 +1,185 @@
|
||||
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...).
|
||||
|
||||
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 ();
|
||||
$res = $route->routingCollection (array (
|
||||
"blog/{page}" => array ("class", "method", "{page}"),
|
||||
));
|
||||
|
||||
The routes are read sequentially. The first which match the class/method wins.
|
||||
It start a new instance of "class" and apply the method "method" with the
|
||||
parameters need to launch the action. The result of the action is returned to
|
||||
the main script to be outputed.
|
||||
The parameters are puts between {}. You must put the parameters in the right
|
||||
order needed by your method.
|
||||
|
||||
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 :
|
||||
array ("route", "redirect", "nextPage/", 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)
|
||||
|
||||
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.
|
||||
|
||||
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 ====
|
||||
|
||||
XX. CLI usage
|
||||
-------------
|
||||
The DomFramework is designed to be used in console line too.
|
||||
TBC !!
|
||||
|
||||
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
|
||||
-----------------------
|
||||
DomeFramework 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.
|
||||
Reference in New Issue
Block a user