To get started, create the contact module using the Zend Tool Project's create module command, as shown in Listing 10-1. This will create the module directory and the required subdirectories.

zf create module contact

Now you need to create the contact controllers and views manually. First create the index controller. Add a new file to the application/modules/contact/controllers directory named IndexController.php. Open this file, and add the controller class. Note that the class names of the module controllers are prepended with the module namespace, so in this case the controller class name should be Contact_IndexController. Add an empty indexAction() method to this controller, as shown in Listing 10-2.

<?php
class Contact_IndexController extends Zend_Controller_Action

{
    public function indexAction()
    {

    }
}

Next you need to add a directory to the module's view directory for the index controller's views named index. Then add a new file to this directory named index.phtml. Add a headline to the page for now, as shown in Listing 10-3. You will add the actual contact form to this page shortly.

<h2>Contact Us</h2>

Now that the contact module is created, you need to configure your application to load it. This requires two things; you need to update the main application configuration file and create a bootstrap file for the contact module.

To get started, open the configuration file (application/configs/application.ini). First set the front controller's module directory to modules. Once this is set, the front controller will automatically load each of the modules that are in this directory. Next set the module resource to an empty array. Then you need to override the setting you added earlier, where you set the default controller to page. Set this back to index. Listing 10-4 shows the three lines you need to add.

resources.frontController.moduleDirectory = APPLICATION_PATH "/modules"
resources.modules[] = ""
contact.resources.frontController.defaultControllerName = "index"

The last step of configuring your module is to bootstrap it. If your module has a file named Bootstrap.php in its root with a class named {Module}_Bootstrap, then Zend_Application will use this file to bootstrap your module. In the contact form's case, there is not a lot of custom configuration required; it needs only to reset the defaultControllerName. It will do this automatically since you set it in the configuration file.

Create a new file in the root of your contact module named Bootstrap.php. Add a class to this file named Contact_Bootstrap, which should extend Zend_Application_Module_Bootstrap, as shown in Listing 10-5.

<?php
class Contact_Bootstrap extends Zend_Application_Module_Bootstrap
{}

Once this file is in place, you should be able to point your browser to http://localhost/contact and see the index page of the contact module.

Now that the contact module is wired up, you are ready to construct the contact form. Create a new directory in the contact module named forms. Then create a new file in this directory named Contact.php. The module resources (forms and models) will be automatically loaded if you follow the module namespace convention like the controller class; the contact form class will be called Contact_Form_Contact. Add this class to the Contact.php file.

The contact form will need four fields: the person's name, their e-mail address, the subject, and the message. All of the fields are required. You will also need to validate that the e-mail address is valid. Listing 10-6 shows the completed form.

<?php
class Contact_Form_Contact extends Zend_Form
{
    public function init()
    {
        // create new element
        $name = $this->createElement('text', 'name'),
        // element options
        $name->setLabel('Enter your name:'),
        $name->setRequired(TRUE);
        $name->setAttrib('size',40);
        // add the element to the form
        $this->addElement($name);

        // create new element
        $email = $this->createElement('text', 'email'),
        // element options
        $email->setLabel('Enter your email address:'),
        $email->setRequired(TRUE);
        $email->setAttrib('size',40);
        $email->addValidator('EmailAddress'),
        $email->addErrorMessage('Invalid email address!'),
        // add the element to the form
        $this->addElement($email);

        // create new element
        $subject = $this->createElement('text', 'subject'),
        // element options
        $subject->setLabel('Subject: '),
        $subject->setRequired(TRUE);
        $subject->setAttrib('size',60);
        // add the element to the form

$this->addElement($subject);

        // create new element
        $message = $this->createElement('textarea', 'message'),
        // element options
        $message->setLabel('Message:'),
        $message->setRequired(TRUE);
        $message->setAttrib('cols',50);
        $message->setAttrib('rows',12);
        // add the element to the form
        $this->addElement($message);

        $submit = $this->addElement('submit', 'submit',
            array('label' => 'Send Message'));
    }
}

Now you need to load the form in the contact module's index controller. Open the file, and update the indexAction() method; first create an instance of the form, then set the action and method, and finally pass it to the view to render, as shown in Listing 10-7.

public function indexAction()
{
    $frmContact = new Contact_Form_Contact();
    $frmContact->setAction('/contact'),
    $frmContact->setMethod('post'),
    $this->view->form = $frmContact;
}

Then you simply need to update the view script to render the form, as shown in Listing 1087.

<h2>Contact Us</h2>
<p>To send us a message please complete the form below and click Send Message.</p>
<?php echo $this->form; ?>

Once you have updated the view script, point your browser to http://localhost/contact, and you should see the contact form in Figure 10-1.

Figure 10.1. The contact form

