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

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. Database abstraction
------------------------
A database abstraction permits to forget if the database engine is MySQL, SQLite
or PostgreSQL. It can read, insert, update easily from arrays, but display the
tables without having to think about the backend.
It check the foreign keys before doing insertions/updates, look at unique
constrains. It can create table with the different syntax of the engines.
Define your table like this :
    class record extends dblayer
    {
      public $table = "dns_records";
      public $fields = array (
        "id"=>array ("integer", "not null", "autoincrement"),
        "zoneid"=>array ("integer", "not null"),
        "source"=>array ("varchar", "255", "not null"),
        "class"=>array ("varchar", "2", "not null"),
        "rr"=>array ("varchar", "10", "not null"),
        "addvalues"=>array ("varchar", "10"),
        "target"=>array ("varchar", "255", "not null"),
        "ttl"=>array ("integer"),
        "comment"=>array ("varchar", "1024"),
        "opendate"=>array ("datetime", "not null"),
        "closedate"=>array ("datetime"),
      );
      /** The primary key of the table */
      public $primary = "id";
      /** The unique constrain of the table */
      public $unique = array ("id");
      /** The foreign keys of the table */
      public $foreign = array ("zoneid"=>array ("dns_zones", "id",
                                        "ON UPDATE CASCADE ON DELETE CASCADE"));
      /** SQL Debug */
      public $debug = FALSE;
    /** Translation */
      public function titles ()
      {
        return  array (
          "id"=>_("ID"),
          "zoneid"=>_("ID Zone"),
          "source"=>_("Source"),
          "class"=>_("Class"),
          "rr"=>_("RR"),
          "addvalues"=>_("Add values"),
          "target"=>_("Target"),
          "ttl"=>_("TTL"),
          "comment"=>_("Comment"),
          "opendate"=>_("Open date"),
          "closedate"=>_("Close date"),
        );
      }
    
      public function verifyOne ($field, $val)
      {
        $verify = new verify ();
        switch ($field)
        {
        case "id":
          break;
        case "zoneid":
          if (strlen ($val) < 1)
          {
            $msg = _("Not enough chars");
            return array ("error", $msg);
          }
          break;
        // Add more unit tests here
        }
        return array ();
      }
    
      /** Verify all the fields consistency and return an error array */
      public function verifyAll ($datas)
      {
        $errors = array ();
        $verify = new verify ();
        switch ($datas["rr"])
        {
        case "A":
          if (substr ($datas["source"], -1*strlen ($datas["zone"])) ===
              $datas["zone"])
          {
            $msg = _("Don't add the domain in the source");
            $errors["source"] = array ("error", $msg);
          }
          break;
        // Add more consistency tests here
        }
       return $errors;
      }
    }

11. 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>")

12. Internationalization
------------------------
The domframework can be use to internationalize your software. You can create a
structure like _locale/en_US.UTF8/LC_MESSAGES/{package}.mo_ and just call :
    // Selection of the language
    $language = new language ();
    $language->activeLanguage ("package", "package-Langugage");

Change the name "package" by your soft name, and use the same name in the
_LC_MESSAGES_ directory.
The _LC_MESSAGES_ directory must be writeable : a cache of the .mo file is
created if it is possible to inform Apache of the evolutions of your software.

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