Zen Cart Documentation – Encapsulated Plugins

Dev: Encapsulated Plugin Directory Structure

Mon, 01 Jan 0001 00:00:00 +0000

Directory Structure

Plugins written for the new architecture will reside in the zc_plugins directory. Within their directory, plugin authors can add subdirectories that mimic the main Zen Cart directories. Note how each plugin starts with a versioned directory. This allows for automated upgrades and the possibility of downgrading as well.

Note that the admin sub-directory must be called admin here (not renamed) and the catalog sub-directory contains the storefront files.

e.g.

zc_plugins
- PluginName
  - v1.0.0
    - manifest.php
    - database_tables.php (auto loads for both catalog and admin, since ZC v2.2.0)
    - filenames.php (auto loads for both catalog and admin, since ZC v2.2.0)
    - Installer
      - languages
        
        english
    - admin
      - includes
        
        auto_loaders
        
        classes
        
        observers
        
        extra_configures
        
        extra_datafiles
        
        functions
        
        extra_functions
        
        init_includes
        
        javascript
        
        languages
        
        english
        
        extra_definitions
    - catalog
      - includes
        
        auto_loaders
        
        classes
        
        ajax
        
        observers
        
        extra_configures
        
        extra_datafiles
        
        functions
        
        extra_functions
        
        init_includes
        
        languages
        
        english
        
        extra_definitions
        
        modules
        
        pages
        
        sideboxes
        
        templates
        
        default
        
        common (note that only additional common files will be loaded!)
        
        css
        
        images
        
        jscript
        
        templates
  - v1.0.1
    - Uses a similar structure to v1.0.0, with any files added/modified/removed since that version
    - EVERY subsequent version MUST BE able to exist on its own without any prior versions installed. ie: must be a complete fileset.

Notes:

Zen Cart v1.5.7 or later is required. Plugins for prior versions must be installed directly into the main Zen Cart directory structure.
The Installer folder is optional; you can embed the installation logic in your plugin if you prefer. See Installer Classes and Plugin SQL Installation for details on using the Installer folder.
Naming an /admin/javascript/ file the same name as your PHP file name will make it automatically load. If you have additional .js files to load, give them names starting with the PHP file name followed by an underscore. For example, if you create a file called admin/rewards.php, the autoloader will load admin/includes/javascript/rewards.js, as well as any JavaScript file whose name matches the pattern admin/includes/javascript/rewards_*.js, e.g. admin/includes/javascript/rewards_sha-256.js.

Dev: Encapsulated Plugin Manifest Files

Mon, 01 Jan 0001 00:00:00 +0000

Manifest Files

Each plugin must have a manifest.php file in the root of its version directory.

e.g.

zc_plugins
- myPlugin
  - v1.0.0
    - manifest.php

An example manifest file would look like:

<?php
return [
    'pluginVersion' => 'v3.0.0',
    'pluginName' => 'Display logs',
    'pluginDescription' => 'Display and manage Zen Cart log files.',
    'pluginAuthor' => 'Vinos de Frutas Tropicales (lat9)',
    'pluginId' => 1583, // ID from Zen Cart forum
    'zcVersions' => ['v157'],
    'changelog' => '', // online URL (eg github release tag page, or changelog file there) or local filename only, ie: changelog.txt (in same dir as this manifest file)
    'github_repo' => '', // url
    'pluginGroups' => [],
];

pluginVersion

The version of this plugin. It should match the version number entered when submitting the plugin to the Plugins Library on the Zen Cart forum.

pluginName

A human readable string for the name of the plugin.

pluginDescription

A human readable string describing the plugin.

Flagrant advertising is not permitted.

pluginAuthor

A human readable string for the plugin author.

PluginId

The id number assigned by the Zen Cart forum site when submitting the plugin for review, e.g. https://www.zen-cart.com/downloads.php?do=file&id=1583. This is used by the store’s Plugin Manager to check for whether new versions have been submitted.

The Plugin Manager only alerts about new versions of this plugin if the store’s Zen Cart version matches one of the versions specified in a given update on the Zen Cart Plugins Library. Set it to 0 if you’re writing a plugin that you’re not submitting to the Plugins Library. (eg: a commercial plugin)

changelog

Online URL (eg github release tag page, or changelog file there) or local filename only, ie: changelog.txt (in same dir as this manifest file)

