Let's take a look at some of the pages in our application.

“Home” and “About Site” just displays a static page and thus we haven't included “About Site” page in our screenshots. The other two, “Register” and “Login”, includes a form for the user to fill-up and for us to validate.

Our directory structure for our default module will be like the screenshot below.

The uniformity of our pages look was done through our use of Zend_Layout, one of the most useful feature, in building a web application.

In our previous post, we declared in pur bootstrap file that we will be using MVC for our aplication and defined the directory our template files. So, Let's take a look at the important part our template file ( templates/front.phtml ), the full source code of our working applicatio can be downloaded at the end of our tutorial.

1.) The code below creates the title tag in our html part ( including the title tag itself ). The prepend method tells that we will insert the string “ZF Connections” in or every page and adds a separator of “::”. We could see the effect of this on the screenshots displayed above.

 
$this->headTitle()->prepend('ZF Connections');
$this->headTitle()->setSeparator(' :: ');
echo $this->headTitle();
 

2.) The next code below includes the css files in our application. It will insert all of the necessary attributes for a valid inclusion of css file.

 
echo $this->headLink()
->appendStylesheet($this->baseUrl . '/styles/blueprint/screen.css', 'screen')
->appendStylesheet($this->baseUrl . '/styles/blueprint/print.css', 'print')
->appendStylesheet($this->baseUrl . '/styles/zf.css', 'screen')
 

3.) The folowing just includes the necessary files located at the same directory as our template file.

 
<?php echo $this->partial('front-top-lang.phtml') ?>
<?php echo $this->partial('front-header.phtml') ?>
<?php echo $this->partial('front-footer.phtml') ?>
 

4.) The following is a little bit different than the previous one, for it wil loop the content of the parameter passed.

 
<?php echo $this->partialLoop('front-navigation.phtml', $this->urls) ?>
 
// font-navigation.phtml contains the following
<a href="<?php echo $this->url ?>"><?php echo $this->name ?></a> |
 
// and urls is declared in the basecontroller as
private function getLinks() {
$url = $this->getHelper('Url');
return array(
array('name' => 'Home',
'url' => $url->url(array('controller' => ''))),
array('name' => 'About Site',
'url' => $url->url(array('controller' => 'about-site'))),
array('name' => 'Register',
'url' => $url->url(array('controller' => 'register'))),
array('name' => 'Login',
'url' => $url->url(array('controller' => 'login')))
);
}
 
//and set on the init method
$this->view->urls = $this->getLinks();
 

5.) The most important and the simplest part of our layout will be displaying the actual content of the controller called.

 
<?php echo $this->layout()->content; ?>
 

We have seen the layout.phtml and now its time to delve into our controlelr classes.

We will discuss the abstract BaseController class upon which all of our controllers on our default module extends upon. BaseController does the work of initializing our FlashMessenger, setting the baseUrl on the view, setting the the layout and links, and other methods.

We have three protected methods on our BaseController class, 1.) validateForm which accepts a Zend_Form instance as its first parameter and the array of data to validate upon, 2.) redirectToController which accepts a controller name and an optional action name as its second parameter, and 3.) addSucessMessage which takes a stirng parameter as message and store it in our flashMessenger.

We have also another helper controller namely the FlashMessagesController. It's only job is to fetch all the messages stored on our FlashMessenger and display it as well as parse upon which kind of message is stored ( success, notice, or error ). We will be including this action through one of view's helper, namely action helper ( nice name ).

Its only method, indexAction, contains the following code:

 
if($this->_flashMessenger->hasMessages()) {
$display_messages = array();
$messages = $this->_flashMessenger->getMessages();
foreach($messages as $message) {
if(substr($message, 0, 4) == 'type') {
$type = explode('=', $message, 2);
$this->view->messages_type = $type[1];
} else {
$display_messages[] = $message;
}
}
$this->view->messages      = $display_messages;
}
 

 
// and this will be the phtml file for displaying our message
<?php if($this->messages && is_array($this->messages)): ?>
<div class="<?php echo $this->messages_type ?>" style="width:350px" align="left">
<?php if(isset($this->messages[1])): ?>
<?php echo $this->formErrors($this->messages) ?>
<?php else: ?>
<?php echo $this->messages[0] ?>
<?php endif; ?>
</div>
 
<?php endif; ?>
 

Our IndexController and AboutSiteController are pretty straightforward and just displays their properly configured view file. We have configured these controller files to load the view file in a separate directory, instead of their default ones. The code looks like the following:

 
// IndexController ( indexAction )
$this->render('home', null, true);
 
// AboutSiteController ( indexAction )
$this->render('about-site', null, true);
 

This line of code tells us that we will load the about-site.phtml in top directory of views folder, meaning not under any controller specific subdirectory ( the true argument on render particulary says that the view does not have a controller ). The second argument (null ), simply tells that we will be including all the segment of the response object.

Now we'll have to take a look at our RegisterController. RegisterController does some other things beside displaying the register page. In this controller, we will creae a Zend_Form to be included in the view area, validates our form after submission and displays messages based on the result of validation ( success or error ).

