Module (Old Way)

A Phoenix module is a way of adding an addon to Phoenix that can be enabled/disabled as well as have customizable options that admins can adjust within their module area.

A module in Phoenix requires a couple of files at minimum:

Module File
- This is the file that will have the module class and logic.
Language File
- You will want to create a language file for each language that you plan to support. I usually just create an english version but you can choose which ever language you require.

For this example we will just add a javascript alert to the catalog for a simple test.

Create a new file, calling it something that is unique that won’t collide with other modules. (Refer to rules)

We’ll call this file:

ht_zipur_alert_example.php

and we’ll place it in:

catalog/includes/modules/header_tags/

The above path refers to your “catalog” or base directory of your store.

The above path also refers to “header_tags” which is one of the module types.

Here is an example of the file:

<?php
    /**
     * $Id: ht_zipur_alert_example.php
     * $Loc: catalog/includes/modules/header_tags/
     *
     * zipurAlertExample
     * Version: 0.1.0
     * Author: Preston Lord
     *         aka zipurman / zipur.ca / plord@inetx.ca
     *
     * Modified Date: 08/05/2020
     * Created as a module test
     * Copyright (c) 2020: Preston Lord - @zipurman
     * All rights reserved.
     * Released under the GNU General Public License
     */
    
    class ht_zipur_alert_example {
        var $code = 'ht_zipur_alert_example';
        var $group = 'header_tags';
        var $title;
        var $description;
        var $alerttext;
        var $enabled = false;

        function __construct() {
            $this->title       = MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TITLE;
            $this->description = MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_DESCRIPTION;
            if ( defined( 'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE' ) ) {
                $this->alerttext = MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT;
                $this->enabled    = ( MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE == 'True' );
            }
        }

        function execute() {
            $script = <<<js
            <script>
            alert('{$this->alerttext}');
            </script>
            js;
            $GLOBALS['oscTemplate']->addBlock( "{$script}", 'footer_scripts' );

        }

        function isEnabled() {
            return $this->enabled;
        }

        function check() {
            return defined( 'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE' );
        }

        function install() {
            tep_db_query( "insert into configuration (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) values ('Enable Zipur Test Alert', 'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE', 'True', 'Do you want to allow Zipur Test Alert to be added to the site?', '6', '1', 'tep_cfg_select_option(array(\'True\', \'False\'), ', now())" );
            tep_db_query( "insert into configuration (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) values ('Alert Message', 'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT', '', 'Your visitors will see this message.', '6', '1', '0', now())" );
        }

        function remove() {
            tep_db_query( "delete from configuration where configuration_key in ('" . implode( "', '", $this->keys() ) . "')" );
        }

        function keys() {
            return [
                'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE',
                'MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT',
            ];
        }
    }

Let’s break down the above module example:

A comment block should always be added to the top of your file to show the details, author, copyright, etc.
The class name ht_zipur_alert_example is very important.
This should match the other files in the folder. In this example, all header_tags modules are prepended with a “ht_“
At the start of the class you have some variables being set, $code, $group, $title … these should make sense as the example shows.
The __construct() method is called when the ht_zipur_alert_example class is instantiated (started)
- This method sets the class variables to their defaults from the language file (I will explain the language files next)
- In Phoenix, modules are expected to have certain variables. Both $title and $description are expected and will be shown in the admin when describing the module.
- The “if” statement checks to see if the module is enabled/defined and if so, it sets a couple of other parameters.
The execute() method is the main part of the module. This is what is called when the module executes.
- In this example, we are simply creating a heredoc block with a script that fires our alert message and then injecting the result into the “footer_scripts” area of the Phoenix core. There are several areas in the Phoenix core you can target.
The isEnable() method will return true/false depending on if the module is installed or not. (I am not sure if this is needed but I include as other modules seem to have it there)
The check() method will return true/false depending on if the module is installed or not. (I am not sure if this is needed but I include as other modules seem to have it there)
The install() method is used when an admin decides to install the module. Upon them installing, the code in this method will run.
- tep_db_query will query the database attached to your catalog.
  In this example, 2 inserts are sent to the configuration table
  - The first is what activates the module. You will notice that the insert “MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE” matches the above logic to test if it is defined or not. This is important to get right.
  - The second insert “MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TEXT” is what we will use in the admin to prompt for our alert message and will also be what we use in the __construct() method to assign the text to our class variable of $alerttext
- You could also add additional configuration options here, each with their own unique name and then use those defined variables in your logic
The remove() method simply removes all of your configuration from the database. This should also disable/remove your method from being installed.
The keys() method returns a list of all configuration keys that are used in your module. It is important to have them all listed in this area to avoid junk being left behind when removed as well as module not being properly uninstalled. You’ll notice that for each item in this array, there is a matching item in the install()

Now we need to add a language file. You must match the path to your above module so we will place this file as:

catalog/includes/languages/english/modules/header_tags/ht_zipur_alert_example.php

The language file will then be loaded when the module is loaded.

Here is the file:

<?php
    /**
     * $Id: ht_zipur_alert_example.php
     * $Loc: catalog/includes/languages/english/modules/header_tags/
     *
     * zipurAlertExample
     * Version: 0.1.0
     * Author: Preston Lord
     *         aka zipurman / zipur.ca / plord@inetx.ca
     *
     * Modified Date: 08/05/2020
     * Created as a module test
     * Copyright (c) 2020: Preston Lord - @zipurman
     * All rights reserved.
     * Released under the GNU General Public License
     */

    define('MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_TITLE', 'Zipur Alert Example');
    define('MODULE_HEADER_TAGS_ZIPUR_ALERT_EXAMPLE_DESCRIPTION', 'Add the Zipur Alert Example to your site.');

In the above example we simply have our defined variables that we use in the module. These ARE NOT the same as the defined keys that we add to the database in the install() of the main class, but these are any language items wrapped around the module that people will see in either the admin configuration or the front-end website visitors.

Phoenix Docs

Related Articles