Now that the form is completed, you need to update the indexAction() method of the contact index controller again to process the form submission. This process will be very similar to the other forms that you have worked with. First you need to check and see whether the request method is POST, which means that the form has been posted back. Next you need to load the form with the POST data and confirm that it is valid (as shown in Listing 10-9). If it is valid, then you can send the message.

public function indexAction()
{
    $frmContact = new Contact_Form_Contact();
    if($this->_request->isPost() && $frmContact->isValid($_POST)) {
        //send the message
    }
    $frmContact->setAction('/contact'),
    $frmContact->setMethod('post'),
    $this->view->form = $frmContact;
}

Note that I just added a placeholder where you are going to send the message. I will go over that process next.

The Zend_Mail component gives you the capability to send e-mail messages from your project. You can send either plain-text messages or rich HTML messages. You have a number of options regarding the transport method you use. I generally use the default sendmail client, but you can use SMTP if you want to route your mail through a different server.

In this example, I'll show how to send an HTML message through the sendmail client, but feel free to modify this if necessary.

<h1>Contact Form Submission</h1>
<p>You received a new contact form submission from:</p>
<ul>
    <li>Name: <?php echo $this->name; ?></li>
    <li>Email Address: <?php echo $this->email; ?></li>
</ul>
<h2>Message</h2>
<h3><?php echo $this->subject; ?></h3>
<p><?php echo $this->message; ?></p>

public function indexAction()
{
    $frmContact = new Contact_Form_Contact();
    if($this->_request->isPost() && $frmContact->isValid($_POST)) {
        // get the posted data
        $sender = $frmContact->getValue('name'),
        $email = $frmContact->getValue('email'),
        $subject = $frmContact->getValue('subject'),
        $message = $frmContact->getValue('message'),

        // load the template
        $htmlMessage = $this->view->partial(
            'templates/default.phtml',
            $frmContact->getValues()
        );

$mail = new Zend_Mail();
        // set the subject
        $mail->setSubject($subject);
        // set the message's from address to the person who submitted the form
        $mail->setFrom($email, $sender);
        // for the sake of this example you can hardcode the recipient
        $mail->addTo('[email protected]', 'webmaster'),
        // it is important to provide a text only version in
        // addition to the html message
        $mail->setBodyHtml($htmlMessage);
        $mail->setBodyText($message);
        //send the message
        $result = $mail->send();
        // inform the view with the status
        $this->view->messageProcessed = true;
        if($result) {
            $this->view->sendError = false;
        } else {
            $this->view->sendError = true;
        }
    }
    $frmContact->setAction('/contact'),
    $frmContact->setMethod('post'),
    $this->view->form = $frmContact;
}

<h2>Contact Us</h2>
<?php if($this->messageProcessed && $this->sendError) { ?>
    <p>Sorry there was an error sending your message. Please contact

 [email protected] for more help.</p>
<?php } elseif ($this->messageProcessed &! $this->sendError) {?>
    <p>Thank you for contacting us. We will be in touch soon.</p>
<?php } else { ?>
    <p>To send us a message please complete the form below
        and click Send Message.</p>
    <?php echo $this->form;
}

You will almost be guaranteed to get some spam when you publish a contact form on your site. You can minimize this in a number of ways (such as asking a simple mathematical question), but CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is the most effective at the time of this writing. It authenticates that a real person is submitting the form rather than an automated process. It does this by requiring the user to perform some challenge task, such as typing the letters of a graphical piece of text, which is difficult (but not impossible) for an automated process to do.

Zend_Captcha includes a number of back-end adapters that can generate CAPTCHA for your program:

I have used several of the adapters, but I really like the Recaptcha service. It is a web project that is attempting to digitize literature that was written prior to the digital revolution. It does this by photographically scanning the works and then transforming it into text using "optical character recognition" software. The issue is that this software is not perfect, so the Recaptcha service sends the text that it cannot translate to humans to decipher. You get a simple and effective CAPTCHA service while helping this project.