We first take a look at the creation of form defined on the getForm() method on our RegisterController.

 
$form = new Zend_Form();
$form->setAction($this->_request->getBaseUrl() . '/'
. $this->_request->getControllerName() . '/signup')
->setMethod('post');
 
$email = $form->createElement('text', 'email', array('class' => 'text'));
$email->addValidator('EmailAddress')
->setRequired(true)
->addFilter('StringToLower')
->addFilter('StringTrim')
->setLabel('Email Address');
 
$submit = $form->createElement('button', ' Submit ', array('type' => 'submit', 'class' => 'button'));
 
$form->addElement($email)
->addElement($submit);
 
return $form;
 

Creating of Zend_Form is pretty straightforwad, the trivial part is the creation of its action. We didn't hard-code the action of our form so that our form will be more flexible and we won't be changing any the form's properties.

Our email element was created through the form's createElement method. We have created a input element with type of text, with name of email and a class of text.
We have added a validator for the element, EmailAddress, or we could have written the validation just like the following instead:
$email->addValidator(new Zend_Validate_EmailAddress());

And we have added some filters, StringToLower and StringTrim, which are quite straightforward. And lastly we have added a label to the element.

The next element on our form is the submit button. we have used button element with type of submit.

After the two elements were created, we have added the two elements back on the form for display.

Our signupAction which do the validation of our form is as simple as the following code:

 
if(!$this->_request->isPost()) {
return $this->redirectToController('register');
}
 
if(!$this->validateForm($this->getForm(), $_POST)) {
return $this->redirectToController('register');
}
 
$message  = '
 
Thank you for joining ZF Connections
 
';
$message .= '
 
Your login credentials will be submitted in the email that you have provided.
 
';
$this->addSuccessMessage($message);
return $this->redirectToController('register');
 

First we, checked is submitted via post method. The next checking is actually checking of forms for theie errors. If the form does not have any errors we just display a message ( for now ). All of the following cases will end up redirecting to the “register” controller.

The validateForm method on our BaseController is defined as follows:

 
protected function validateForm(Zend_Form $form, array $data) {
if(!$form->isValid($data)) {
foreach($form->getMessages() as $field => $message) {
foreach($message as $error) {
$this->_flashMessenger->addMessage(strtoupper($field) . ' ' . $error);
}
}
$this->_flashMessenger->addMessage('type=error');
return false;
}
return true;
}
 

The method checks the form and add any errors generated and add it to our flashMessenger.

LoginController is almost the same as RegisterController, the only difference is that LoginController has an additional element on its form which is the password element. You can download our working application below and take a look on how we have glued together our application.

Our next topic will be creating a Model for database interaction and finishing up our registration and login. We will be using more ZF classese like Zend_Auth, Zend_Acl, Zend_Log and other classes we may need as we code.

See you next time and happy coding! =)
Download Files Here ( Zend Framework is not included in the zip file dure to file limitation ):
ZF Tutorial Part2 - Files

Our project for this tutorial, ZF Connections (a social networking site), will be designed in such a way that adding a functionality will be as easy as possible by extending it using a module. This tutorial assumes the reader of familiarity of PHP5 and OOP terminologies.

Our application will be divided into three main modules, admin module, members module, and the default/application module. The first module (admin module) will be used for administrative tasks on our application, the members module will focus more on the members/users of the application and the third one, default/application module, will be focusing on the overall or general part of our application.

Now that we have the basic requirement for our application, let's begin to dig a little deeper. For our admin module, all modules installed must be accessible only through the following url: http://localhost/admin//, as well as the members module must only be accessible in http://localhost/members//. The default/application modules must be accessed regularly as http://localhost//. The problem here is that we must have a directory structure upon which adding a directory under some “modules” directory will automatically create the route/url for us and its controllers and models will be properly included and initialized.

The directory structure I have come up with was like this:

-- [root]
---- _tests
---- application
------ admin
------ default
------ members
------ modules
-------- default
-------- members
-------- admin
------ templates
---- html
---- library
---- resources

Our directory structure has five top-level directories, but only four will be deployed ( _tests, application, html, library, resources ).

_tests directory will contain all of our test cases

application directory will contain our modules (default modules and sub-modules)

html directory will contain all files visible to the public ( images, js, css, view files )

library directory will contain all of the classes that we will be using including the Zend Framework, and other classes as we go along into our tutorial.

resources directory will contain all of our configuration files.

Let's take another look at our application directory.
-- application
---- admin
---- default
---- members
---- modules
------ admin
------ default
------ members
---- templates

The three subdirectories ( admin, defualt, members ) will be our default or predefined modules in our application, “default” is a predefined module in Zend Framework.
The other directory, modules, on which there are three subdirectories on which the three predefined modules are named alike plays a significant role in our application design. Every modules defined on one of the subfolders will be automatically included as a submodule of our predefined module. Consider the follwing module example module placed under modules/members

---- modules
------ members
-------- message
---------- controllers
---------- models
---------- views

The message module upon placing it under the members module will automatically qualify it as a submodule of members module. Whew! The message module can now be accessed through the following url: http://localhost/members/message/ .
Every modules placed under the subdirectories of our predefined module names ( as well as other module names ) under modules directory will also be rerouted correctly.

Placing other inside other module name directory beside our predefined subdirectory is also possible. Consider the following example.

