EmailExample module upgrade to Zend 3

This section assumes that you have read the section about upgrading custom modules to work with Zend 3. If you have not read this section yet, see Upgrade custom modules to work with Zend 3.

The operation and testing of custom modules is the responsibility of the module creator.  Perforce Software, Inc. is not responsible for the operation of your custom modules, nor does Perforce Software, Inc. make any representations or warranties regarding the interoperability of your custom modules with P4 Code Review.

If you add or edit a module, P4 Code Review will not use that change until the config cache has been reloaded, this forces P4 Code Review to use the module change. You must be an admin or super user to reload the P4 Code Review config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the System Information.

This section describes how to refactor a custom module so that it will work with P4 Code Review 2019.1 and later. We will be refactoring the Example email module, this module has been included in the documentation for a number of years and so is a useful module to use to demonstrate the process.

EmailExample module for P4 Code Review 2018.3 and earlier (Zend 2)

This section contains:

File locations

The content of the email templates in module/EmailExample/view/mail/ are described on the example email module page, see Example email module.

module/
      EmailExample/
                   config/
                          module.config.php
                   view/
                        mail/
                             commit-html.phtml
                             commit-text.phtml
                             comment-html.phtml
                             comment-text.phtml
                             review-html.phtml
                             review-text.phtml	
                   Module.php

Module.php

<?php

namespace EmailExample;
use Zend\Mvc\MvcEvent;

/**
 * Automatically uses any custom email templates found under this
 * module's view/mail folder (e.g. EmailExample/view/mail/commit-html.phtml).
 *
 * Valid templates include:
 *
 *   commit-html.phtml (HTML version of commit notification)
 *   commit-text.phtml (text version of commit notification)
 *   comment-html.phtml (HTML version of comment notification)
 *   comment-text.phtml (text version of comment notification)
 *   review-html.phtml (HTML version of review notification)
 *   review-text.phtml (text version of review notification)
 *
 * Note: you need to provide custom templates for both HTML and text;
 * if you do not provide both, it is possible that the search for
 * customized templates only finds the non-customized versions, making
 * it appear that this module is not working.
 */
class Module
{
    public function onBootstrap(MvcEvent $event)
    {
        $application = $event->getApplication();
        $services    = $application->getServiceManager();
        $events      = $services->get('queue')->getEventManager();

         $events->attach(
            '*',
            function ($event) {
                $mail = $event->getParam('mail');
                if (!$mail || !isset($mail['htmlTemplate'], $mail['textTemplate'])) {
                    return;
                }
   
                $html = __DIR__ . '/view/mail/' . basename($mail['htmlTemplate']);
                $text = __DIR__ . '/view/mail/' . basename($mail['textTemplate']);
    
                if (file_exists($html)) {
                    $mail['htmlTemplate'] = $html;
                }
                if (file_exists($text)) {
                    $mail['textTemplate'] = $text;
                }
    
                $event->setParam('mail', $mail);
            },
            -199
        );
    }
}

EmailExample module for P4 Code Review 2019.1 and later (Zend 3)

This section shows the files that need to change and also new files that are required for P4 Code Review 2019.1 and later (Zend 3).

The PHP 7.x new language features enable you to use [] as a shortcut for array().

This section contains:

File locations

Changes:

  • custom.modules.config.php: new configuration file that tells P4 Code Review to auto-load classes and lists the custom modules it can use, see config/custom.modules.config.php.

    • The custom.modules.config.php file is used for all of the P4 Code Review custom modules and contains a list of the modules you want P4 Code Review to run.

  • Listener.php: new file that defines the listeners P4 Code Review uses for this module, see module/EmailExample/src/Listener/Listener.php.
  • The email templates in module/EmailExample/view/mail/ do not need changing. For details of the email template file content, see Example email module.
config/
      custom.modules.config.php
module/
      EmailExample/
                  config/
                         module.config.php
                  src/
                     Listener/
                              Listener.php		
                  view/
                       mail/
                           commit-html.phtml
                           commit-text.phtml
                           comment-html.phtml
                           comment-text.phtml
                           review-html.phtml
                           review-text.phtml
                  Module.php

config/custom.modules.config.php

This is a new file that is used to auto-load classes and to tell P4 Code Review which custom modules it should run.

Changes:

  • Create the custom.modules.config.php file in the config directory if it does not already exist and edit the file so that it contains the code to auto-load classes

    • The custom.modules.config.php file is used for all of the P4 Code Review custom modules and contains a list of the modules you want P4 Code Review to run.

  • Add the EmailExample module namespace so that it is enabled in P4 Code Review