github_repo

A link to the plugin’s github repo, if one exists.

zcVersions

An array of the Zen Cart versions the plugin supports. (eg: ['v157'], or ['v157','v158']). Note the v prefix and the 3 digits and the lack of decimals (".").

pluginGroups

not currently supported but will eventually support filtering the display of plugins in the admin.

Dev: Encapsulated Plugin Installer Language Files

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Installer Language Files

While most language constants for the plugin installer are managed internally there will be cases where a plugin needs to define some of its own language defines.

For example, if the plugin needs to test some pre-requisites before installing, the error messages for when those pre-requisites fail will need to be defined. In these cases the plugin system allows for loading custom language files.

NOTE These files use define() statements. The array-based language-file format is not supported here.

The main custom language file would reside in the [plugin version directory]/languages/[language name]/main.php file.

e.g.

zc_plugins
- PluginName
  - v1.0.0
    - Installer
      - languages
        
        english
        
        main.php

If the plugin needs more customization and wants to split off other language defines into separate files it can also load the language files separately. A helper method in the installer class can be used to do this.

e.g.

$this->loadInstallerLanguageFile('myFile.php');

Remember, we are talking here about language defines that are only used during installation. Loading of language files needed by the plugin itself are handled differently.

Dev: Encapsulated Plugin Installer Classes

Mon, 01 Jan 0001 00:00:00 +0000

Installer Classes

In many cases you may not need anything custom done for a plugin beyond merely some SQL queries, which would be done in install.sql and removed via uninstall.sql. (But upgrades cannot be done merely via .sql files.)

However there may be times when a plugin needs to override the default installer behavior. Or handle database-changes during an Upgrade from a prior plugin version.

For example a plugin may need to check some pre-requisites before allowing installation, such as the availability of a PHP extension or maybe the plugin relies on another plugin being installed.

In these cases the plugin can define its own installer class that extends the base installer.

The class must be named ScriptedInstaller.php and be placed in the Installer directory.

e.g.

zc_plugins
- rewardPoints
  - v1.0.0
    - Installer
      - ScriptedInstaller.php

The skeleton of this class should look like :

<?php
use Zencart\PluginSupport\ScriptedInstaller as ScriptedInstallBase;

class ScriptedInstaller extends ScriptedInstallBase
{ 
    /**
     * @return bool
     */
    protected function executeInstall()
    {
        return true;
    }

    /**
     * @return bool
     */
    protected function executeUninstall()
    {
        return true;
    }

    /**
     * @return bool
     */
    protected function executeUpgrade($oldVersion)
    {
        return true;
    }
}

Important Notes for coding in the context of a `ScriptedInstaller` class

Database Querying