---- modules
------ others
-------- other
---------- controllers
---------- models
---------- views

The follwing module can be accessed through the url:
http://localhost/others/other

The magic(logic) behind accessing and plugging module is in our bootstrap file.
It's time we take a look at our bootstrap file and dissect it part by part later. We will not be talking the classes involved in detail, we will only discuss it in depth as soon as we will be using it extensively or in a major part of the application.

This is our index.php file.

 
<?php
/**
 * Zend Framework Tutorial
 *
 * @author Ronald de Leon
 * @version 1.0
 */
 
error_reporting(E_ALL|E_STRICT);
date_default_timezone_set('Asia/Manila');
 
define('SYSTEM_PATH', dirname(__FILE__));
define('APPLICATION_PATH', dirname(SYSTEM_PATH) . DIRECTORY_SEPARATOR . 'application');
define('RESOURCE_PATH', dirname(SYSTEM_PATH) . DIRECTORY_SEPARATOR . 'resources');
 
// set include path to include files in our library directory on which the
// zend framework is located
set_include_path(get_include_path() . PATH_SEPARATOR
				  . dirname(SYSTEM_PATH) . DIRECTORY_SEPARATOR . 'library'
				);
 
// load Zend_Loader class and make it automatically auto load all of our classes,
// no more long includes/requires and Zend_Loader::loadClass
require_once 'Zend/Loader.php';
Zend_Loader::registerAutoload();
 
// // setup database config file by loading configuration through our ini file located at resource directory
$dbConfig = new Zend_Config_Ini(RESOURCE_PATH . DIRECTORY_SEPARATOR . 'database-config.ini', 'staging');
 
// setup database resource through our config file
$db = Zend_Db::factory($dbConfig->database);
 
// set db to be used as default default adapter in all of our application models
Zend_Db_Table_Abstract::setDefaultAdapter($db);
 
// set-up layout options to be used for our project
$layoutOptions = array(
	'layoutPath' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'templates', // our template directory
	'layout'	 => 'front' // our default layout
);
// set layout configuration to Zend_Layout class
Zend_Layout::startMvc($layoutOptions);
 
// define default modules directory
$defaultModules = array(
	'default' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'default',
	'members' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'members',
	'admin'   => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'admin'
);
 
// get front controller instance
$controller = Zend_Controller_Front::getInstance();
 
// get router from front controller
$router = $controller->getRouter();
 
// iterate default modules
{
	foreach($defaultModules as $key => $module) {
 
		// add default controller directories
		$controller->addControllerDirectory($module . DIRECTORY_SEPARATOR . 'controllers', $key);
 
		// add models directory to include path
		set_include_path(get_include_path() . PATH_SEPARATOR . $module . DIRECTORY_SEPARATOR . 'models');
 
	}
}
 
$controller->throwExceptions(true); // should be turned on in development time
 
// define modules directory
$moduleFolder = APPLICATION_PATH  . DIRECTORY_SEPARATOR . 'modules';
 
// this is where the code that makes our application extendable through modules
{
	$modules = scandir($moduleFolder); //scan module folder for saved modules (top level modules will be scanned {application, members})
	foreach ($modules as $module) {
 
		if($module[0] == '.') continue; // if search directory starts with a dot, skip directory
 
		$subModulePath = $moduleFolder . DIRECTORY_SEPARATOR . $module; // this will be the submodules directory directly under parent module. e.g. application
		if(is_dir($subModulePath)) {
 
			$subModules = scandir($subModulePath); // scan the submodules directory for specific modules defined
 
			foreach($subModules as $singleModule) { 
 
				if($singleModule[0] == '.') continue; // if search directory starts with a dot, skip directory
 
				$modulePath = $subModulePath . DIRECTORY_SEPARATOR . $singleModule; // this will be the actual module or specific module found
				if(is_dir($modulePath)) {
 
					// add to include path, models directory
					set_include_path(get_include_path() . PATH_SEPARATOR
							. $modulePath . DIRECTORY_SEPARATOR . 'models');
 
					// add controllers to controller directory
					$controller->addControllerDirectory($modulePath . DIRECTORY_SEPARATOR . 'controllers', $singleModule);	
 
					// add to router
					// if module is under application set router to default directory
					if($module == 'default') {
						$router->addRoute('', new Zend_Controller_Router_Route($singleModule));
					} else {
						// if module is under not a member of default module set router to /${module}/{singleModule}
						$router->addRoute($module . '/' . $singleModule, new Zend_Controller_Router_Route($module . '/' . $singleModule,
							array(
								'module'	 => $singleModule,
								'controller' => 'index'
							)
						));
					}
 
				} // end checking {is_dir($modulePath)} 
 
			} // end loop of submodules directory
 
		} // end checking {is_dir($subModulePath)}
 
	} // end looping of modules directory
 
} // end group bracket
 
// run application
$controller->dispatch();
?>
 

The first two lines of code in our framework will be setting some important configuration. Setting error reporting to ALL or STRICT, and setting default timezone to Manila, Philippines.

The next lines defines some paths to be used in accessing certain files in our layout such as the APPLICATION_PATH and RESOURCE_PATH.

