DomFramework/docs/USAGE

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 ();
  $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)

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.
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&param4=new"

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
-----------------------
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.