Recently I have been asked to introduce and assist with starting Zend Framework projects; over time I have learned through trial, error and banging my head against a wall a few tricks, shortcuts and nuances. In this series I will take the life cycle of a Zend Framework project from beginning to never-end and cover each portion as completely as I can and provide a place for discussion to improve my process or detail it further. It should be clear the intent of this article is not to discuss development methodology or any process outside of the scope of using Zend Framework itself.

A project is born.

Beginning with a name for the project established (for the purpose of this write-up I have decided on ZendDB) we should begin by creating the project reference within Eclipse, Zend Studio or your preferred editors method. Before we begin any code creation or development we need to insure we have the required tools on our system to begin.

Following this we must establish where we will edit, build and work on the project and initialize the project contents using the zf tool, create additional directories for build and validation. The build related files and directories tie all components into a collective suite of tools, utilizing ant or phing we will be able to execute all reports as one single command. This practice also lays the foundation for continuous integration, which this project will evolve into as time goes on. To enable each of these tools we will use we must create their associated configurations, begin by editing build.phpcs.xml I have intentionally kept this example simple and to the point, I strongly recommend you visit the PHP_CodeSniffer project for more details on its capabilities. Once complete the PHPUnit configuration is setup with the various types of reports it should generate, the test suites it will cover. For more details on PHPUnits report capabilities and xml configuration options visit the PHPUnit Documentation. Now this is established we may bring it all together with the ant build.xml file. This file will allow us to create/remove required build artifacts, report directories and execute phpunit, phpcs and phpdoc all in a single stack. For a more detailed overview of an ant build file please see Apache Ant; it should also be noted that Phing is a php alternative to ant and should be interoperable with ant. To utilize the build script you need only execute ant within the top-level directory of the project, the example file provided will create phpdocs, code sniff the project and execute all unit tests. Reports will be stored within build/* for review.

In the next edition to this I will cover database configuration and model creation.

I recently made the embarrassing mistake of creating a push request to a well respected PHP author’s project and to my horror I saw he had to ‘detabify’ my push. I had recently reset my Zend Studio workspace and neglected to reconfigure the default format standard from PHP => Zend.

Once I sorted out my studio client, I began to look into ways to test this all before it’s even committed, to insure I have not overlooked a detail. To help with syntax, formatting and style, I have employed PHP_CodeSniffer, a PEAR package. Its use is simple and straightforward with informational documentation; Rulesets or Sniffs are varying and customizable in the form of a ruleset xml file. Available Sniff Collections are grouped as follows:

• Generic
• Squiz
• PHP
• Zend
• PEAR

Each brings its own standards ruleset for customization. I have chosen to implement the Zend Sniff in  the form of a file named phpcs.xml, I exclude certain file types .js, .css all test files, data files and, for good measure, .svn directories.

I place this file in a directory inside /tests/build/ where you place your file strictly depends ons on your personal preferences. To install PHP_CodeSniffer execute the following commands:

There are several choices of reports, for the purpose of command line reporting I choose one or all:

• source [provides a description of what rules the violations are related]
• full [detail of all violations in the code base, line of violation and rule
• summary [ a high level assessment of all rule violations]

Examples of the report type’s outlines and the associated commands to produce each with the afore mentioned rules file.

[gist id=”965105”/]

While it’s possible, the report will be sizable depending on the projects size; however this is an opportune time to begin cleaning up your existing code base; but more importantly, it gives you the tools required to insure your code is clean, consistant and within community expectations.

If you, your project or employer have your own specification of code standards, I would encourage you to create your own rule set in combinations. Should the existing sniffs not be sufficient, it’s advised to create your own sniffs to accommodate your needs.

The PHP_CodeSniffer project provides an annotated xml ruleset file to serve as a guideline and tutor; as well as the documentation associated with its use.

I am happy to announce the release of Skulk 0.1.2 for use with Prowl. This release introduces a command line zf provider for your messaging pleasure. More on its use and source code may be found at github@Skulk.

For PEAR installation and channel information, please see: http://pear.zircote.com/ for more details.

Setting up and using the Provider

Create the user config file for Zend_Tool

zf create config 

$ zf enable config.provider Skulk_Tool_ProwlProvider Provider/Manifest 'Skulk_Tool_ProwlProvider' was enabled for usage with Zend Tool. 

You are ready to set up the configuration and send a message.

$ zf ? prowl Zend Framework Command Line Console Tool v1.11.5 Actions supported by provider "Prowl" Prowl zf addkey prowl keyname apikey zf delkey prowl keyname zf send-message prowl message priority[=normal] description url 

Add your API key(s) with the following command:

zf addkey prowl   

Now send a message:

$ zf send-message prowl 'test message' 988 messages left until May 8, 2011 5:58:48 PM

 

I decided I wanted to have a CLI interface to my Skulk library and provide a method to send messages from scripts without requiring any additional coding overhead. To do this I employed the Zend_Tool CLI [zf] and began by deciding on the functionality it would possess. After some thought, I settled ultimately that sending messages would be sufficient for the time being; however, it would require some supporting methods for api key management, naming, adding and deleting.

class Skulk_Tool_ProwlProvider extends Zend_Tool_Project_Provider_Abstract
{
}

I started the process by creating the provider class Skulk_Tool_ProwlProvider; the “Provider” portion of the name is important as the IncludePathLoader will not otherwise recognize the class as such and extending the Zend_Tool_Project_Provider_Abstract.

require_once ('Zend/Tool/Project/Provider/Abstract.php');
class Skulk_Tool_ProwlProvider extends Zend_Tool_Project_Provider_Abstract{
    public function addkey($keyname, $apikey){
    }
    public function delkey($keyname){
    }
    public function sendMessage($message, $priority = 'normal', $description = null, $url = null){
    }
}

Having established the class we may now move on to the public methods. We have established our required methods as follows:

• Adding an api key
• Removing an apikey
• Sending a message

require_once ('Zend/Tool/Project/Provider/Abstract.php');

class Skulk_Tool_ProwlProvider extends Zend_Tool_Project_Provider_Abstract{

    public function addkey($keyname, $apikey){
        if(!$this->_registry->getConfig()->skulk){
            $skulk = array(
                'defaults' => array( 'priority' => 'normal'),
                'keys' => array($keyname => $apikey)
            );
            $this->_registry->getConfig ()->skulk = $skulk;
            $this->_registry->getConfig ()->save();
        } else {
            if($this->_registry->getConfig()->skulk->keys){
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            } else {
                $this->_registry->getConfig()->skulk->keys = array();
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            }
            $this->_registry->getConfig ()->save();
        }
    }
}

To add the API key we will need to be able to write to the configuration file in the user’s home directory or where otherwise specified at runtime. This will require interaction with the internal registry property; testing if the relevant properties exist in the configuration, modify it in the event it does or initialize it if not. We perform the various configuration operations through the _registry property as demonstrated in the example below adding the required options followed by the save method to write the configuration file.

$this->_registry->getResponse()
    ->appendContent('api key saved!', array('color' => 'green'));

We also may want to provide feedback to the user regarding the status of the operation. This also is provided through the access of the _registry property with the response object, which may be formatted for color, tab depth, centering and blocking. For the purpose of this demonstration, we will use the color decorator to make the output green, leaving our example well established and ready for the next steps.

    public function addkey($keyname, $apikey){
        $skulk = $this->_registry->getConfig()->skulk;
        if(!$skulk){
            $this->_registry->getResponse()
                ->appendContent('initializing default config for Skulk...', array('color' => 'cyan'))
                ->appendContent('default priority [normal]...', array('color' => 'cyan'));
            $skulk = array(
                'defaults' => array( 'priority' => 'normal'),
                'keys' => array($keyname => $apikey)
            );
            $this->_registry->getConfig ()->skulk = $skulk;
            $this->_registry->getConfig ()->save();
        } else {
            if($this->_registry->getConfig()->skulk->keys){
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            } else {
                $this->_registry->getConfig()->skulk->keys = array();
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            }
            $this->_registry->getConfig ()->save();
        }
        $this->_registry->getResponse()
            ->appendContent('api key saved!', array('color' => 'green'));
    }

Now to add the delkey method using the same tools as before, with the addition of an unset on the existing property followed by the save method, as in the addkey logic writing the file with the updated values.

    public function delkey($keyname){
        $config = $this->_registry->getConfig();
        if($config->skulk->keys->$keyname){
            unset($config->skulk->keys->$keyname);
            $this->_registry->getConfig ()->save();
            $this->_registry->getResponse()
                ->appendContent($keyname . ' apikey removed...', array('color' => 'red'));
        } else {
            $this->_registry->getResponse()
                ->appendContent($keyname . ' apikey does not exist...', array('color' => 'red'));
        }
    }

Finally this brings us to the sendMessage call, which will require ancillary methods to create the outgoing message container, the API object that sends the message as well as a priorities method to convert users input into a value expected by the API actor. The details of which are less about Providers and more about the code being employed, leaving us with a final product ready to send messages to an iOS device near you.

require_once ('Zend/Tool/Project/Provider/Abstract.php');

/**
 * @author zircote
 *
 * zf enable config.provider Skulk_Tool_ProwlProvider
 * zf create config
 * zf ? prowl
 */