Using the alternate query functions below will allow the ScriptedInstaller to report query failures so that the install aborts with a logged and displayed message.
Avoid making $db-> calls directly (tip: if you have to global $db then you’re not doing it right! … in this context.
For non-SELECT queries, instead of $db->Execute($sql) use $this->executeInstallerSql($sql)
For a SELECT query use $this->executeInstallerSelectQuery($sql) instead of $db->Execute($sql)
Instead of zen_db_perform() use $this->executeInstallerDbPerform() with the same usual parameters.
The record ID of a single record created by a db query can be accessed with $insert_id = $this->dbConn->insert_ID();
The number of rows affected by a query can be accessed with $rows = $this->dbConn->affectedRows();
Use $this->dbConn-> instead of $db-> if you really need to access the queryFactory object directly.
If you need to inspect the database schema, use the global $sniffer class, as you normally would.

Database DEFINES

NEW database TABLES need to have constants defined!!!!
- /catalog/includes/extra_datafiles/database_tables.php if you need to use the table catalog-side
- /admin/includes/extra_datafiles/database_tables.php if you need to use the table admin-side
- and inside your ScriptedInstaller.php, at the top of the class or at least before you use the constant

Configuration and Configuration_Group records

Many helper functions for configuration and configuration_group tables are shown in the example template below
Consult /includes/classes/PluginSupport/ScriptedInstallHelpers.php for more insight on the many helper functions available

Handling Errors

ERROR messages may be triggered via $this->errorContainer->addError(0, 'message to log', false, 'message to show to user');
If errors are added to errorContainer, then no matter how much progress was done, the errors will be displayed in the messageStack and the plugin version will NOT be marked as installed/upgraded.
It is best to return false; immediately after you trigger an error so that no further processing is done; else it will keep going and more errors will be collected.
When returning from executeInstall(), executeUninstall(), and executeUpgrade(), returning false or triggering an error will abort and not mark it installed. If no errors are set and true is returned, the plugin will be marked as installed (or if upgrading, the new version will be set as the active one).

Building Upgrades From Prior Versions

When building upgrades in ScriptedInstaller remember:

executeInstall() is for NEW installs, so should also include anything that an upgrade from previous version would do
executeUninstall() is to remove ALL changes for the plugin even after multiple upgrades (you might choose to NOT drop columns from db, to avoid user-error by accidental uninstall of the plugin)
executeUpgrade() should include ALL upgrades from ALL prior versions, since users can skip a version and therefore you need to cover all scenarios
While executeUpgrade($oldVersion) provides the version from which the upgrade is being done, it is better to code assuming none of any upgrades are done, by checking and performing all updates that would be needed to get any version up-to-date.

Informational Properties

A few properties exist to assist:

$this->pluginDir refers to the parent directory of the version you’re currently working in.
$this->pluginKey is the name of the plugin’s database key identifier.
$this->version is the version you’re currently “in”.
$this->oldVersion, which is only available when upgrading (otherwise null), indicates the version being upgraded from.

Example `ScriptedInstaller` Template

<?php
use Zencart\PluginSupport\ScriptedInstaller as ScriptedInstallBase;

class ScriptedInstaller extends ScriptedInstallBase
{
    /**
     * @return bool
     */
    protected function executeInstall()
    {
        // check whether the PHP version has the required features // using mb_strtolower just as an example here
        if (!function_exists('mb_strtolower')) {

            // trigger an error, which will cause the plugin to NOT get marked as installed, AND will display the error message
            $this->errorContainer->addError(
                0,
                'error message for the log file',
                false,
                'error message for display to the user (do not include sensitive details here)'
            );
            return false; // return now to abort the rest of the installation
        }

        // probably important to de-register the page key if you're converting an old plugin and using the same key name, so the new details are correct
        if (zen_page_key_exists('myAdminPageKey')) {
            zen_deregister_admin_pages(['myAdminPageKey']);
        }
        // check if the key exists first, because re-registering will trigger errors
        if (!zen_page_key_exists('myAdminPageKey')) {
            zen_register_admin_page('myAdminPageKey', language_key, main_page, page_params, menu_key, display_on_menuYN, sort_order_int);
        }

        // read a configuration key value
        $cKey = $this->getConfigurationKeyDetails('MY_MOD_SOMETHING');

        // create a new configuration group // NOTE: YOU PROBABLY DON'T NEED A NEW GROUP, but this is an easy way to create one
        $groupId = $this->addConfigurationGroup([
            'configuration_group_title' => 'Name up to 64 characters',
            'configuration_group_description' => 'Description up to 255 chars',
            //'sort_order' => 0, // int (will be made to match auto-increment id if not specified)
            //'visible' => 1, // 0 or 1, default '1'
        ]);

        // register a configuration key
        $this->addConfigurationKey('MY_MOD_MAX_ROWS_DISPLAY', [
            'configuration_title' => 'Display Maximum Rows',
            'configuration_value' => '20',
            'configuration_description' => 'Identify the maximum number of records to display.  (Default: <b>20</b>)',
            'configuration_group_id' => 10, // could use a variable to indicate a group ID here, such as $groupId from the above example
            //'sort_order' => 100, // INT(5) default NULL
            //'use_function', // TEXT default NULL
            //'set_function', // TEXT default NULL
            //'val_function', // TEXT default NULL
        ]);

        // DATABASE CHANGES
        /** @var sniffer $sniffer */
        global $sniffer;

        define('TABLE_MY_NEW_TABLE', DB_PREFIX . 'my_new_table');
        // NOTE: Be sure to ALSO add any database table constant defines to the admin and/or catalog extra_datafiles directory.

        // Add a Table:
        if ($sniffer->table_exists(TABLE_MY_NEW_TABLE, 'some_certain_field') !== true) {
            $sql = "CREATE TABLE IF NOT EXISTS " . TABLE_MY_NEW_TABLE . " (
                id INT NOT NULL auto_increment,
                name varchar(32) default NULL,
                PRIMARY KEY (id),
                KEY idx_mynewtable_name (name)
            )";
            $this->executeInstallerSql($sql);
        }

        // Add a Field:
        if (!$sniffer->field_exists(TABLE_MY_NEW_TABLE, 'some_certain_field')) {
            $sql = "ALTER TABLE " . TABLE_MY_NEW_TABLE . " ADD some_certain_field TINYINT NOT NULL DEFAULT 0";
            $this->executeInstallerSql($sql);
        }

        // Add an index:
        if (!$sniffer->indexExists(TABLE_MY_NEW_TABLE, 'idx_certain_field')) {
            $sql = "ALTER TABLE " . TABLE_MY_NEW_TABLE . " ADD INDEX idx_certain_field (some_certain_field)";
            $this->executeInstallerSql($sql);
        }

        return true; // or false on failure
    }

    /**
     * @return bool
     */
    protected function executeUninstall()
    {
        zen_deregister_admin_pages(['yourPageKeyNameHere']);
        $this->deleteConfigurationGroup($groupName, $boolWhetherToDeleteAllConfigKeysInThisGroup);
        $this->deleteConfigurationKeys($arrayOfKeyNames);

        return true; // or false on failure
    }

    /**
     * @return bool
     */
    protected function executeUpgrade($oldVersion)
    {
        // get a configuration group ID, and optionally create it if it doesn't already exist
        $groupId = $this->getOrCreateConfigGroupId('My Group Name', 'description');

        // maybe update the title or description of the group?
        $changed = $this->updateConfigurationGroup($groupId, [
            //'configuration_group_title' => 'something', // varchar(64) NOT NULL default ''
            //'configuration_group_description' => 'something', // varchar(255) NOT NULL default ''
            //'sort_order' => 0, // int(5) default NULL
            //'visible' => 1, // int(1) default '1'
        ]);

        // maybe update parts of a configuration table record, passing only the fields that need updating for this version
        $cID = $this->updateConfigurationKey('MY_MOD_SOMETHING', [
            // 'configuration_title' => 'something',
            // 'configuration_value' => 'something',
            // 'configuration_description' => 'something',
            // 'configuration_group_id' => $groupId,
            // 'sort_order' => 'some_int', // INT(5) default NULL
            // 'use_function' => '', // TEXT default NULL
            // 'set_function' => '', // TEXT default NULL
            // 'val_function' => '', // TEXT default NULL
        ]);

        return true; // or false on failure
    }
}