The following line loads Zend_Loader and tells the class to automatically load all defined class.

require_once 'Zend/Loader.php';
Zend_Loader::registerAutoload();

The next lines of code setup our database connection by specifying and loading the configuration thru a database-config.ini file located in our top-level resource directory and loaded it through Zend_Config_Ini to be automatically parse our ini file. The 'staging' part is a way to tell Zend_Config_Ini that we will be using the 'staging' part in the config file. We chose to use Zend_Config_Ini instead of Zend_Config_Xml because the codes are easier to read in an ini file than in an xml file.

We get the db adapter or resource from Zend_Db class by passing our config object. The last part tells that we should always or our db adapter defined here will be used if no adapter is specified. Our DB adapter is of type Zend_Db_Adapter_Pdo_Mysql, it automatically detects to load the particular class by parsing our ini file.

// // setup database config file by loading configuration through our ini file located at resource directory
$dbConfig = new Zend_Config_Ini(RESOURCE_PATH . DIRECTORY_SEPARATOR . 'database-config.ini', 'staging');

// setup database resource through our config file
$db = Zend_Db::factory($dbConfig->database);

// set db to be used as default default adapter in all of our application models
Zend_Db_Table_Abstract::setDefaultAdapter($db);

// filename: database-config.ini
// our database configuration
; Production site configuration data
[production]
database.adapter = pdo_mysql
database.params.host = dbhost
database.params.username = dbuser
database.params.password = dbpassword
database.params.dbname = dbname

; Staging site configuration data inherits from production and
; overrides values as necessary
[staging : production]
database.params.host = localhost
database.params.username = root
database.params.password =
database.params.dbname = zfconnections_development
database.params.profiler = true

The following defines our layout options and set the options to our Zend_Layout class. Upon callinf the startMvc method, our application assumes that we will be using layouts for our application on which the layouts wil be located on the paths specified in our 'layoutPath' and our default layout if none specified will be 'front'.

// set-up layout options to be used for our project
$layoutOptions = array(
'layoutPath' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'templates', // our template directory
'layout' => 'front' // our default layout
);
// set layout configuration to Zend_Layout class
Zend_Layout::startMvc($layoutOptions);

In the codes below, we define our default modules in an array so that we could iterate overt it at a later time. Instantiate our fromt controller by calling its static method getInstance(), retrieve the router object from our front controller and iterate our default module directory so that its 'controllers' directory will be added in our front controller's controller directory and our models directory will be added in our include_path.

// define default modules directory
$defaultModules = array(
'default' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'default',
'members' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'members',
'admin' => APPLICATION_PATH . DIRECTORY_SEPARATOR . 'admin'
);

// get front controller instance
$controller = Zend_Controller_Front::getInstance();

// get router from front controller
$router = $controller->getRouter();

// iterate default modules
{
foreach($defaultModules as $key => $module) {

// add default controller directories
$controller->addControllerDirectory($module . DIRECTORY_SEPARATOR . 'controllers', $key);

// add models directory to include path
set_include_path(get_include_path() . PATH_SEPARATOR . $module . DIRECTORY_SEPARATOR . 'models');

}
}

The code below tells that we will be throwing some exceptions.
And it SHOULD be turned off on our live site.

$controller->throwExceptions(true); // should be turned on in development time

The last code is lies the nitty gritty details of our application's secret to its extensible modular design.
The first part tells us where the modules are located.

// define modules directory
$moduleFolder = APPLICATION_PATH . DIRECTORY_SEPARATOR . 'modules';

this is the part where we scan the modules directory for any directories under it, except if it starts with a dot (.)

The comments on the codes will be enough to tell what the application is doing.

// this is where the code that makes our application extendable through modules
{
$modules = scandir($moduleFolder); //scan module folder for saved modules (top level modules will be scanned {application, members})
foreach ($modules as $module) {

if($module[0] == '.') continue; // if search directory starts with a dot, skip directory

$subModulePath = $moduleFolder . DIRECTORY_SEPARATOR . $module; // this will be the submodules directory directly under parent module. e.g. application
if(is_dir($subModulePath)) {

$subModules = scandir($subModulePath); // scan the submodules directory for specific modules defined

foreach($subModules as $singleModule) {

if($singleModule[0] == '.') continue; // if search directory starts with a dot, skip directory

$modulePath = $subModulePath . DIRECTORY_SEPARATOR . $singleModule; // this will be the actual module or specific module found
if(is_dir($modulePath)) {

// add to include path, models directory
set_include_path(get_include_path() . PATH_SEPARATOR
. $modulePath . DIRECTORY_SEPARATOR . 'models');

// add controllers to controller directory
$controller->addControllerDirectory($modulePath . DIRECTORY_SEPARATOR . 'controllers', $singleModule);

// add to router
// if module is under application set router to default directory
if($module == 'default') {
$router->addRoute('', new Zend_Controller_Router_Route($singleModule));
} else {
// if module is under not a member of default module set router to /${module}/{singleModule}
$router->addRoute($module . '/' . $singleModule, new Zend_Controller_Router_Route($module . '/' . $singleModule,
array(
'module' => $singleModule,
'controller' => 'index'
)
));
}

} // end checking {is_dir($modulePath)}

} // end loop of submodules directory

} // end checking {is_dir($subModulePath)}

} // end looping of modules directory

} // end group bracket

