Zend_Validate includes two classes to work with database columns: Zend_Validate_Db_NoRecordExists and  Zend_Validate_Db_RecordExists. As their names suggest these check that a value either does or doesn’t exist in a specified column in a database table. The classes work really well in a form when specified as a validator for a value but things can get a little trickier if you need to check two columns in a table. The problem I had was in creating a simple FAQ page for a site. The site owner gets to add FAQs to the site and each FAQ is contained in a category. As a little sanity check I wanted to make sure that the combination of category and question was unique. The database also has a multiple column unique key on these to enforce the integrity. My first attempt looked something like this in a class that extends Zend_Form:

public function init() {
//Category options are populated elsewhere.
$categories = new Zend_Form_Element_Select('category');
$categories->setAllowEmpty(FALSE)
	   ->setAttrib('required', 'required')
	   ->setLabel('FAQ Category:')
	   ->addErrorMessage('Please choose a valid category from the list.')
	   ->addMultiOption('', '--Please Choose--');
$question = new Zend_Form_Element_Text('question');
$question->setRequired(TRUE)
	 ->setLabel('Question:')
	 ->setAttrib('required', 'required')
	 ->setAttrib('max', '100')
	 ->addValidator('StringLength', FALSE, array(0,100))
	 ->addErrorMessage('Enter a question of up to 100 characters in length.');
$validate = new Zend_Validate_Db_NoRecordExists(array('table' => 'faqs', 'field' => 'title'));
$validate->getSelect()->where('FaqCategoryId = ?', $this->getValue('category'), Zend_Db::PARAM_INT);
$question->addValidator($validate);
}

I thought that this would add the extra where clause to the select statement for the validation. This failed miserably though. The problem is that the value referenced in ‘$this->getValue(‘category’)’  doesn’t exist when the init() method is called. Values are only added to the form when the isValid() method is called. The solution was to extend the isValid() method and to perform the extra check there.

public function isValid($data) {
	$result = parent::isValid($data);
	if ($result) {
		$validate = new Zend_Validate_Db_NoRecordExists(array('table' => 'faqs', 'field' => 'question'));
		//Add a where clause to check the FaqCategoryId
	        $validate->getSelect()->where('FaqCategoryId = ?', $this->getValue('category'), Zend_Db::PARAM_INT);
	       	$result = $validate->isValid($this->getValue('question'));
	       	if (! $result)
	       		$this->getElement('question')->setErrors(array('The selected category already has an FAQ with that question. Please edit the question.'));
		}
		return $result;
	}

By extending the isValid() method I can call the parent method to do the majority of the work. If the form looks valid I then perform the extra check to make sure the combination of question and category is unique. If it isn’t an error message is set and the validation fails. I’ve also used this in another part of the site where the client is adding news articles to the site. In that instance the combination of published date and title needs to be unique as these are used in the url to uniquely reference the article. The same method in form validation checks that when the form is submitted. Using this method I’ve been able to clean up my controller and move all validation checks into the form, where they should be. I’d love to hear in the comments how other people approach this problem though.

The first problem came because the online version of the Framework documentation hasn’t been updated with the latest release. As Zend_Service_Twitter has been largely refactored to use OAuth this is a major issue (the constructor even accepts different arguments from what the documentation says). At no point is it clear what arguments need to be passed to the constructor or in what order. Anyway, after hours of frustration I finally came by some help on StackOverflow. Here’s some very simple test code to post a Tweet using Zend_Service_Twitter and OAuth (assuming you’ve already registered an application with Twitter and got the correct user authorisation keys):

$access = new Zend_Oauth_Token_Access();
 $access->setToken('USER AUTHORISATION TOKEN')->setTokenSecret('USER AUTHORISATION TOKEN SECRET');
 $params = array(
 'accessToken' => $access,
 'consumerKey' => 'YOUR APPLICATIONS CONSUMER KEY',
 'consumerSecret' => 'YOUR APPLICATIONS CONSUMER SECRET'
 );
 $twitter = new Zend_Service_Twitter($params);
 $twitter->statusUpdate('Testing posting tweets using OAuth!');