Dev: Encapsulated Plugin Class Autoloading

Mon, 01 Jan 0001 00:00:00 +0000

Class Autoloading

“Class Autoloading” means: “when I want to use a class, I simply attempt to instantiate it (ie: new Foo()) and PHP will automatically find the right file, load it (so I don’t have to include() or require() it manually), and then do the requested creation of an instance of it”. In most cases this is the best way.

Encapsulated plugins allow you to Autoload classes based on 2 scenarios.

Where the class follows PSR4 and the filename is the same as the class name (This is the best way). Naming should be CamelCased.
Where the filename is different to the class name (This should be rare).

PSR4 based classes

Formula for catalog:

place your class in the plugin’s [version]/catalog/includes/classes/ directory
name the class and its filename the same (ie: catalog/includes/classes/DrawPrettyGraph.php should contain a class named DrawPrettyGraph)
set the namespace: namespace Zencart\Plugins\Catalog\SalesGraphs; if the plugin’s name is Sales Graphs

Formula for admin: (basically, change “catalog” to “admin” for directory name and namespace)

place your class in the plugin’s [version]/admin/includes/classes/ directory
name the class and its filename the same (ie: admin/includes/classes/DrawPrettyGraph.php should contain a class named DrawPrettyGraph)
set the namespace: namespace Zencart\Plugins\Admin\SalesGraphs; if the plugin’s name is Sales Graphs

Example, for a plugin named `Sales Graphs`:

Filename

zc_plugins/SalesGraphs/vX.Y/admin/includes/classes/DrawPrettyGraph.php

<?php
namespace Zencart\Plugins\Admin\DisplayLogs;

class DrawPrettyGraph
{
    public function output()
    {
        echo 'Look at my pretty graph!';
    }
}

