xero / open_qoob

open qoob framework

the qoob is a semi-RESTful php api framework designed to simplify and expedite the process of creating dynamic web applications.

                           MM.                                                   
                           MNNNN.                                                
                           MM...NMN.                                             
                           MN......ONN                                           
                           MN.......ZN                                           
                           MN.......ZN                                           
                           MNZ......ZN         MMMMMMM  MMMMMMM  MMMMMMM  MMMMM  
                         ,ND."MND...ON         MM   MM  MM   MM  MM  MMM  MM   MM
                      ,NNN..NN. "MNDON         MM   MM  MM   MM  MM       MM   MM
                   ,NNN.......DNN. "ON         MMMMMMM  MMMMMMM  MMMMMMM  MM   MM
                 NNM..............NNM                   MM                       
             ,N N. "NN7........ONN" ,N                  MM                MM     
          ,NNNN NNNN."ONN...ZNN" ,NMON                  MM                MM     
       ,NNI..ON NO...NN. "NN" ,NN...MN                                    MM     
     NN......ON NZ......NN INN......MN         MMMMMMM  MMMMMMM  MMMMMMM  MMMMMMM
     N.......ON NZ.......N $N.......MN         MM   MM  MM   MM  MM   MM  MM   MM
     N.......ZN N$.......N $N.......MN         MM   MM  MM   MM  MM   MM  MM   MM
     N.......MN NN.......N $N.......MN         MMMMMMM  MMMMMMM  MMMMMMM  MMMMMMM
     N....NN$"    "NN....N $N....NN",ON.            MM                           
     N.NNN"          "N..N $N..N" ,MN...MN.         MM                           
     NI"                "N $N" ,NM........"MM.      MM                           
                             MM...............MM                                 
                              "MMM.........MNM"                                  
                                 "MMN...NMM"                                     
                                    "NMM"  

##DOCS (wip)

• version
• requirements
• getting started
• config
• loading classes
• routing
• templates
• databases

##version this is actually version 2.x of the open qoob framework and is a complete rewrite from the ground up. if you're looking for the legacy versions, they are archived here:

• Framework: http://github.com/xero/open_qoob_legacy/
• CMS: http://github.com/xero/open_qoob_cms_legacy/

follow @openqoob for updates via social media

##requirements

• PHP 5.1.2
• mySQL 5.0+
• Apache mod_rewrite

##getting started ###database installation install the db.sql file on your mysql server. add the connection information to the qoob\app\config file.

###framework init to load the open qoob into memory in your index.php call:

$qoob = require('qoob/open_qoob.php');

to get your qoob reference in any other class call:

$qoob = qoob::open();

##config INI files can be used to load configuration variables into the library. pass the location of the file to the config method to load it.

$qoob->config('qoob/app/config.ini.php');

variables in the file will be added to the library with the CONFIG pseudo namespace.

somevar="something"

CONFIG.somevar

sections in INI files will become a second level namespace in CONFIG.SECTION.name syntax.

[general]
somevar="something"

CONFIG.GENERAL.somevar

###best practice i suggest naming INI files with a .php extension and adding ;<?php exit(); __halt_compiler(); to the first line. since INI files are simply text files, anyone who knows (or guesses) their location will be able to read them. giving the file a php extension and adding the exit directive to the first line will keep the file’s contents hidden.

here’s and example config.ini.php file:

;<?php exit(); __halt_compiler();
debug=true

[general]
author="xero harrison"
copyright="creative commons attribution-shareAlike 3.0 unported"
keywords="qoob, open qoob, openqoob, framework, code, api"
description="the open qoob framework"

##loading classes the qoob uses the new (php 5.1.2) spl_autoload methods for automatically loading classes. if your class exists within the qoob's file structure there is no need to call include or require before using it. this method is also namespace aware.

loading the benchmark class (located at /qoob/utils/benchmark.php):

$bench = new qoob\utils\benchmark;
$bench->mark('name');

it is also possible to load a class into the open qoob framework and have it be addressable via $this->classname internally or $qoob->classname externally. you accomplish with with the qoob load method, which is also namespace aware.

$this->load('qoob\utils\benchmark');
$this->benchmark->mark('name');

note: the load method will strip off the namespace and create a public variable from the name of the class only.

you can also autoload classes when in the config file is loaded. simply add the namespace and class as a value of the autoload config array.

here's an example of loading the benchmark and logz utility classes via the config file:

[autoload]
benchmark="qoob\utils\benchmark"
logz="qoob\utils\logz"

##routing the qoob has it's own routing system. routes map urls and requests to either anonymous functions or class methods. ###closure style callbacks when this route is requested the anonymous function will be called.

$qoob->route('GET /home', function() {
  echo '<h1>open qoob</h1><p>this is the home page.</p>';
});

###class method callbacks when this route is requested an instance of the some_class will be created and its some_method will be called.

$qoob->route('GET /something', 'some_class->some_method');

you can also use static methods

$qoob->route('GET /static', 'some_class::static_method');

you can also use class namespaces.

$qoob->route('GET /something', 'name\space\some_class->some_method');

route patterns have two required parts and one optional one.

• HTTP verb - GET, HEAD, POST, PUT, PATCH, DELETE, or CONNECT
• URI pattern - e.g. /home, /user/42, /blog/page/9, /test/:arg, etc
• request type optional - [SYNC] or [AJAX]

you can create URI argument variables with :name syntax. the results of which are passed to your callback function at run time.

$qoob->route('GET /user/:id', function($args){
  echo "user id: ".$args['id'];
});