To get started using the Recaptcha service, you need to sign up on its site (http://recaptcha.net) for an API key. Once you have this key, integrating the service with your form is a trivial task. Zend_Form has a CAPTCHA form element that handles the rendering and validation for you. Add this element to your form, configuring it as is demonstrated in Listing 10-13.

// configure the captcha service
$privateKey = 'your private key';
$publicKey = 'your public key';
$recaptcha = new Zend_Service_ReCaptcha($publicKey, $privateKey);

// create the captcha control
$captcha = new Zend_Form_Element_Captcha('captcha',
    array('captcha'        => 'ReCaptcha',
        'captchaOptions' => array('captcha' => 'ReCaptcha', 'service' => $recaptcha)));

// add captcha to the form
$this->addElement($captcha);

Now if you point your browser to the contact form (http://localhost/contact), you should see the Recaptcha control, as in Figure 10-2.

Figure 10.2. The contact form, secured with the Recaptcha form element

There are many situations where you may not want to use the default mail server. A few examples include when you are working on a development server that does not have a mail server configured and when your site has a large volume of messages that you do not want bogging down your web server. SMTP mail transport enables you to send mail through a remote server.

To configure Zend_Mail to use SMTP transport, you first have to create a new instance of Zend_Mail_Transport_Smtp, which you configure with the address to the mail server and your user credentials. Listing 10-14 demonstrates how to update the mail method in the indexAction() to use SMTP transport.

$mail = new Zend_Mail();
// configure and create the SMTP connection
$config = array('auth' => 'login',
    'username' => 'myusername',
    'password' => 'password'),

$transport = new Zend_Mail_Transport_Smtp('mail.server.com', $config);

// set the subject
$mail->setSubject($subject);
// set the message's from address to the person who submitted the form
$mail->setFrom($email, $sender);
// for the sake of this example you can hardcode the recipient
$mail->addTo('[email protected]', 'webmaster'),
// it is important to provide a text only version in addition to the html message
$mail->setBodyHtml($htmlMessage);
$mail->setBodyText($message);
//send the message, now using SMTP transport
$result = $mail->send($transport);

You may want to enable file attachments on your contact form in certain circumstances. For example, your users might need to upload a screenshot if the form is being used for technical support.

Attaching files to your contact form messages is a two-step process; first you need to upload the file from the user's desktop to the server, and then you need to attach the file to the message. A number of other things need to be done behind the scenes, such as setting the MIME type, but Zend_Mail handles that for you.

Uploading the File

The first thing you need to do is update the contact form and indexAction() to enable the users to upload files.

Warning

The file element requires a little more configuration than many of the other elements; allowing a site visitor to upload a file onto your server is not something to take lightly!

Start by creating a new directory for the file uploads named uploads. This directory should be in the root of your project because these files should never be publicly accessible.

Then add a new file element to the contact form beneath the subject element, setting the upload destination to the upload directory you just created.

The next step is validating the upload. Note that for this example I limited uploads to image files, but you can add any file types you need to allow. Add the following validators to your file element:

• Count: Ensures that only one file is uploaded

• Size: Sets a reasonable limit to the file size, in this case 100KB

• Extension: Ensures that only allowed file types can be uploaded

The final step is setting the enctype attribute of the form to multipart/form-data so it accepts file uploads. Listing 10-14 shows the complete element.

Example 10.15. Creating the File Upload Control in application/modules/contact/forms/Contact.php

// create new element
$attachment = $this->createElement('file', 'attachment'),
// element options
$attachment->setLabel('Attach a file'),
$attachment->setRequired(FALSE);
// specify the path to the upload folder. this should not be publicly accessible!
$attachment->setDestination(APPLICATION_PATH . '/../uploads'),
// ensure that only 1 file is uploaded
$attachment->addValidator('Count', false, 1);
// limit to 100K
$attachment->addValidator('Size', false, 102400);
// only allow images to be uploaded
$attachment->addValidator('Extension', false, 'jpg,png,gif'),
// add the element to the form
$this->addElement($attachment);
// set the enctype attribute for the form so it can upload files
$this->setAttrib('enctype', 'multipart/form-data'),

Now if you point your browser to the contact form (http://localhost/contact), you should see the file control, as in Figure 10-3.

Figure 10.3. The contact form with the file upload control

$mail = new Zend_Mail();
// configure and create the SMTP connection
$config = array('auth' => 'login',
    'username' => 'myusername',
    'password' => 'password'),

$transport = new Zend_Mail_Transport_Smtp('mail.server.com', $config);

// set the subject
$mail->setSubject($subject);
// set the message's from address to the person who submitted the form
$mail->setFrom($email, $sender);
// for the sake of this example you can hardcode the recipient
$mail->addTo('[email protected]', 'webmaster'),
// add the file attachment
$fileControl = $frmContact->getElement('attachment'),
if($fileControl->isUploaded()) {
    $attachmentName = $fileControl->getFileName();
    $fileStream = file_get_contents($attachmentName);
    // create the attachment
    $attachment = $mail->createAttachment($fileStream);
    $attachment->filename = basename($attachmentName);
}
// it is important to provide a text only version in addition to the html message
$mail->setBodyHtml($htmlMessage);
$mail->setBodyText($message);
//send the message, now using SMTP transport
$result = $mail->send($transport);

In this chapter, you learned how to extend a Zend Framework project by adding modules to the project. After this brief overview, you created a new contact module, which served as a good example of a very common addition to dynamic web sites. While you built this module, you also learned how to create and send e-mail messages with Zend_Mail, including some of the more advanced features such as using SMTP transport and handling file attachments.