<?php
\Zend\Loader\AutoloaderFactory::factory(
    array(
        'Zend\Loader\StandardAutoloader' => array(
            'namespaces' => array(
                'EmailExample'      => BASE_PATH . '/module/EmailExample/src',
            )
        )
    )
);
return [
    'EmailExample'
];

module/EmailExample/Module.php

Changes:

  • getAutoloaderConfig() deleted. Functionality has been moved to config/custom.modules.config.php
  • onBootstrap method deleted. Functionality has been moved to module/EmailExample/src/Listener/Listener.php

    • In this example, onBootstrap was only being used to attach listener events so it was removed entirely.

    However onBootstrap can also be used to provide other functionality for custom modules, if this is the case only remove the attach listener event functionality from onBootstrap. 

<?php
/**  
 * Perforce Swarm
 *
 * @copyright   2019 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
*/

namespace EmailExample;

class Module
{
    public function getConfig()
    {
        return include __DIR__ . '/config/module.config.php';
    }
}

module/EmailExample/config/module.config.php

Changes:

Edit the content of your module.config.php to configure your event listeners, this replaces the attach listener event functionality of the onBootstrap method in the original Module.php file

Listener::class example details:

  • Events\Listener\ListenerFactory::ALL => [

    • We are listening to ALL here for convenience because we are listening for mail events but this means it will trigger on every event. Usually is better to just listen for the events you are interested in. For example, if you are interested in commits and shelves you would listen on COMMIT and SHELVE events.

  • Events\Listener\ListenerFactory::PRIORITY => -199,

    • Declares an event priority of -199 for the event listener because email delivery events are processed with a priority of -200 and the example event needs to run just before the email delivery event.

  • Events\Listener\ListenerFactory::CALLBACK => 'handleEmail',

    • Declares the function name within the listener class that is called.

  • Events\Listener\ListenerFactory::MANAGER_CONTEXT => 'queue'

    • Triggers your custom listener when P4 Code Review processes the P4 Code Review event queue.

<?php
/**
 * Perforce Swarm
 *
 * @copyright   2019 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
*/

$listeners = [EmailExample\Listener\Listener::class];
return [
    'listeners' => $listeners,
    'service_manager' =>[
        'factories' => array_fill_keys(
            $listeners,
            Events\Listener\ListenerFactory::class
        )
    ],
    Events\Listener\ListenerFactory::EVENT_LISTENER_CONFIG => [ 
        Events\Listener\ListenerFactory::ALL => [
            EmailExample\Listener\Listener::class => [
                [
                    Events\Listener\ListenerFactory::PRIORITY => -199,
                    Events\Listener\ListenerFactory::CALLBACK => 'handleEmail',
                    Events\Listener\ListenerFactory::MANAGER_CONTEXT => 'queue'
                ]
            ]
        ]
    ]
];

module/EmailExample/src/Listener/Listener.php

Changes:

  • Create a file called Listner.php in the module/EmailExample/src/Listener/ directory.
  • Edit the content to configure your event listeners, this replaces the attach listener event functionality of the onBootstrap method in the original Module.php file
  • Logging has been added
<?php
/**
 * Perforce Swarm
 *
 * @copyright   2019 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
*/

namespace EmailExample\Listener;

use Events\Listener\AbstractEventListener;
use Zend\EventManager\Event;

class Listener extends AbstractEventListener
{
    /**
     * Automatically uses any custom email templates found under this
     * module's view/mail folder (e.g. Example/view/mail/commit-html.phtml).
     *
     * Valid templates include:
     *
     *  commit-html.phtml (HTML version of commit notification)
     *  commit-text.phtml (text version of commit notification)
     *  comment-html.phtml (HTML version of comment notification)
     *  comment-text.phtml (text version of comment notification)
     *  review-html.phtml (HTML version of review notification)
     *  review-text.phtml (text version of review notification)
     *
     * Note: you need to provide custom templates for both HTML and text;
     * if you do not provide both, it is possible that the search for
     * customized templates only finds the non-customized versions, making
     * it appear that this module is not working.
     */

    /**
     * Handle the Email and set the new templates.
     *
     * @param Event $event
     */
    public function handleEmail(Event $event)
    {
        $logger = $this->services->get('logger');
        $logger->info("EmailExample: handleEmail");
        $mail = $event->getParam('mail');
        if (!$mail || !isset($mail['htmlTemplate'], $mail['textTemplate'])) {
            return;
        }

        $html = __DIR__ . '/view/mail/' . basename($mail['htmlTemplate']);
        $text = __DIR__ . '/view/mail/' . basename($mail['textTemplate']);

        if (file_exists($html)) {
            $mail['htmlTemplate'] = $html;
        }
        if (file_exists($text)) {
            $mail['textTemplate'] = $text;
        }

        $event->setParam('mail', $mail);
        $logger->info("EmailExample: handleEmail end.");
    }
}