PHP framework to help php developer

Introduction

This document is intended for web programmers and project managers who create PHP-based applications.

First, let us explain what we mean by a framework in terms of programming.

A beginner develops programme “from scratch”. When it starts working he thinks he has done everything properly. In reality he might not know why the program works but he is satisfied none the less.

More experienced programmers tend to reuse code written by themselves or other people. Over time they accumulate what is known as a “library”. Libraries speed up the development process and can improve the quality of the product.

Libraries suffer from the fact that they cannot be used in all cases. Writing a code that can be reused within a variety of applications is a complicated task. Only those libraries that are engaged in simple solutions, (for example, sorting by Mergersort algorithm or database drivers) are widely usable. A library consisting of modified or specific code is appropriate for use just within the applications it was meant for; its code ceased to be reusable.

When creating a large application, programmers have to be mindful of the fact that the function of the application may change over time. Only with this in mind can they create code that is modifiable and easily picked up by programmers who have not worked on the project from its inception.

Most libraries are not created with this level of foresight.

A framework is a specific sort of reusable code that forms an application structure. To be effective, it should be free from the pitfalls described above and should complement – not replace – a library.

The main difference between a library and a Framework is this:

a library is used by a programmer who selects a ready-made function or method available within it.
A framework effectively determines when the programmer’s code is put into action.

New Approach to Development: Organise Your Code

Magic Web Solutions as an experienced PHP development company offers a PHP Framework, which allows the development of virtually any kinds of PHP-based web applications in a completely fresh way. It follows all the basic principles of Object Oriented Programming and suggests new rules and conventions of web development. Our Framework will let your products look more professional and considerably reduce the time you spend on support.

Example of use

We need to create a very simple web application where users first register and then log in, using registered user names and passwords, something that usually requires many lines of code.To implement such an application based on the Framework, we just write down in the configuration file where the application is going to store users’ data. It might be a database or a file in XML-format. If it is a database, then we write in the configuration file the name of the table in question, and specify, which field would contain user names and which one is for passwords.The Framework will automatically form all the necessary queries and send them to the database or analyse the XML file.Now we can add information to another Framework configuration file specifying which forms are going to contain registration and login pages, and which fields those forms should consist of. For example, this file may contain information that a form is to include Framework_login and Framework_password fields, where the password field accepts strings no shorter than 14 characters, and login field requires the visitor’s email address.Here is an example of such a file:

This is necessary for the Framework to verify and validate data entered by a user.

Any field with a name starting with Framework_,will be verified by the Framework, rather than by application being used.

Using XML files to validate users’ data has many advantages. Imagine, that you need to change a table that contains information entered by user. For example, the field that stored Numeric values has to be altered to store Short numbers, or, more critically, Strings. Normally, you would have to change the application. With frameworks, we don’t need to redo the PHP coding – we can simply rewrite the XML config file.

Then, it will be enough to add to the handler folder a file named login_handler.php, which would resemble the following:

Class LoginHandler extends HandlerBase{
Function LoginHandler(){
Parent::HandlerBase();
}
function handle($request){
If( $request->IsAuthorized() ){

// add your code here
}
}
}

The Main Benefits That Come With the Framework

You can create better applications faster, because the Framework handles many common routines itself. For example, the Framework will check and validate data, submitted by a user. If the Framework detects an attempt to hack a web application using Cross Site Scripting or SQL injection, the information will not get as far as the application, and the user will be redirected to the same page and will see an error message. You can set up or disable this functionality as you wish. The same applies for most of the Framework functionality
It is easier to modify an application. The Framework implements design patterns described in, perhaps, the best known source devoted to the topic.
An application becomes more convenient for support. Thus, some significant modifications that would have required the participation of a chief developer, are now easily implemented via the Framework config file.
The Framework allows easy integration with any PHP library. The Framework is created using PEAR, which is widely recognised as a standard PHP library.

Brief Description

In order to use the Framework, the programmer has to place his files into the correct folders for the Framework to look for them.

After extracting contents from archived file with the Framework distribution kit, the following folder structure will be created on your hard disk:

docroot is the only folder that should be visible from the World Wide Web and accessible from a browser.

This folder necessarily contains an index.php file. However, you can name it index.html or choose any other extension. Note, that, if you rename it, you should not forget to include its new name in the include/constants.php file, which is the main setting file of the Framework. Index.php implements the Front Controller design pattern.

