EmailExample module upgrade to Zend 3

This section describes how to refactor a custom module so that it will work with Swarm 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 Swarm 2018.3 and earlier (Zend 2)
• EmailExample module for Swarm 2019.1 and later (Zend 3)

EmailExample module for Swarm 2018.3 and earlier (Zend 2)

This section contains:

• File locations
• Module.php

File locations

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 Swarm 2019.1 and later (Zend 3)

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

This section contains:

• File locations
• config/custom.modules.config.php
• module/EmailExample/Module.php
• module/EmailExample/config/module.config.php
• module/EmailExample/src/Listener/Listener.php

File locations

Changes:

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

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

• Listener.php: new file that defines the listeners Swarm 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 Swarm 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
Tip

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

• Add the EmailExample module namespace so that it is enabled in Swarm

<?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
Tip

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

<?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.");
    }
}