Invoking

now in any file you can invoke it directly: $myGraph = (new ZenCart\Plugins\Admin\SalesGraphs\DrawPrettyGraph)->output();

Or if you’d like to split the namespace out separately to make lines shorter, use 2 steps:

At the top of whatever file you wish to use it, add a line: use Zencart\Plugins\Admin\SalesGraphs\DrawPrettyGraph;
Then call it: $myGraph = (new DrawPrettyGraph)->output();

Custom class filenames

When the filename of a class does not match the class name, we need to do a bit more work.

The best situation is to avoid using custom class filenames, and to follow the standards provided above. Your IDE/editor will also be happier in such cases as well.

From the example above, if we had a class filename of class.some_weird_class_filename.php and the class name was myClass, then we would have to set up autoloading manually at tthe top of whatever file needs it. The following would need to be called after the line require 'includes/application_top.php';:

$psr4Autoloader->setClassFile('Zencart\Plugins\Admin\SalesGraphs\myClass', $filePathPluginAdmin['SalesGraphs'] . 'class.some_weird_class_filename.php');
$myClass = new Zencart\Plugins\Admin\SalesGraphs\myClass();
$myClass->output();

This would output 'Look at my pretty graph!'

Dev: Encapsulated Plugin SQL Installation

Mon, 01 Jan 0001 00:00:00 +0000

Plugins might need to create/alter database tables and/or insert/amend data in database tables.

The plugin installer allows two methods for doing this:

A class-based approach where each database alteration is done with PHP code. This approach also allows for upgrading between versions when you release updates.
Using .sql files containing just SQL statements. This should only be used in VERY simple scenarios, where upgrades will never be needed.

SQL Installer Classes

If you have more complex needs when creating schemas or seeding the database, instead of using a plain SQL install file as above, you can use a class based method, by extending ScriptedInstallBase as /Installer/ScriptedInstaller.php in your plugin. See Installer Classes for details.

IF YOUR PLUGIN PROVIDES UPGRADES WHICH NEED DATABASE CHANGES, then you MUST use the Installer Classes, since there is no way to offer plain .sql file upgrades.

An example is provided in the DisplayLogs plugin, in zc_plugins/DisplayLogs/[version]/Installer/ScriptedInstaller.php.

Briefly, three key methods that must be implemented in a class which extends ScriptedInstallBase are executeInstall and executeUninstall and executeUpgrade, which run the installation, de-installation and upgrade logic, respectively. They should return true on success, and false on failure. They can set $this->errorContainer->addError($severity=0, $logMessage, $booleanShowLogToUser, $userMessage) if any errors need to be logged and/or shown to the user.

Plain SQL Files

If your needs are VERY simple, and upgrades will never be necessary, you could use just a plain .sql file:

Create a plain SQL file called install.sql with the SQL statements you need for installation. Be sure to make your installation robust in the face of prior partial or failed installs (e.g. use IF NOT EXISTS, INSERT IGNORE and so forth).

CREATE TABLE IF NOT EXISTS reward_master (
                           rewards_products_id INT( 11 ) NOT NULL AUTO_INCREMENT PRIMARY KEY,
                           scope INT( 1 ) NOT NULL DEFAULT '0',
                           scope_id INT( 11 ) NOT NULL DEFAULT '0',
                           point_ratio DOUBLE( 15, 4 ) NOT NULL DEFAULT '1',
                           bonus_points DOUBLE( 15, 4 ) NULL,
                           redeem_ratio DOUBLE( 15, 4 ) NULL,
                           redeem_points DOUBLE( 15, 4 ) NULL,
                           UNIQUE unique_id ( scope , scope_id ));

INSERT IGNORE INTO reward_master
(rewards_products_id ,scope ,scope_id ,point_ratio ,bonus_points, redeem_ratio, redeem_points)
VALUES (NULL , '0', '0', '1.0000', NULL, 0.01, NULL);

The sql file should reside in

zc_plugins
- PluginName
  - v1.0.0
    - Installer
      - install.sql
      - uninstall.sql

Warning With this install.sql approach, there is no way to safely roll back any installer SQL if an error occurs.

Note that an uninstall script (called uninstall.sql) may be placed in the same folder.

Currently Supported SQL Commands