The statusUpdate method returns an instance of Zend_Rest_Client_Result, which can be checked to see if the request was successful. The method also throws Zend_Http_Client_Exception and Zend_Service_Twitter_exception, which I would of course catch in production code.

<rant>This has taken me hours to figure out. If only the documentation had been properly updated this should have been a cinch to put together. I am a newb at Zend Framework but I think this would have stumped anyone. Please, please, please get this documentation sorted out!</rant>

Anyway, I hope this helps someone and stops them from facing the hours of frustration I just have.

What is LiveDocx?

The Live Docx service allows a programmer to take a document template and through a SOAP based web service populate it with content. The resulting document can then be retrieved to the web server in one of many common formats including PDF, MS Word .doc and .docx and RTF. Best of all the service is completely free at the lowest level, but depending on the requirements of your application it may be more appropriate to use one of the paid for levels of service. The templates can be created in .doc, .docx, .rtf and .txd formats and use mail merge to populate the content. The great advantage is that you can use all of the features of a word processing program to design your document, ending up with a fully professional quality document. Best of all you don’t even need to write any code to access the web service. The latest release of the Zend Framework (1.10) includes a component, Zend_Service_LiveDocx, to access and work with the service and there’s also a .NET library to download for Microsoft developers.

Creating Templates

As mentioned earlier the LiveDocx service uses mail merge fields to perform its magic. You create a document that contains one or more merge fields and then assign content to these fields programmatically at run time. The LiveDocx servers replace the mail merge fields with the content in the same way as a word processing program would, making the completed document available to you. Templates can either be stored directly on the LiveDocx servers or on your own webserver. The SOAP service allows to you specify the name of the template you want to use and whether it is stored locally or remotely. Which one is  chosen will largely depend on the application but storing templates on your own web server does mean that the template must be sent to LiveDocx along with the content before the completed document can be retrieved. This obviously significantly increases the amount of information that needs to be transmitted over the internet but the demands of your application may dictate that templates be stored locally.

Using Zend_Service_LiveDocx

The Zend Framework LiveDocx component is very easy to use and complete documentation can be found here. The Zend Framework download also includes several examples of using the service. Basically you instantiate a Zend_Service_LiveDocx_MailMerge object, setting your username, password and the template you wish to use, before assigning content to the object in much the same way that you would with Smarty. You then call a createDocument() method to produce the document on the remote server followed by a retrieveDocument() method to get the document produced back as a string. The latter method takes an argument which specifies the type of file that should be created. That’s basically it. The code below is a simple view class that I wrote for my application that uses the Zend_Service_LiveDocx to produce a document.

