You don't have to learn MVC to start using Zend Framework.

Recently, at the COMMON conference, I presented several PHP sessions. Two sessions were aimed toward attendees that are relative newcomers to PHP, and they were very well-received. To my thinking, it's time to raise the bar. While many of you are still just learning PHP and are more in the "testing it out" stage than doing actual development, there are a lot of developers on the IBM i who are writing real-world PHP applications. So this article is the first of what will be several focusing on transitioning from using plain PHP and the procedural model to harnessing the power of Zend Framework (ZF) and the Model-View-Controller (MVC) design pattern.

So now that I have frightened you, let me give you some good news. You don't have to learn the MVC design pattern to start using ZF. In fact, we are going to walk through a sample PHP script that uses some of the ZF tools and is still just a regular procedural script. But before we do that, let's cover a few of the basics.

Verify Your Zend Framework Version

In order to use ZF, you need to have Zend Core or Zend Server 5 for IBM i installed on your machine. Look for licensed program 1ZCORE5 for Zend Core or 2ZSVRPI for Zend Server. If you don't have one or the other of these installed, you'll need to install one. Either one can be downloaded from the Zend Web site. Both of the install packages include clear and concise directions for installing the software (usually just a *SAVF and RSTLICPGM command).

Once you verify that you have one of the PHP environments installed, you still need to verify that you have a recent version of Zend Framework (you probably don't). The most recent version as of this writing is 1.10.4. All the example scripts were written and tested using version 1.10.3, so any version 1.10.3 or later is fine. Many of you probably haven't updated ZF since you installed Zend Core or Zend Server. The versions installed with your PHP server automatically are as follows:

• Zend Core: ZF version 1.6.0
• Zend Server 5 for IBM i: ZF version 1.9.7

You can find out which version you're running by looking at the Zend Server GUI administration dashboard. The dashboard can be found at http://youribminame:10088/ZendServer. Once you open the dashboard, the ZF version is on the right side near the top (see below). This actually serves the dual purpose of both checking your version and making sure that your Zend Server subsystem is active.

Figure 1: Check the dashboard to find the ZF version. (Click image to enlarge.)

If it's necessary, installing a new version of Zend Framework is easy. Download latest version from the Zend Web site. Then unzip the .zip file into the appropriate directory as shown below:

• Zend Server users: /usr/local/zendsvr/share
• Zend Core users: /usr/local/zend

Now you have a new subdirectory called ZendFramework-x.xx.x, where x.xx.x will be the version of the new installation. The easiest way to complete the installation and start using the new version is to rename the existing ZendFramework directory to ZendFramework_old. Then you can rename your newly installed subdirectory ZendFramework. You can now start using the new version without making any configuration changes.

Now that you're up to date with the ZF release, you can get down to business. Zend Framework is one of several "frameworks" available for PHP (CodeIgniter, Symfony, and CakePHP are a few others that are popular). Generally speaking, frameworks are packages of component-based tools/functions that are used in most development projects. For instance, Zend Framework has classes available that help you easily create forms (Zend_Form), authenticate users (Zend_Auth), easily access DB tables (Zend_Db), and more. Frameworks are also sometimes referred to as "scaffolding," which perhaps gives a more visual description of how they are used. Typically, these frameworks are tied to a specific design pattern; in the case of ZF, this is the Model-View-Controller (MVC) design pattern. For those of you unfamiliar with MVC, it can best be described as a standard design that all your applications are built on.

Your First Zend Framework Script

Using Zend Framework together with the MVC design pattern is the topic of a later article. For now, it's enough that you know what MVC is. We're actually going to use an alternative method to determine the installed ZF version for our first example script. The script uses one of the available ZF functions, and it gives me a decent alternative to the ubiquitous "Hello World" example.

<?php

require_once("Zend/Version.php");

echo "Zend Framework Version: ".Zend_Version::VERSION;

?>

The code above searches the include path for a directory/file called Zend/Version.php. This file contains a class called Zend_Version that in turn has a constant called VERSION. Then we use the echo construct to display the VERSION constant to the user. This is probably all review for most of you, so we'll move on to some other ZF functions.

Got Authentication?

One of the often-used and much-needed functions provided by ZF is the Zend_Auth classes. The Zend_Auth classes provide a tool that simplifies user authentication. In our example, we're going to use the Zend_Auth_Adapter_DbTable and Zend_Db classes. This is because we are going to use a DB2 table as our authentication database. What this means is that the user names and passwords we're expecting to receive from the Web user are stored on our IBM i in a DB2 table. It could be any table you specify. I have created a simple file called USERMSTR and included several fields in addition to the required "identity" column (aka user_profile) and "credential" column (aka password). The reason I included these additional columns will become clear later.

Here's the SQL to create the USERMSTR table:

create table jeffo/usermstr                     

 ( usermstr_id    integer   not null            

       as identity(no cache) primary key,       

   user_profile   varchar(10) not null,         

   password       varchar(15) not null,         

   realname       varchar(50) not null,         

   email_address  varchar(100) not null    )    

The code below is just for demonstration purposes. In a real-world example, you would want get the username and password from an HTML form (we'll get to that later too). For now, we just want to get a feel for how to use the ZF classes.

<?php

//-----------------------------------------------------------------------------

// Set to display errors - TESTING ONLY!!

//-----------------------------------------------------------------------------

ini_set('display_errors', '1');

//-----------------------------------------------------------------------------

// Use Autoloader to include the Zend Framework Classes we are going to use.

//-----------------------------------------------------------------------------

require_once 'Zend/Loader/Autoloader.php';

Zend_Loader_Autoloader::getInstance()->setFallbackAutoloader(true);

//-----------------------------------------------------------------------------

// Set up the DB options

//-----------------------------------------------------------------------------

$library = 'jeffo';

// single database library option

$driverOptions = array( "i5_lib" => $library);

// Library list option

/* $driverOptions = array( "i5_naming" => DB2_I5_NAMING_ON,

         "i5_libl" => "TBSCOMMON JMOQA2 JMOQA1 JMOPROD QGPL");  */

$config = array( "host" => "localhost",

                 "username" => "quser",

                 "password" => "quser",

                 "dbname" => "LEGATO3",

                 "driver_options" => $driverOptions);

if (!$db = Zend_Db::factory('DB2', $config)) {

       echo "didn't create the DB adapter<br>";

       die();

}

//----------------------------------------------------------------------------

// Setup the authentication database adapter

//----------------------------------------------------------------------------

if (!$authAdapter = new Zend_Auth_Adapter_DbTable($db)) {

       echo "didn't create the Zend Auth Adapter table object<br>";

       die();

}

// set the table and columns to use for authentication

$authAdapter

    ->setTableName('USERMSTR')

    ->setIdentityColumn('USER_PROFILE')

    ->setCredentialColumn('PASSWORD')

;

// set the values (usually from a login form) to be authenticated

$authAdapter

    ->setIdentity('username')

    ->setCredential('password')

;

// authenticate using the specified credentials (specified above)

$authResult = $authAdapter->authenticate();

// display authentication results

switch ($authResult->getCode()) {

       case Zend_Auth_Result::SUCCESS:

              echo "User successfully logged in";

              // print the returned contents of the result row in the

             // authentication table

              print_r($authAdapter->getResultRowObject());

              break;

       case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:

        echo "User Identity not found. Login unsuccessful";

        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:

        echo "User/Password combination not valid. Login unsuccessful";

        break;            

       default:

              echo "Login unsuccessful. Unidentified error";

}

?>

The first thing we do in the code is set the display_errors flag to 1. This will allow us to see any errors that occur during the execution of our script, which can be helpful during testing, but you must remember to remove it before moving into production because the information displayed can potentially be sensitive information (names of databases, variable names, etc.). Next, we use the require_once function, which includes other source code similar to a /copy in RPG. In this case, we're including the ZF Autoloader class (/Zend/Loader/Autoloader.php). The Autoloader class provides some advanced functionality that we don't necessarily want to address here. In the case of our sample script, we're using the Autoloader to avoid the trouble of coding a require_once for each ZF class we use. By using the following code, we can use any ZF classes in our script, and the PHP interpreter will "autoload" the class for us.

require_once 'Zend/Loader/Autoloader.php';

Zend_Loader_Autoloader::getInstance()->setFallbackAutoloader(true);

It's a convenience tool. The Autoloader class is really beyond the scope of this article, but you can find out more about it in the Zend Framework Manual.

Once we have the Autoloader code in place, we move on to configuring and creating the ZF database adapter. We have ability here to code a single database library (as I have done in the example).

$library = 'jeffo';

// single database library option

$driverOptions = array( "i5_lib" => $library);

Or we can use a library list by changing the code above to read as shown below:

// Library list option

$driverOptions = array( "i5_naming" => DB2_I5_NAMING_ON,

         "i5_libl" => "TBSCOMMON JMOQA2 JMOQA1 JMOPROD JEFFO QGPL"); 

Then we use an array ($config) to set the database connection parameters. These parameters should be familiar as they are nearly the same as the parameters we have used previously with the db2_connect function. The difference is that for the ZF database class, we're placing the key/value pairs in an array instead of passing them as individual parameters as we do on the db2_connect function. Once we populate the configuration array, we use the Zend_Db class to create a database object.

if (!$db = Zend_Db::factory('DB2', $config)) {

       echo "didn't create the DB adapter<br>";

       die();

}

There are several ways we could create the database adapter object ($db). We use the static method Zend_Db::factory to create our adapter. Without getting too esoteric, a factory method is a generic method that creates instances of similar objects. For example, we can use the Zend_Db::factory method to create database adapters objects for DB2, MySQL, and SQLite.

Once the database adapter object is created, we need to set up Zend_Auth so that it knows to use that database adapter for authentication requests. This is done by creating a Zend_Auth_Adapter_DbTable object and passing our existing database adapter object as a parameter to the __construct method.

if (!$authAdapter = new Zend_Auth_Adapter_DbTable($db)) {

       echo "didn't create the Zend Auth Adapter table object<br>";

       die();

}

Now that we've created the Zend_Auth_Adapter_DbTable object ($authAdapter), we need to configure it to our specific database.

// set the table and columns to use for authentication

$authAdapter

    ->setTableName('USERMSTR')

    ->setIdentityColumn('USER_PROFILE')

    ->setCredentialColumn('PASSWORD')

;

First, we configure Zend_Auth to use the correct table and columns for authentication. In this case, we'll be using database table USERMSTR and using the USER_PROFILE and PASSWORD columns to authenticate on. As I said before, you would normally expect to receive the input for authentication from a login Web page. For now, we're just hardcoding the USER_PROFILE and PASSWORD values we're authenticating.

// set the values (usually from a login form) to be authenticated

$authAdapter

    ->setIdentity('username')

    ->setCredential('password')

;

Now all that's left is to actually do the authentication. This is accomplished using the aptly named "authenticate" method.

// authenticate using the specified credentials (specified above)

$authResult = $authAdapter->authenticate();

The authenticate method returns an object with different properties and values, depending on the result of the authentication. Some of the results can be seen in our code. For instance, we're using the getCode method to retrieve the authentication result code and then comparing that to the ZF Zend_Auth_Result constants to determine the actual results.

// display authentication results

switch ($authResult->getCode()) {

       case Zend_Auth_Result::SUCCESS:

              echo "User successfully logged in";

              // print the returned contents of the result row in the

             // authentication table

              print_r($authAdapter->getResultRowObject());

              break;

       case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:

        echo "User Identity not found. Login unsuccessful";

        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:

        echo "User/Password combination not valid. Login unsuccessful";

        break;            

       default:

              echo "Login unsuccessful. Unidentified error";

}

Remember I said that there was a reason that I included some columns in the USERMSTR table other than just the USER_PROFILE and PASSWORD columns required for authentication? Well, now we get to see why. One of the other features of Zend_Auth is that if the authentication is successful, you can retrieve the contents of the retrieved authentication row (the row from the USERMSTR table). This is done using the getResultRowObject as shown above. Since you will probably want to store other authorization-type information in the USERMSTR table, the getResultRowObject can be really handy.

You can see how easy it would be to modify this code to accept input from a form. Also, to make things more secure, you could store your passwords using the MD5 encryption available in PHP. In the next article, we'll cover how to use Zend_Form to create a login page and tie into the sample code we created here.

Editor's note: Zend Server 5.0.2 is now available for IBM i.