Several Framework configuration files are included in the conf folder, while conf/auth contains only those configuration files that store users authorisation settings.
The include folder and its sub-folders contain programme code of the Framework and that of the application. include/compiler, include/validator, include/auth, include/view_dispatcher, and pear folders should not be of any interest for an application developer. These are used only by the Framework for its own purpose, and their functions is described in “How to Create Framework Extensions” document.
The classes folder is for application files. These files do not necessarily contain classes. They can contain any sort of PHP code, with just one restriction: this code should never send to the browser any data via print, echo, or similar PHP functions. All HTML code should be collected in specific files, which we will describe below. The Framework helps, even compels a developer to separate application code from HTML. That significantly simplifies programme modification, as designers will only modify HTML code and only programmers will work with PHP files. Due to such a structure, a designer can independently alter an application layout with little need to change PHP code.
The include/custom_constants folder contains files with constants, employed by the Framework and the Framework-based application for their interaction. For instance, we recommend addressing HTML form fields not by their names in HTML tags, but by means of constants described in the include/parameter_names.php file.

Request handlers added to the framework should be put into the handler folder. The names of request handler files end with _handler.php, for example, login_handler.php. These files contain classes with names such as WEB_Handler_Register _handler-name.These classes inherit from WEB_Handler_Base class.The request handler in the register_handler.php file class should look like this:
Class WEB_Handler_Register extends WEB_Handler_Base{
/**
@Return Object
*/
Function handle()
$request = $this->getRequest();
…………..
}
…The Framework will call the handle() method of a handler, and all the data concerning the users’ requests will be passed via the $request parameter.Every request from the browser to a Framework-based application will contain a special parameter interpreted not only by an application, but also by the Framework. This parameter allows the Framework to recognise, what kind of request has come, and which request handler it should be passed to. The developer is responsible for inclusion of this parameter into all the links and form action parameters of all visible pages.The Framework can call a sole request handler in response to several different requests. Which one it should be is described by the application developer in the correspondent configuration file.

So, in order to add a new page to an application (or several pages), all the developer has to do is:

Write handlers for them.
Describe, in the include/custom_constants/action_constants.php file, a new constant for every kind of request that an application may receive (for example,
define(‘SUBMIT_REGISTER’,2); for a registration request); and
Describe, in the conf/handlers.xml file, which handler corresponds to which request..New pages with new functionality can be added to an existing application, even one with many pages. With the Framework, it will take only seconds to put existing code together with new lines, and let a user see new pages.The programmer benefits from the Framework most noticeably, when she has to change an application that is not her own – and that is most often the case.

The required folder is intended for libraries that are not written by the authors of the application they are required for. Its files will be accessed by an application via include_path.
The templates folder is to store files containing actual HTML code of an application pages.

If an application contains a considerable number of pages, it is recommended that templates are used. The Framework distribution kit is completed with two systems intended for generating HTML pages out of templates. One of them is based on Smarty (), the other is more simple.

Using conf/view_dispatcher.xml, the Framework can be set up for use with the choice of systems, or a completely new one can be added.

The simplified system is meant to speed up the programmer’s familiarisation with the Framework. For Smarty, see the vendor’s home site for information.

When using the simplified system, a separate file in the templates folder corresponds to each page. That file will be shown to a user, and all PHP code in it will be interpreted. Of course, this file can include other files via an include PHP function.

Most important, HTML code and PHP code should be separated. Files in the templates folder can be given to a designer who will entirely change an application layout or, for instance, replace HTML with WML. To do this, the designer will not need any files outside the templates folder.

