A model layer for the i5 Toolkit on PHP

PHP has kind of taken the i5 world by storm.  Many RPG developers want to move their applications to the web, but while there are options for doing so, RPG is not all that well suited for writing web applications unless you invest heavily in a CGI framework like DEV2.  The other option has been Java, which represents a completely different way of coding that many RPG developers are not overly comfortable with.  Alongside that, there is the standard issue of Java taking some time to learn properly.  So along comes PHP and it gives the RPG developers a chance to ease into programming for the web.  They can still use procedural programming when they start, but they can also move to more structured applications as they become more familiar with the language.

However, there is often a problem in that there is a significant amount of functionality that still exists in RPG that you don't necessarily want to duplicate in PHP.  For that reason the PHP Toolkit was added as part of Zend Core, and now Zend Server for the i.  You can see an example of that on George Papayiannis' blog.  What it basically amounts to is calling several PHP tookit functions whenever you want to access that functionality.  The example from George's blog is like this:

$conn = i5_connect("localhost", "gpapayia", "secret");

echo "Product Id: ".$PROD_ID."l
echo "Store Location: ".$STORE_LOC.";
echo "Price: ".$AMOUNT.";

Before I get into some of the problems with this I would like to state that this is not a critique of George's code.  Given the toolkit as it stands, this is, in actuality, a good example.

However, there are a couple of problems with this.

1. This can lead to a lot of duplicated code
2. This injects individual variables into the global scope. (due to the toolkit)
3. It is difficult to structure a large application when you have to repeat the same connectivity code over and over again.

So what I've done is written a very simple library that can be used to abstract out that functionality.  I have placed it on Github so you can install it, examine it, and modify it to add functionality as needed.  The library I wrote only supports program calls at this time and there is a lot of additional functionality in the i5 Toolkit that could be abstracted.

The way it works is that you set up a connection manager in one part of your application, either an include file or preferably some kind of bootstrap.  Then you define your individual model classes (classes that represent programs in RPG) to match that functionality.  Then you call it.  I won't spend any time at this point talking about the underlying architecture.  If you are interested you can read the source code.  Or I may do another blog post on it.

The first thing you need to do is define your connection manager.  This allows you to set the adapter type and any connection information in one place.  This would be done in a bootstrap or include file.

$mgr = new Itk_Connection_Manager(
    array(
        'adapter'        => 'Live',
        'username'        => '',
        'password'        => '',
        'host'            => '127.0.0.1'            
    )
);
Itk_PgmAbstract::setDefaultAdapter($mgr->getAdapter());

What this does is set the default adapter for any model classes that are called.  You can actually create a model object off of any arbitrary adapter (if you have multiple adapters running at the same time), but this generally will not be necessary.  In this library I have created two different adapters.  One is Live, which will call the i5 Toolkit.  The other is Mock, which allows you to define the return values for individual program calls to help facilitate unit testing.  Look in the /tests directory for some examples of this.

The next thing to do is to define your model class.

class Model_CommonPgm extends Itk_PgmAbstract
{
    protected $_programName = 'ZENDSVR/COMMONPGM';
    protected $_description = array(
        'CODE'    => array(
            self::DESC_IO        => I5_INOUT,
            self::DESC_TYPE      => I5_TYPE_CHAR,
            self::DESC_LENGTH    => "10"
        ),
        'DESC'    => array(
            self::DESC_IO        => I5_INOUT,
            self::DESC_TYPE      => I5_TYPE_CHAR,
            self::DESC_LENGTH    => "10"
        )
    );
    public function setCode($code)
    {
        $this->CODE = $code;
    }
}

What you are doing here is defining what the input and output parameters are, just like you would in a regular i5 toolkit call.  However, there is a big difference in the actual call.  The class definitions are usually done in separate files and included either manually or (preferably) using an autoloader, such as Zend_Loader_Autoloader.  So actually calling the RPG function makes your inline code extremely simple.  Additionally you can optionally define setters like I did here to document and structure the available functionality even more.

One of the reasons that I like this is that it is both very clean and very repeatable.  When you want to actually execute the RPG logic from within your application you run code like this.

$model = new Model_CommonPgm();
$model->setCode($_POST['code']);
$result = $model->execute();
echo "The return values are: ", "Code: ", $result->CODE, " Description: ", $result->DESC," ";

The code example I took this from was at least 2 dozen lines long and I was able to bring it down to about 3 lines of code.  What this is doing is creating a new class and attaching outside data to the IN or INOUT properties by referencing the POST variable.  Then I execute it, taking the result and putting it into a result object where I can reference the out-bound results of the call.

Please note that I am not an RPG programmer and as such it would probably be a good idea for people more familiar with RPG than I to use this and find problems but I think that this can go a long way to making PHP applications that rely on RPG and the i5 Toolkit to be much more structured and much easier to maintain.

Again, here's the link to Github.