// run application
$controller->dispatch();

That's it! Now we have a base design for our application. Next topic we will be discussing on ZF Core components, particularly the MVC components. We will be building the front-end of our application, No database access yet, but we have already defined here our database configuration so theres not much of a problem when we will be using some database access. Our front end development of the application will be focusing on the Zend_Action, Zend_Layout, Zend_View and the our Zend_Form as well on the Request and probably the Response object.

See yah! :-p

The project will be called ZF Connections, an online community with user profiles, messaging, posting of ads and blogs.

Next post, we will be discussing our directory structure, and how we could separate our modules in their own directories and our bootstrap file.

Attribute-oriented programming (@OP) is a program-level marking technique. Programmers can mark program elements (e.g. classes and methods) to indicate that they maintain application-specific or domain-specific semantics.

With annotations, we could add some "markers" in a class in an unobtrusive way by annotating a property, methods or class inside it's PHPDoc block. Some of the uses I thought of while doing this article includes.

1. an easy way to inject dependencies (IOC) on methods of a class like an @Inject(Google Guice) annotation.

2. a way in marking a class to map with a persistent layer. e.g @table, @column, etc. like in JPA

3. a way in marking a method to log everytime it is called with @log annotation.

The above examples are just 3 of some hundred of uses with annotation based attribute. And the fun part is, the annotations are totally unobtrusive because it is declared inside a PHPDoc block.

An example of an annotated class in PHP is given below:

 
<?php
 **  
 
 * User entity  
 
 *  
 
 * @author Ronald A. de Leon  
 
 * @table(name = 'users', type ='innodb')  
 
 */  
 
class User {  /**  
 
  * username of user  
 
  *  
 
  * @var string  
 
  * @id()  
 
  * @column(name = 'username', unique = true, updatable = false)  
 
  */  
 
 private $username;  
 
/**  
 
  * @column(name = 'first_name')  
 
  */  
 
 private $firstName;  
 
/**  
 
  * @column(updatable = 'true')  
 
  */  
 
 private $lastName;  
 
 private $notImportant;  
 
/**  
 
  * transient property  
 
  *  
 
  * @var string  
 
  */  
 
 private $fullName;  
 
/**  
 
  * return username  
 
  *  
 
  * @return string  
 
  * @log(type = 'trace')  
 
  */  
 
 public function getUsername() {  
 
 	return $this->username;  
 
 }  
 
/**  
 
  * return fullName  
 
  *  
 
  * @return string  
 
  */  
 
 public function getFullName() {  
 
 	return $this->fullName;  
 
 }  
 
}  
 
?>
 

We have annotated the User class with pseudo annotations like @id, @column, @table. So let's define our goal:
1. We have to properly extract all our custom-based annotations.
2. We have to do something with our extracted data. ( We will discuss this in Part 2 where we will build a simple EntityManager class for our annotated classes )

Our first goal is be able to retrieve all of the values as well as the annotations provided on the class. There are some considerations that we will be dealing. First, we should not parse default annotations provided by PHPDoc ( @var, @param, etc ). Second, a property, method or class can have zero to multiple annotations, and there should be a rule on where an annotation can only be provided in property but not on the class or method level.

So let's start developing our annotation parser and have to address the goals we have defined. The two goals we have given can be combined into one simple goal: "PROVIDE A LOOKUP FOR ALL THE VALID ANNOTATIONS FOR CLASS, METHOD AND PROPERTY."

To address the issue, we will have a static private property on our parser containing our rule. We can store that in an array. Here's the implementations that I came up with:

 
<?php
private static $validAnnotations = array(  
 
 	'class' => array(  
 
 		'@table' => array('name', 'type')  
 
 	),  
 
 	'properties' => array(  
 
 		'@column' => array('name', 'insertable', 'updatable', 'unique'),  
 
 		'@id' 	  => array('generator'),  
 
 	),  
 
 	'methods'	=> array()  
 
 );
?>
 

The key for the implementation of our parser relies on one of the coolest class in PHP, the ReflectionClass. With the ReflectionClass, we could extract all of the metadata for the passed object including the documentation block for the class, methods and properties.

An example of an implementation of the ReflectionClass is as follows:
$reflect = new ReflectionClass(new User());

After the following line, we could now extract all of our needed data, including getting all of the methods and properties of the User object as well as their PHPDoc if there is one. The key of extracting our annotations lies with the 'getDocComment' method. The 'getDocComment' method returns the PHPDoc block of the given data (Reflection family type e.g. ReflectMethod, etc.)

The next thing will just be some simple string matching (RegEx is your friend here ) on the PHPDoc block with our static private rule property as our validator.

Once we have done this, we could extract our gathered data in some kind of 'AnnotationProxy' object where we could referenced the annotated methods, properties, etc.

The code below shows how I implement this behavior. Downloadable files are attached at the end of this article including the UnitTest for our parser (PHPUnit is needed to run the test).

 
<?php
/**  
 
 * Parser of the Pseudo annotations  
 
 *  
 
 * @author Ronald A. de Leon  
 
 *  
 
 */  
 