<?php
 /**
 * View for the download plan functionality. Uses the LiveDocx web service and the ZendFramework LiveDocx SOAP integration to produce a file.
 * @author Jeremy Cook
 * @version 1.0
 * @see http://framework.zend.com/manual/en/zend.service.livedocx.html
 */
 class planView {
 /**
 * Array of content to be used in the plan
 *
 * @var array
 */
 protected $content = array();
 /**
 * The type of file to be requested from LiveDocx
 *
 * @var string
 */
 protected $fileType;
 /**
 * Name of the template on LiveDocx to use
 *
 * @var string
 */
 protected $template;
 /**
 * Username for LiveDocx
 *
 * @var string
 */
 protected $username;
 /**
 * Password for LiveDocx
 *
 * @var string
 */
 protected $password;
 /**
 * Name to give the downloaded file
 *
 * @var string
 */
 protected $filename;
 /**
 * Constructor
 *
 * @param array $content
 * @param string $fileType Type of file to be requested from LiveDocx
 * @param string $template Name of the remote template to use on LiveDocx
 * @param string $filename Name to use for the file produced by LiveDocx
 * @param string $username
 * @param string $password
 * @return planView
 */
 public function __construct (array $content, $fileType, $template, $filename, $username, $password) {
    $this->content = $content;
    $this->fileType = $fileType;
    $this->template = $template;
    $this->filename = $filename;
    $this->username = $username;
    $this->password = $password;
 }
 /**
 * Method to produce the plan document
 *
 * @throws Zend_Service_LiveDocx_Exception
 * @throws RuntimeException
 */
 public function getPlan () {
    require_once 'Zend/Service/LiveDocx/MailMerge.php';
    $doc = new Zend_Service_LiveDocx_MailMerge();
    $doc->setUsername($this->username)->setPassword($this->password);
    $doc->setRemoteTemplate($this->template);
    foreach ($this->content as $key => $value) {
       $doc->assign($key, $value);
    }
    $doc->createDocument();
    $document = $doc->retrieveDocument($this->fileType);
    unset($doc);
    $output = fopen('php://output', 'w');
    if (!$output)
       throw new RuntimeException('Unable to bind PHP output as a file handle');
    switch ($this->fileType) {
       case 'pdf':
          header ('Content-Type: application/pdf');
          break;
       case 'doc':
       case 'docx':
          header ('Content-Type: application/vnd.ms-word');
          break;
    }
    $filename = str_replace(' ', '_', $this->filename) . ".{$this->fileType}";
    header ("Content-Disposition: attachment; filename=\"$filename\"");

    //Make sure the browser doesn't cache the file
    //Set headers to ensure the document is not cached.
    header ("Expires: Mon, 26 Jul 1990 05:00:00 GMT");
    header ("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
    header ("Cache-Control: no-cache, must-revalidate");
    header ("Pragma: no-cache");
    //Write the document to php output
    fwrite($output, $document);
    fclose($output);
 }
 }
?>

Some ‘Gotchas’

The two main problems I had in using the LiveDocx service had nothing to do with LiveDocx or Zend_Service_LiveDocx (which has great documentation). The problems I had were in making MS Word do what I wanted in the template creation. Admittedly this may have more to do with the fact that I’d never created a mail merge template before but I thought I’d mention the two issues here. The issues were in adding merge fields to the document and creating bookmarks.

Adding Merge Fields

Merge fields are denoted by the text {MERGEFIELD fieldName} (where ‘fieldName’ is the unique name of the field). What the documentation doesn’t say however is that the curly braces cannot be simply typed on the keyboard. In Word you need to enter ctrl + F9 to get a special set of merge field curly braces. In Word 2007 you can also go to the insert tab then Quick Parts, [field] and select merge field. Add a name for the merge field and it is inserted into the document where your cursor is placed. This second method makes the field look like «fieldName» but this is completely equivalent to the first method with the curly braces.

Adding Bookmarks

With LiveDocx a bookmarked section allows you to iterate over a section of a template, assigning content from an array to merge fields inside the bookmark on each iteration. This enables you to produce sections of documents that have the same structure but different content. This is obviously very handy as varying amounts of content can be assigned to the section of the template. One of the examples in the Zend Framework utilises this to produce a telephone bill where a varying number of calls can be assigned to a bookmarked section, producing a table of all the calls in the final document. The array has to be multi-dimensional, with the top level array being numeric and each nested array being associative where the key is the name of the merge field and the value is the content to be inserted. What the documentation doesn’t tell you is how to create the bookmarks (there’s supposed to be a screenshot in the documentation which is missing) and I spent a few frustrating hours before I finally found out how to do it. Here are the steps.

1. Go to the insert tab in Word and select bookmark.
2. Create a new bookmark that begins with blockStart_ (ie. blockStart_bookmarkName).
3. The bookmark will be invisible in the document but go ahead and add your merge fields with whatever formatting you like.
4. After the last merge field for the section add another bookmark but start it with blockEnd_ (ie. blockEnd_bookmarkName).
5. When you assign content to the bookmarked section make sure that the array is assigned to the name of the bookmark, like the following:

<?php

//Assume $doc is a Zend_Service_LiveDocx_MailMerge object and $array is the multidimensional array to be assigned to the bookmark.

$doc->assign('bookmarkName', $array);

?>

Conclusion

I hope you find this brief introduction to LiveDocx useful. I’ve found it to be a great service that’s easy to use and I’ll certainly use it again the next time I need to produce professional quality documents from within PHP.