Example of use
Class WEB_Handler_SomeData extends WEB_Handler_Base{
/**
@Param Object $request
@Return Object
*/
Function handle($request){
/**
This object’s properties and methods allow to get all the information sent by a browser in a form suitable for processing.
*/
$request = $this-> getRequest();
/**
Every handler must return an object belonging to the View class, so that the Framework will recognise, what page to display for a user.PAGE_USER_LIST constant is a way to inform the Framework, what page it should display for a user after this handler has been called.The conf/view_dispatcher.xml Framework configuration file should contain information, which page this constant corresponds to.Certainly, one can use a literal value instead of a constant name.
*/
$ret = new View();
$ar_parameters = array();
if($request->hasParameter(‘USER_WANT_VIEW_SOME_DATA’)){
}
$ar_parameters[“SOME_DATA”] =”This data is created by the request handler.”;
$ret->setParameters( $ar_parameters );
$ret->setId(PAGE_USER_LIST);
return $ret;
}
…The following code demonstrates how a page from the templates folder might look. File name and extension could be whatever you like. The most important thing is that they should be included into the conf/view_dispatcher.xml configuration file. The Framework will display this page to a user, when a request handler ‘asks’ to display it:if(isset($parameters[‘SOME_DATA’])){
?>

} else{
?>No Data}
?>

…

Framework Documentation

In order to use the Framework, it is enough to read the documentation for the following classes:

FrontController
WEB_Handler_Base
Request
Response
Pool

Detailed information is given in the doc files in the documentation/API folder of the distribution kit.

Here, we briefly describe the goals and the most important characteristics of those classes.

1. FrontController – an abstract class that implements the Front Controller^iv design pattern. The default implementation is in the DefaultFrontController class. Every request to a web-application is at first handled by a handle() method of this class.

2. WEB_Handler_Base – an abstract class. In order to create a request handler, you should inherit from this class, and implement the doHandle() method. An inherited method getRequest() will return a Request object, which will pass all information about a user’s request to a handler.

Another important method is getResponse(), which will return a Response object to a handler. From this object, the handler will extract the name of the page the Framework should display to the user in response to a request, and determine, which kind of data will be passed to the page generating code.

A handler should not send any HTML code to a browser!

One handler may call another one, and it is possible to send raw user’s data to the second handler, or modify it first. A response from another handler can be passed to the Framework modified or without modification.

The Framework offers functionality that we will call “filters”. A web-developer can write into the configuration file that requests with some special parameters should be handled by several handlers in turn.

An example is an application that contains a handler and sends queries to a database, then returns the results of those queries to the Framework. The Framework then displays those results to a user. Later on, it might become necessary to enhance functionality, for example, to verify user’s data more thoroughly, in order to prevent an SQL Injection attack; to write information on request and response into log file, to find a subtle bug; or to notify an administrator via e-mail.

For instance, in the case of an application that works as a forum, it might be necessary to check user’s text for obscene words.

The Framework allows you to add supplementary functionality to your handler without any modification of existing code. Due to this, things that worked beforehand, will not cease working after a new functionality is added.

It is enough to place that additional code into an additional handler as a “filter”. You can filter data sent by a user, as well as data returned by a handler in response to it.

3. Pool. This class contains only one method worth mentioning, and it is getConnection(). It helps you to get a database driver object. A connection name should be passed as a parameter, for example, “my_database” or “other_database”. A purpose of this class is to spare an application author from to including connection parameters in application code, even as constants.

The compliance between the connection name that is sent as a parameter into getConnection(), and a real name of the database, user name and password, is set up in the configuration file of the Framework. The file in question pool.ini or pool.xml is located in the conf folder.

Coding Convention

The Framework uses the same coding conventions that apply to PEAR project. Documentation for PEAR can be found at pear.php.net.

Examples of Use

All the source code of the examples can be found in the examples folder of the distribution kit.

Example 1.
Shows how to create a Framework-based application containing one page without registration and authorisation of users.

Example 2.
Here, on the base of the Framework, we create a one-page application, but users’ registration and login functionalities are added.
For authorisation, we use a default page provided by the Framework.

Example 3.
This is an example of an application that is based on the Framework and that contains one page with users’ registration and log in details.
A page written by an application developer, is used for authorisation purpose.
Users’ information is stored in the database.

Example 4.
In this example, we demonstrate how to create a Framework-based application with one page plus registration and authorisation of users in conjunction with a page written by an application author.
LDAP catalogue is used to store users’ data.

Example 5.
This presents a Framework-based application with one page, registration and login added. The login page is written by an application developer and contains several forms. In this example, the Framework checks the validity of users’ data.
Users’ information is stored in the database.

Example 6.
This shows how to create a Framework-based application that contains several pages and several handlers.
A page written by an application author, is used for login functionality.
The page contains several forms, and the Framework validates users’ data.
Information on users is stored in the database.

Example 7.
An example of a Framework-based application employing filters, with several pages and several handlers.

MagicWeb PHP Framework