class AnnotationParser {	private static $validAnnotations = array(  
 
 	'class' => array(  
 
 		'@table' => array('name', 'type')  
 
 	),  
 
 	'property' => array(  
 
 		'@column' => array('name', 'insertable', 'updatable', 'unique'),  
 
 		'@id' 	  => array('generator'),  
 
 	),  
 
 	'method'	=> array(  
 
 		'@log'	=> array('type')  
 
 	)  
 
 );  
 
/** uninstantiable, static methods only */  
 
 private function __construct() {  
 
 }  
 
public static function createAnnotatedProxy($object) {  
 
$r = new ReflectionClass($object);  
 
 	$classAnnotations = self::setProperties(array($r), 'class');  
 
 	$methodAnnotations = self::setProperties($r->getMethods(), 'method');  
 
 	$propertiesAnnotations = self::setProperties($r->getProperties(), 'property');  
 
return new AnnotatedProxy($r->name, $classAnnotations, $methodAnnotations, $propertiesAnnotations);  
 
 }  
 
private static function setProperties($properties, $target) {  
 
 	$arrayToSave = array();  
 
 	foreach($properties as $property) {  
 
 		self::setProperty($property, $target, $arrayToSave);  
 
 	}  
 
 	return $arrayToSave;  
 
 }  
 
private static function setProperty($property, $target, &$arrayToSave) {  
 
 	$propComment = $property->getDocComment();  
 
 	$arrayToSave[$property->name] = array();  
 
 	foreach(self::$validAnnotations[$target] as $annotation => $validParameters) {  
 
$propAnnotation = self::getAnnotationLine($annotation, $propComment);  
 
if($propAnnotation == null || !isset($propAnnotation[1])) { // check if string is not empty  
 
 			if(empty($arrayToSave[$property->name])) {  
 
 				unset($arrayToSave[$property->name]);  
 
 			}  
 
 			continue;  
 
 		}  
 
$arrayToSave[$property->name][$annotation] = array();  
 
$lineProps = self::getAnnotationLineProperties($propAnnotation, $validParameters);  
 
 		if($lineProps && !empty($lineProps)) {  
 
 			$arrayToSave[$property->name][$annotation] = $lineProps;  
 
 		}  
 
}  
 
return $arrayToSave;  
 
 }  
 
private static function getAnnotationLine($name, $searchString) {  
 
 	$matches = array();  
 
 	preg_match("/{$name}(.*)/", $searchString, $matches);  
 
 	return isset($matches[0]) ? $matches[0] : null;  
 
 }  
 
private static function getAnnotationLineProperties($annotationLine, $validParameters) {  
 
$params = array();  
 
 	preg_match("/((.*))/", $annotationLine, $params);  
 
$map = array();  
 
 	$properties = explode(', ', $params[1]); // $params[0] will return the first match string with '()'  
 
 	foreach($properties as $v) {  
 
if(empty($v) || strpos($v, '=') < 0) {  
 
 			continue;  
 
 		}  
 
$tmp = explode('=', $v);  
 
$key = strtolower(trim($tmp[0]));  
 
$value = trim(str_replace('\'', '', $tmp[1]));  
 
 		$value = strtolower($value);  
 
if(!in_array($key, $validParameters) || empty($validParameters)) {  
 
 			continue;  
 
 		}  
 
$map[$key] = $value;  
 
 	}  
 
return $map;  
 
 }  
 
}  
 
class AnnotatedProxy {  
 
private $classAnnotations;  
 
private $methodAnnotations;  
 
private $propertyAnnotations;  
 
private $className;  
 
public function __construct($className, $classAnnotations, $methodAnnotations, $propertyAnnotations) {  
 
 	$this->className 		= $className;  
 
 	$this->classAnnotations 	= $classAnnotations;  
 
 	$this->methodAnnotations	= $methodAnnotations;  
 
 	$this->propertyAnnotations 	= $propertyAnnotations;  
 
 }  
 
public function getClassName() {  
 
 	return $this->className;  
 
 }  
 
public function getClassAnnotations() {  
 
 	return $this->classAnnotations;  
 
 }  
 
public function getMethodAnnotations() {  
 
 	return $this->methodAnnotations;  
 
 }  
 
public function getPropertyAnnotations() {  
 
 	return $this->propertyAnnotations;  
 
 }  
 
public function getPropertyAnnotationValue($column, $annotation, $property = null) {  
 
if(!array_key_exists($column, $this->propertyAnnotations)) {  
 
 		return null;  
 
 	}  
 
if(!array_key_exists($annotation, $this->propertyAnnotations[$column])) {  
 
 		return null;  
 
 	}  
 
if($property != null) {  
 
 		return (array_key_exists($property, $this->propertyAnnotations[$column][$annotation]))  
 
 				? $this->propertyAnnotations[$column][$annotation][$property]  
 
 				: null;  
 
 	}  
 
return $this->propertyAnnotations[$column][$annotation];  
 
 }  
 
public function getMethodAnnotationValue($method, $annotation, $property = null) {  
 
if(!array_key_exists($method, $this->methodAnnotations)) {  
 
 		return null;  
 
 	}  
 
if(!array_key_exists($annotation, $this->methodAnnotations[$method])) {  
 
 		return null;  
 
 	}  
 
if($property != null) {  
 
 		return (array_key_exists($property, $this->methodAnnotations[$method][$annotation]))  
 
 				? $this->methodAnnotations[$method][$annotation][$property]  
 
 				: null;  
 
 	}  
 
return $this->methodAnnotations[$method][$annotation];  
 
 }  
 
public function getClassAnnotationValue($annotation, $property){  
 
 	return $this->classAnnotations[$this->className][$annotation][$property];  
 
 }  
 
}  
 