DROP TABLE IF EXISTS <table name>;
DROP TABLE <table name>;
CREATE TABLE IF NOT EXISTS <table name> <additional sql>;
CREATE TABLE <table name> <additional sql>;
TRUNCATE TABLE <table name>;
REPLACE INTO <table name> <additional sql>;
INSERT INTO <table name> <additional sql>;
INSERT IGNORE INTO <table name> ;
ALTER TABLE <table name> <additional sql>;
RENAME TABLE <table name> TO <table name>;
UPDATE <table name> <additional sql>;
DELETE FROM <table name> <additional sql>;
DROP INDEX <index name> ON <table name>;
CREATE INDEX <index name> ON <table name> <additional sql>;
SELECT <fields> FROM <table name> <additional sql>;
SELECT <fields> FROM <table name> <join type> JOIN <table name> <additional sql>

Where:

<table name> is the name of the table(s) which may require a suffix adding
<additional sql> is additional valid sql for the statement. It must not contain any table names that may require prefixing
<index name> is the name of the index to be created/dropped
<join type> is the type INNER, OUTER, etc.

Notes:

There must be exactly one space before <table name>.
The statement before the first < must be single spaced.
There can be multiple JOIN statements in a select.
Every statement must end with a semi-colon (;).
Sub selects are not available.

Dev: Converting a Plugin to the Encapsulated Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Note For simplicity, files like license.txt, README.txt and docs are omitted; no changes are made to those files, which are not deployed.

Converting an older plugin to use the encapsulated architecture can be done following these steps:

1. Create the plugin’s file hierarchy.

As a general rule, this just means moving the files you currently have in the plugin’s top level folder under a new folder with the name Plugin Name/Version.

For example, the Mod List files, prior to conversion, were:

./admin/includes/languages/english/extra_definitions/mod_list.php
./admin/includes/languages/english/mod_list.php
./admin/includes/extra_configures/mod_list.php
./admin/mod_list.php

Note On a live system the admin folder will have been renamed.

These become:

./zc_plugins/ModList/1.4.0/admin/includes/languages/english/extra_definitions/mod_list.php
./zc_plugins/ModList/1.4.0/admin/includes/languages/english/mod_list.php
./zc_plugins/ModList/1.4.0/admin/includes/extra_configures/mod_list.php
./zc_plugins/ModList/1.4.0/admin/mod_list.php

Note It is not necessary to rename admin in the plugin directory hierarchy

For Zen Cart versions 2.1.0 and later, only array-based language files are supported for encapsulated plugins. Using the example above, the admin folder’s files will be

./zc_plugins/ModList/1.4.0/admin/includes/languages/english/extra_definitions/lang.mod_list.php
./zc_plugins/ModList/1.4.0/admin/includes/languages/english/lang.mod_list.php
./zc_plugins/ModList/1.4.0/admin/includes/extra_configures/mod_list.php
./zc_plugins/ModList/1.4.0/admin/mod_list.php

2. Add the Manifest

Create a manifest file. In our example, this will be placed in

./zc_plugins/ModList/1.4.0/manifest.php

3. Add the Plugin Installer script

Create an installer script.

In our example, this will be placed in

./zc_plugins/ModList/1.4.0/Installer/PluginInstaller.php

4. (optional) Create install and uninstall files

If the installer script you created above did not do the SQL operations required by the plugin, you can use plain SQL files.

In our example, these will be placed in

./zc_plugins/ModList/1.4.0/Installer/uninstall.sql
./zc_plugins/ModList/1.4.0/Installer/install.sql

5. Remove old files and update documentation

Once you have put your the admin, includes, etc. folders under zc_plugins, do not duplicate them at the top level for older versions of Zen Cart. Instead, update the README file for your plugin with guidance like:

If you are running a  Zen Cart installation older than 1.5.7, do not copy in the `zc_plugins` folder.  Instead, 
go to the `zc_plugins/YOURPLUGIN/VERSION/` folder and copy the `admin` and `includes` folders to your shopping cart (after renaming the `admin` folder.)

Alternately, you may mark your plugin as “1.5.7 (and above) only.”

6. Final Result

Now the file hierarchy looks like this:

