Oxwall Software Documentation dev:core

Coding standards

2013-09-05T08:54:28+00:00

Coding standards

If you decided to write code for Oxwall make sure you observe code style standards described in this convention.

You don't HAVE to make your code look fancy to write a great plugin but think how others looking at your code would appreciate if it's written alike the rest of the Oxwall code. All rules in this convention are not taken “because we like it so” but were elaborated with readability, portability, compatibility, fail-safety and general acceptability in mind.

General

Always use full-form of PHP code tags:

<?php
?>

For files containing only PHP code, the closing tag ?> must be ommitted.

include_once and require_once are statements, not functions. Parentheses should not surround the subject filename.

//RIGHT
require_once 'header.php';
//WRONG
require_once('header.php');

Indenting

Use 4 spaces instead of tabs for an indent.

Naming conventions

Filenames

view.php
base_dao.php
my_super_class.php

Classes

class MySuperClass
{
    //code here
}
 
class PREFIX_MySuperClass
{
    //code here
}

Functions

function connect()
function camelCaseFunction()
function fooBar()

global functions

function my_global_function()

Vars

public    $myVar;
private   $hisVar;
protected $x;

Constants

define("MY_MEGA_CONSTANT", "Hello world");

Control structures

foreach, for, while, if, switch, try, catch etc.

There should be one space between the control keyword and opening parenthesis in control statements, which will distinguish them from function calls.

Use curly braces even in case they are optional, as this will make the code more readable and help to avoid logic errors appearing when new lines are added.

switch

switch ( condition ) 
{
    case 1:
        action1();
        break;
 
    case 2:
        action2();
        break;
 
    default:
        defaultAction();
        break;
}

if, else

Use else if statement instead of elseif

if ( $a !== $b )
{
    return false;
}
else if ( false )
{
    doSomething1();
}
else
{
    doSomething2();
}

long if statements

Split long if statements onto several lines

if ( condition1
    || condition2
    && condition3 )
{
    //code here
}

foreach, for, while

foreach ( $a as $v )
{
    echo $v;
}

try, catch

try
{
    //code here
}
catch ( Exception $e )
{
    //code here
}

Function declaration

All function names must be in a camelCase. Global functions are an exception. They should consist of words in lowercase and underscores.

There should be whitespaces before and after parameter list.

There should be no space between a function name and an opening parenthesis.

There should be a new line before return statement.

function fooBar( $param1, $param2 )
{
    if ( $param1 !=== $param2 )
    {
        //code here 
    }
 
    return true;
}

You should always declare a type of parameter when possible:

function doSomethingGood( MyClass $obj )
{
    //code here
}

Global function example:

function print_var( $var, $echo = false )
{
    //code here
}

Function calls

myCoolFunction(1, 2, 3);
$this->myCoolMethod(1, 2, 3);

Arrays

Indexed arrays

$arr = array ( 1, 2, 'no', 'pain', 'no', 'gain' );
$longArr = array ( 1, 2, 3,
                   4, 5, 6,
                   7, 8, 9 );

Associative arrays

$assoc = array ( 'key1' => 'value1',
                 'key2' => 'value2',
                 'key3' => 'value3' );

Core Code Reference

2012-10-24T11:06:36+00:00

Core Code Reference

On this tutorial's section will be described core's architecture and all major methods.

Page lifecycle

2013-02-15T03:43:40+00:00

Page lifecycle

Oxwall is under developement at the moment, so below you can see only preliminary version of page-lifecycle. Oxwall implements front-controller pattern and all requests are handled by single script - index.php (it is the only script available for user requests). Lets see how it works:

First of all .htaccess file in root directory helps us to redirect all requests to front-controller script.

Code of .htaccess:

Options +FollowSymLinks
RewriteEngine On
#RewriteCond %{REQUEST_FILENAME} !-f
#RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/index.php
RewriteCond %{REQUEST_URI} (/|\.php|\.html|\.htm|\.feed|\.pdf|\.raw|/[^.]*)$  [NC]
RewriteRule (.*) index.php

Below you can see the code of index.php script:

Code of index.php:

define('_OW_', true);
 
define('DS', DIRECTORY_SEPARATOR);
 
define('OW_DIR_ROOT', dirname(__FILE__).DS );
 
require_once(OW_DIR_ROOT.'includes'.DS.'init.php');
 
$application = OW_Application::getInstance();
 
$application->triggerEvent(OW_EventManager::APPLICATION_INIT);
 
$application->triggerEvent(OW_EventManager::ROUTE_STARTUP);
 
$application->route();
 
$application->triggerEvent(OW_EventManager::ROUTE_SHUTDOWN);
 
$application->dispatch();
 
$application->finalize();
 
$application->returnResponse();

As we can see index.php is very simple script representing a number of definite logic steps:

 <-- Page start -->

Define 3 basic constants

_OW_ - is indicator if core and other classes are included within the OW framework (kind of replacement for 'deny from all' instruction)
DS - short variant of standart PHP constant DIRECTORY_SEPARATOR
OW_DIR_ROOT - root directory constant for OW script modules

Include init.php script (loads modules for application startup)

load constants and configs to run the appliaction (stored in separate PHP files - define.php and configs.php)
load global functions (function.php)
load classes to be used by application in any case
register autoloader and error manager (exception interceptor, PHP error handler)

Create an instance of front-controller class (OW_Application) and initialize it

register non-autoloadable classes in autoloader object (Form, Inputs, etc)
add static routes from navigation system (static pages added from admin panel) in router object
register active plugins in plugin manager and load plugin init.php scripts (plugin initializers)
initialize core basic objects: request, response, event manager, theme manager, etc
create and add HTML document (OW_HtmlDocument) to response object

Trigger event APPLICATION_INIT

 <-- User request handling start -->

Route requested uri (Routing process)

search matching route in static navigation routes
— in custom static routes
— in dynamic routes
try to resolve requested uri with system default route

 <-- If matches were not found -> show 404 page -->

Trigger event ROUTE_SHUTDOWN

Dispatch routing results (dispatching process)

Check provided dispatch parameters
Create action controller instance;
Run controller action;
Get result markup and put it in HTML document object

Trigger event FINALIZE

Compile and send response

Compile document to send ( controller rendered body + master_page + html head part )
send added HTTP headers
send buffered debug output
send compiled HTML document

 <-- Page end (Here script dies) -->