Example linkify module

The following example module demonstrates how to turn text that appears in changelist, job, or code review descriptions, comments, and activity entries into links.

Note

Swarm supports the Laminas component versions in the LICENSE.txt file, features and functions in the Laminas documentation that were introduced in later versions of Laminas will not work with Swarm. The LICENSE.txt file is in the readme folder of your Swarm installation.

Tip

You must test your custom modules on a test system before transferring them to your production system. This avoids any negative impact on the operation of your production system. If you have more than one custom module, the modules should all be tested at the same time on the same test system as this ensures that the modules operate correctly with each other and with Helix Swarm.

Tip

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

Basic steps needed to create the Email Example module are:

Create the Module.php file
Create the module.config.php file
Enable the Rickroll module for Swarm in custom.modules.config.php

File locations

For reference, the Rickroll module uses the following filenames and locations:

config/
      custom.modules.config.php
module/
      Rickroll/
               config/
                      module.config.php
               Module.php

Create the Module.php file

Module.php will:

Declare the module namespace, this must match the directory name of the module.
Provide the Linkify application.
Provide the onBootstrap() function.
Add a callback to the Linkify module that declares what text is to be searched for (rickroll) and, when found, how to compose the link for that text.
Provide the getConfig() function.

Create the Module.php file:

Create a directory called Rickroll in the module directory.
Create the file Module.php in module/Rickroll.
Edit Module.php to contain:

<?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 Rickroll;

use Application\Filter\Linkify;

class Module
{
    public function onBootstrap()
    {
        Linkify::addCallback(
            // Linkify requires 3 parameters: "$linkify", "$value" and "$escaper" 
            function ($linkify, $value, $escaper) {
                if (strcasecmp($value, 'rickroll')) {
                    // not a hit; tell caller we did not handle this one
                    return false;
                }

                return '<a target="_new" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">'
                           . $escaper->escapeHtml($value) . "</a>";
            },
            'rickroll',
            strlen('rickroll')
        );
    }

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

Now Create the module.config.php file.

Create the module.config.php file

The module.config.php file is required but for the linkify module only has an empty return.

Create the module.config.php file:

Create a file called module.config.php in Rickroll/config.
Edit module.config.php to contain:

<?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>
*/

{
    return array();
}

Now Enable the Rickroll module for Swarm in custom.modules.config.php.

Enable the Rickroll module for Swarm in custom.modules.config.php

Swarm uses the custom.modules.config.php file to auto-load classes and to check which custom modules it should run. This gives you control over which modules Swarm loads and prevents modules from being loaded by mistake.

Create the custom.modules.config.php file:

Create the config directory at the same level as the module directory if it does not exist.
Create the custom.modules.config.php file in the config directory if it does not exist.
Edit the custom.modules.config.php file so that it contains the auto-loader and the Rickroll module details:

Tip

If you already have one or more custom modules enabled for Swarm, the auto-loader and the existing module details will already be in the file.

Just add Rickroll to the namespaces and return arrays of the custom.modules.config.php file.

<?php
\Laminas\Loader\AutoloaderFactory::factory(
    array(
        'Laminas\Loader\StandardAutoloader' => array(
            'namespaces' => array(
                'Rickroll'      => BASE_PATH . '/module/Rickroll',
            )
        )
    )
);
return [
    'Rickroll'
];

The Swarm config cache must be reloaded so that Swarm can see your new module. As an admin or super user, navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

The Rickroll module is now enabled for Swarm. Swarm will now replace the text "rickroll " in changelist, job, or code review descriptions, comments, and activity entries with a link to "https://www.youtube.com/watch?v=dQw4w9WgXcQ".

Check that the module works correctly before moving it to your production server.