class Skulk_Tool_ProwlProvider extends Zend_Tool_Project_Provider_Abstract
    implements Zend_Tool_Framework_Provider_Pretendable{
    /**
     *
     * @var Skulk_Client_Message
     */
    protected $message;
    /**
     *
     * @var Skulk_Client
     */
    protected $api;
    /**
     *
     * @example zf addkey prowl iPhone sdf234g9i24t09j23r...
     * @param string $keyname
     * @param string $apikey
     */
    public function addkey($keyname, $apikey){
        $skulk = $this->_registry->getConfig()->skulk;
        if(!$skulk){
            $this->_registry->getResponse()
                ->appendContent('initializing default config for Skulk...', array('color' => 'cyan'))
                ->appendContent('default priority [normal]...', array('color' => 'cyan'));
            $skulk = array(
                'defaults' => array( 'priority' => 'normal'),
                'keys' => array($keyname => $apikey)
            );
            $this->_registry->getConfig ()->skulk = $skulk;
            $this->_registry->getConfig ()->save();
        } else {
            if($this->_registry->getConfig()->skulk->keys){
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            } else {
                $this->_registry->getConfig()->skulk->keys = array();
                $this->_registry->getConfig()->skulk->keys->$keyname = $apikey;
            }
            $this->_registry->getConfig ()->save();
        }
        $this->_registry->getResponse()
            ->appendContent('api key saved!', array('color' => 'green'));
    }

    /**
     *
     * zf delkey prowl iPhone
     * @param string $keyname
     */
    public function delkey($keyname){
        $config = $this->_registry->getConfig();
        if($config->skulk->keys->$keyname){
            unset($config->skulk->keys->$keyname);
            $this->_registry->getConfig ()->save();
            $this->_registry->getResponse()
                ->appendContent($keyname . ' apikey removed...', array('color' => 'red'));
        } else {
            $this->_registry->getResponse()
                ->appendContent($keyname . ' apikey does not exist...', array('color' => 'red'));
        }
    }

    /**
     *
     * zf send-message prowl 'test message' normal 'long description here' 'http://zircote.com'
     * @param string $message
     * @param string $priority
     * @param string $url
     * @param string $description
     */
    public function sendMessage($message, $priority = 'normal', $description = null, $url = null){
        $this->_init();
        $this->message->setApikey($this->apikeys->toArray())
            ->setEvent($message)
            ->setPriority($this->getPriority($priority))
            ->setDescription($description ? $description : $message);
        if(null !== $url){
            $this->message->setUrl($url);
        }
        $response = $this->api->add($this->message);
        $result = $response->getResult();
        if(key_exists('success', $result)){
            $this->_registry->getResponse()
                ->appendContent($response->getRemaining() . ' messages left until '
                 . $response->getResetDate(), array('color' => 'cyan'));
        } else {
            $this->_registry->getResponse()
                ->appendContent($result['error']['detail'], array('color' => 'red'));
        }

    }

    /**
     *
     * returns integer value for priorityfrom a simple string
     * @param string $priority
     * @return integer
     */
    protected function getPriority($priority){
        $priorities = array(
            'verylow' => Skulk_Client_Message::PRIORITY_VERYLOW,
            'normal' => Skulk_Client_Message::PRIORITY_NORMAL,
            'moderate' => Skulk_Client_Message::PRIORITY_MODERATE,
            'high' => Skulk_Client_Message::PRIORITY_HIGH,
            'emergency' => Skulk_Client_Message::PRIORITY_EMERGENCY
        );
        return  $priorities[strtolower($priority)];
    }

    protected function _init(){
        $this->apikeys = $this->_registry->getConfig()->skulk->keys;
        require_once 'Skulk/Client.php';
        require_once 'Skulk/Client/Message.php';
        $this->message = new Skulk_Client_Message();
        $this->api = new Skulk_Client;
    }

}

When completed it affords us the functionality list:

$ zf ? prowl
Zend Framework Command Line Console Tool v1.11.5
Actions supported by provider "Prowl"
  Prowl
    zf addkey prowl keyname apikey
    zf delkey prowl keyname
    zf send-message prowl message priority[=normal] description url