$qoob->route('POST /date/:month/:day/:year', function($args){
  echo "data for date: ".$args['month'].'//'.$args['day'].'//'.$args['year'];
});

you can also create valid routes for mulitple HTTP verbs (e.g. GET or POST)

$qoob->route('GET|POST /hello', function($args){
  echo "hello word!";
});

using the optional request type allows you to handle the same route in two different methods depending on the context. use either the SYNC or AJAX keyword wrapped in square brackets. if a request type is not supplied SYNC is assumed by default. say you have a method that needs to return data in HTML for a synchronous (SYNC) request and JSON for an asynchronous (AJAX) request:

$qoob->route('GET /info [SYNC]', 'request_types->sync');

$qoob->route('GET /info [AJAX]', 'request_types->ajax');

RESTful apps respond to request semantically. so depending on the http verb used (e.g. GET, HEAD, POST) variables will be retrieved from a different request method. the qoob handles this internally and gives you access to appropriate ones via an argument variable $args passed to the constructor of a callback function.

$qoob->route('POST /testPostVars', function($args){
  echo "these are from the $_POST superglobal: ".print_r($args, true);
});
$qoob->route('GET /testGetVars', function($args){
  echo "these are from the $_GET superglobal: ".print_r($args, true);
});
$qoob->route('DELETE /testDeleteVars', function($args){
  echo "these are from php://input: ".print_r($args, true);
});

if uri arguments are present for a route, the uri arguments will be recursivly merged with the request variables

$qoob->route('POST /testMultiVars/:one/:two/:three', function($args){
  echo "these are from the uri request and $_POST superglobal: ".print_r($args, true);
});

##templates the qoob uses it's own "mustache style" template engine. this engine is very simple compared to other fully featured mustache implementations.

###loading a template load the 'stache' template engine. then call the stache->render function.

the function has two mandatory and one optional arguments:

• filename [string] - template file name (minus .html extension)
• data [array] - name value pairs to replace in the template file
• return [boolean] optional - auto echo on false, return string on true (default = false)

here's an example:

    $qoob->load('qoob\core\view\stache');
    $qoob->stache->render(
      'templateFileName', 
      array(
        'title' => 'open qoob',
        'body'=> '<p>hello world!</p>',
        'year' => date('Y'),
        'author' => 'xero harrison'
      )
    );    

you can also use templates with no replacements

    $qoob->load('qoob\core\view\stache');
    $qoob->stache->render('templateFileName');    

###creating a template creating stache templates are simple, you replace any dynamic value with a mustache variable! but templates are not limited to html. they could be emails, xml, excel, or any other type of text file.

here's an example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{{&title}}</title>
  </head>
  <body>
    <header><h1>{{&title}}</h1></header>
    {{@body}}
    {{!this is a comment}}
    <p>{{optional}}</p>
    <footer>&copy; {{#year}} {{#author}}</footer>
  </body>
</html>

###mustache types there are five types of mustaches that the qoob currently supports:

• {{var_name}} - regular variable (escaped)
• {{&unescaped}} - an unescaped variable (may contain html)
• {{!ignored}} - a variable that will not be rendered
• {{#required}} - required variables will throw exceptions if not set
• {{@unescaped_required}} - unescaped required variable

note: any non-required variable will be replaced with an empty string if not set by the render function.

##databases the qoob currently only supports mysql databases. while it's possible to use the mysql/mysqli adapter in any class, IMHO using models makes the most sence. to create a model simply create a class that extends one of the mysql classes: \qoob\core\db\mysql or \qoob\core\db\mysqli. add your connection variables in the class constructor then connect. after that all functions of the model will be ready to execute queries.

###connecting to a db server there are two methods necessary to connect to a mysql database, init and connect.

the init method takes four mandatory parameters and two optional ones.

• db_host [string] - the database server host name
• db_user [string] - the database users
• db_pass [string] - the password for the database user
• db_name [string] - the name of the default database to select
• asciiOnly [boolean] optional - true will allow only ascii characters, false will allow all printable characters (default = true)
• keepAlive [boolean] optional - true will not close the database on class destruction (default = false)

once the necessary variables are set with init simply call the connect function.

###sql queries mysql queries are setup very much like qoob routes. variables in your sql statements are prefixed with a : (colon) and are written inline. you also pass an array of name value pairs to be sanitized and replaced in your sql statement.

here's an example:

    $result = $qoob->mysql->query(
      "SELECT * FROM  `code` LIMIT :limit, :offset;",
      array(
        'limit' => 0,
        'offset' => 30
      )
    );
    print_r($result);

if you want to insert data, set the 3rd parameter of the query function (results) to false.

    $qoob->mysql->query(
      "INSERT INTO `code` (`code_id`, `key`, `val`) VALUES (NULL, ':key', ':val');",
      array(
        'key' => 'hello',
        'val' => 'world'
      ),
      false
    );

if you want the newly created ID from an insert statment, call the insertID function.

    $newID = $qoob->mysql->insertID();

if you want just a count of rows effected by your query set the 4th parameter to true. then call the num_rows function.

    $qoob->mysql->query(
      "SELECT * FROM  `code`;",
      array(),
      false, //dont return results
      true   //count rows
    );
    $count = $qoob->mysql->num_rows();

###auto-sanitization there are currently three methods of sanitization applied to each variable.

• stripslashes - only called if magic quotes are enabled (legacy compatability)
• asciiOnly - depending on the value of the asciiOnly class variable, all non-printable characters are removed. by default only ascii characters are allowed, if you need to support special/international characters (e.g. ñ, ½, etc) change the value to false.
• mysql_real_escape_string - uses the db server's internal sql injection protection routines.