?>
 

Download Files Here

So, let’s get started.

We need at least two PHP class here, the model and the dynamic finder builder class.
Lets start with the model.

Class Model {

const TABLE = ‘users’;

public function __call($statement, $parameters) {
$sql = QueryBuilder::getQuery(self::TABLE, $statement, $parameters);
}

}

?>

The model is quite straightforward, we have created a constant variable TABLE so that we could passed that variable to our query builder and delegate its magic method __call to our QueryBuilder class.
Note: __call method is automatically called every time an unknown method was invoked on the class.

Let’s take at a look at the QueryBuilder class.
The code is properly documented so just read the code below.

class QueryBuilder { 

const FIND_BY = 'find_by';
const FIND_ALL_BY = 'find_all_by';

// field separator ( must comply with preg compatible regex )
const SEPARATOR = '/(_and_|_or_)/';

/**
* This method will build a query depending on the statement and parameters passed
*
* @param string mock statement
* @param array parameters for the query
* @return array
* array[0] = string the sql that was generated
* array[1] = boolean true if a single row will be returned (find_by), otherwise false
*/
public static function getQuery($table, $statement, $parameters) {

$isSingle = strpos($statement, self::FIND_BY);
$isMultiple = strpos($statement, self::FIND_ALL_BY);

// check if the query passed is valid
if($isSingle === false && $isMultiple === false)
throw new Exception("Method not found: " . $statement . '(' . implode(', ', $parameters) . ')');

// 1 is added for the simple reason of the statements having and extra underscore[_] in the end (
$startLength = 1 + ($isSingle !== false
? strlen(self::FIND_BY)
: strlen(self::FIND_ALL_BY));

$sql = self::constructQuery($table, substr($statement, $startLength), $parameters);

return array($sql, $isSingle !== false ? true : false);
}

private static function constructQuery($table, $statement, $parameters) {

//extract columns from statement by splitting the statement passed with the defined separators
$columns = preg_split(self::SEPARATOR, $statement);
if(count($columns) !== count($parameters))
throw new Exception('Invalid number of parameters passed.');

// store separators in separators array
$separators = array();
preg_match_all(self::SEPARATOR, $statement, $separators);

// make separators valid by replacing all underscores from start and end of separator with nothing
// note that & on $v, this is needed so that reference of $v or actual value of $v will be changed
foreach($separators as $k=>&$v) {
$v = str_replace('_', '', $v);
}

// our sql stamenet would have the 1 = 1 at the end so we need another AND to concatenate the base statement below
// with our column => value array defined ( the $where array )and glue them together with our separators ( $separators )
array_unshift($separators[0], 'AND');

// our base sql statement
$sql = sprintf('SELECT * FROM %s WHERE 1=1 ' , $table);

// loop for our where clause and append the separator, column name and parameter to our statement
$length = count($columns);
for($i = 0; $i < $length; $i++) {
$sql .= sprintf("%s %s = '%s' ", strtoupper($separators[0][$i]), $columns[$i], $parameters[$i] );
}

//trim down the sql generated
return trim($sql);
}
}

?>

The code can be extended to have a dynamic counter (SELECT COUNT(*)), finding with array values (Model.find_all_by_first_name(array('ronald', 'dohdoh'))), or even use camel casing (Model.findAllByUsername('dohdoh')).

You can download the codes below containing 3 files.
- QueryBuilder.php -> the query builder class above
- TestTable.php -> test model to be used in our unit test
- QBTest.php -> our unit test class, SimpleTest framework is required to run the this code

Creating a dynamic finder with PHP Files

PHP Everywhere! December 1, 2007

PHP User Group Philippines, Inc. (PHPUGPH), a non-profit organization established to provide support for LAMP (Linux Apache MySQL PHP) and open-source enthusiasts in the Philippines, will be holding it’s 1st ever PHP Developer’s Conference on December 1, 2007 (1-day event)/9am-6pm.

This is in follow-up with last Aprils successful event, a gathering of professional LAMP developers, web freelancers and companies utilizing OSS (Open-Source Software) technologies for enterprise use. The goal for this upcoming conference is to spread the news of using OSS solutions such as Linux, Apache, MySQL, PHP and some Web 2.0 technologies in wider audiences such as universities and training institutions.

Many noted members of our group are certified and professionally affiliated with leading company in the industry such as Barclays, UN-IOSN, Yahoo! Singapore, Accenture, Mobius Asia and some semi-conductor/electronics like Intel, Atmel, Amis, which has some open source software deployed in production environment.

Last Aprils event was sponsored as listed below that capture’s local IT industry attention and it is our aim to widen the coverage this coming December’s event with your support.