./zc_plugins/ModList/1.4.1/admin/includes/languages/english/extra_definitions/mod_list.php
./zc_plugins/ModList/1.4.1/admin/includes/languages/english/mod_list.php
./zc_plugins/ModList/1.4.1/admin/includes/extra_configures/mod_list.php
./zc_plugins/ModList/1.4.1/admin/mod_list.php
./zc_plugins/ModList/1.4.1/manifest.php
./zc_plugins/ModList/1.4.1/Installer/uninstall.sql
./zc_plugins/ModList/1.4.1/Installer/PluginInstaller.php
./zc_plugins/ModList/1.4.1/Installer/install.sql

Things to watch for in the conversion

Scope of variables in `extra_configures` and `extra_datafiles`

In the encapsulated plugin architecture, the files in extra_configures and extra_datafiles are run in the context of the FileSystem class, and therefore any variables created will be scoped into that class and not the global scope.

This means if you have a file that was in admin/includes/extra_configures/my_plugin.php which created a variable (say, $my_list), this variable will not be available to the plugin anymore.

Some options for overcoming this are:

Move the logic to a page specific init file.
Make the variables into defined constants (which by definition have global scope).

Explicit `include` or `require` of storefront files

TBD

Dev: Upgrading Encapsulated Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Once you have created an encapsulated plugin, upgrading it is mostly a matter of creating a new version number under the plugin name, and then making your changes.

So if the old version was structured like this:

zc_plugins/MyPlugin/1.0.0

you can duplicate this to

zc_plugins/MyPlugin/1.0.1

and make your changes.

If you’re using GitHub for your plugin, then commit the new directory to your repository before making new changes for the new version.

Once you release, end-users will upload the new version-number directory to their server and run through the upgrade process using Admin > Modules > Plugin Manager.

Note: An Installer/install.sql file is ONLY run on NEW installs, not upgrades. So if your plugin makes any database changes, be sure to update:

Installer/ScriptedInstaller.php to use executeUpgrade() to perform any queries (if any) required by the new version. (This is the only way to apply db updates in an upgrade.)
Installer/install.sql (IF used) to include (in addition to any prior queries) any new things added by your upgraded version.
Installer/uninstall.sql (IF used) to include all (in addition to any prior) removals required to fully remove.

TO BE CLEAR: The ScriptedInstaller.php (and install.sql and uninstall.sql if they exist (they’re not required)) MUST be capable of handling BOTH fresh installs AND upgrades across ALL versions that your plugin supports. THERE IS NO “INCREMENTAL” UPGRADE SUPPORT BASED ON FILENAMES OR VERSION NUMBERS. Any “incremental” upgrade steps would be coded into your ScriptedInstaller.php script, taking care of doing all requisite dependency checks there.

Zen Cart Documentation – Encapsulated Plugins

Dev: Encapsulated Plugin Directory Structure

Directory Structure

Dev: Encapsulated Plugin Manifest Files

Manifest Files

pluginVersion

pluginName

pluginDescription

pluginAuthor

PluginId

changelog

github_repo

zcVersions

pluginGroups

Dev: Encapsulated Plugin Installer Language Files

Plugin Installer Language Files

Dev: Encapsulated Plugin Installer Classes

Installer Classes

Important Notes for coding in the context of a ScriptedInstaller class

Database Querying

Database DEFINES

Configuration and Configuration_Group records

Handling Errors

Building Upgrades From Prior Versions

Informational Properties

Example ScriptedInstaller Template

Dev: Encapsulated Plugin Class Autoloading

Class Autoloading

PSR4 based classes

Example, for a plugin named Sales Graphs:

Filename

Contents

Invoking

Custom class filenames

Dev: Encapsulated Plugin SQL Installation

SQL Installer Classes

Plain SQL Files

Currently Supported SQL Commands

Dev: Converting a Plugin to the Encapsulated Architecture

1. Create the plugin’s file hierarchy.

2. Add the Manifest

3. Add the Plugin Installer script

4. (optional) Create install and uninstall files

5. Remove old files and update documentation

6. Final Result

Things to watch for in the conversion

Scope of variables in extra_configures and extra_datafiles

Explicit include or require of storefront files

Dev: Upgrading Encapsulated Plugins

Important Notes for coding in the context of a `ScriptedInstaller` class

Example `ScriptedInstaller` Template

Example, for a plugin named `Sales Graphs`:

Scope of variables in `extra_configures` and `extra_datafiles`

Explicit `include` or `require` of storefront files