Previous Sponsors:

Zend Technologies
http://www.zend.com

Bandwagon
http://www.ridethebandwagon.com

Digital Media Exchange
http://www.dmii.net

Eskwela
http://www.eskwela.com

HotelDealsAndMore
http://www.hoteldealsandmore.com

Hostking
http://www.hostking.ph

Mobius Games Asia
http://www.mobiusgames.net

NeverFuget
http://www.neverfuget.com

TechHive
http://www.techhive.net

XackMail
http://www.xackmail.com

Ascendant Technologies
http://www.ascendant.com.ph

Last event photos can be found at http://www.phpugph.com/eb
Monthly meeting held last September 29, 2007 can be found at http://picasaweb.google.c...roupMeetingSept29Saturday

Below are some universities that already showed interest and we’re hoping that your humble sponsorship either in package/s or in kind will bring more success in this event.
UST
http://www.ust.edu.ph

UP
http://www.upm.edu.ph
http://www.up.edu.ph

Ateneo
http://www.admu.edu.ph

Mapua
http://www.mapua.edu.ph

TUP
http://www.tup.edu.ph
The group has already lined up some of our local IT industry leaders as speakers covering various topics ranging from MySQL Enterprise Database, advance web-scripting using PHP, Web 2.0 and some IT technology business matters.

Also, some new sponsors/groups shows support as listed below and we’re looking forward that your name/company will be listed as well.

Our growing new sponsors:

EmuraSoft
http://www.emeditor.com
Utraedit
http://www.idmcomp.com

TheDesignPeople
http://www.thedesignpeople.com

Offshoring
http://www.offshoring.com

Techhive
http://www.techhive.net

Tentative Topics/Sessions this year:

1. CodeIgniter with Aptana (PHP) by Roger Filomeno (Mobile Specialist, TechBiz Asia Group Pte Ltd)
2. TipidPC: How it was made! (PHP) by Jesus Domingo (Frontend Engineer, Yahoo! Singapore)***
3. Database 101 using MySQL (Database) by Cherrie Anne Domingo (Multinational Investment Bank Corporation)
4. Sulit:Ads made Easy (Business) by RJ David (CEO, Sulit.com.ph)
5. Defensive Design (Web Design) by AJ Batac (Director of Operations, Webcore Canada)***
6. CSS and the Web (Web Design) by Angela Sabas (Frontend Engineer, Yahoo! Singapore)***
7. Test Driven Development in PHP:Recap (PHP) by Andre John Cruz (Application Developer, Barclays Singapore)***
8. IT Trends (Business) by JR Yap (CIO, MobileXchange)
9. Zend Core and Oracle (Database) by Clodelio Delfino (System Analyst, AMIS Asia)
10. PHP in Schools: A Visit (PHP) by Anne Michelle Santos (Web Developer/Professor, University of Santo Tomas)
11. Exploring OpenSUSE 10.3 (Linux) by Reuben Ravago (CEO, OLM Technologies)
12. Medical Systems with PHP by Sergio Arroyo (President, Ascendant Technologies)
13. Stealth Startup Product Launch by AJ Batac (Director of Operations, Webcore Canada)***

NEW SPEAKERS/SESSIONS WILL BE INVITED…

*** Pre-recorded sessions (possible online Q & A during the event since some of the members are in other countries).

Below are some data of the group for your additional references:
Name: PHP User Group Philippines Inc.
Founded: January 2001
Founder: AJ Batac (CEO)
President: Clodelio Delfino, ZCE (System Analyst)
Vice-President: Cherrie Ann Domingo (Software Developer)
Treasurer: Anne Michelle Santos (Web Developer/Professor)
Secretary: Garrizaldy Santos (Software Engineer)
Incorporators:
Jonathan Richie Yap (CIO)
Ronald John David (CEO)
Mark Edward Tan (Web Developer)
Bryan Blas (Web Developer)
Erwin Atuli (Software Engineer)
Redelyn Villamin (Software Engineer)
Current Forum Members: 1,130+
Generates a monthly pageviews of almost half million

In return for your support…
1) Inclusion of Logo and Link to PHPUGPH.com home (from December 2007 – to December 2008)
2) Monthly email blast to all PHPUGPH members for 1 year (from Dec 2007 – to Dec 2008)
3) Company logo to be included in the member’s tshirt

Source: http://www.phpugph.com

According to the definition of BDD from wikipedia:

Behavior Driven Development (or BDD) is a software development technique that questions the behavior of an application before and during the development process. Created in response to the failings the founders perceived in Test Driven Development, Behavior Driven Development addresses requirements and specification in a way that is more textual than its predecessor. By asking questions such as "What should this application do?" or "What should this part do?" developers can identify gaps in their understanding of the problem domain and talk to their peers or domain experts to find the answers. By focusing on the behavior of applications, developers try to create a common language that's shared by all stakeholders: management, users, developers, project management and domain experts.

From what I understand, BDD is different from TDD on how they approach in 'testing' a unit/entity. TDD is more focused on the application logic, while BDD is focused on what the behavior of the application on a given situation.

I'll try to put some codes differentiating TDD and BDD approach on my next post.

Till next time. =)