Zencart Plugin Framework – Day 3 – Understanding plugin’s structure

Today is a special day for the devs, I will explain the structure of a standard ZePLUF plugin so you can easily develop your own plugin. You will find how easy and quick it is to create anything you need with this new framework.

If possible, all plugin files should be placed under plugins/yourPluginName to avoid conflicts with other plugins and to keep things organized. Please make sure that you name your plugin folder using the camelCase format.

Below, you will find the list of possible folders and files in a standard plugin:

|– config all the configs of the plugin should be here
|– lib all the logic code of the plugin should stay here
|—- classloader.ini this file is optional and will be explained later
|– content
|—- resources this is where all the images/css/js files stay
|—- views this is where all the template files stay
|– vendor if the plugins use 3rd party scripts, they all can be placed here
|– pluginName.php this file is optional and will be explained later
|– plugin.xml
|– translations this folder should contain all the language files

config

All the configuration files should be stored in this folder.

1. All .php files will be automatically loaded in alphabet order. Note that all these files are loaded inside a class, so if you want any variables to be accessed globally, you need to declare
2. settings.yaml: if the plugin contains this file, its content will be loaded and parsed automatically (given that the plugin is enabled). The content in here can then be accessed via the settings instance:
   plugins\riPlugin\Plugin::get('riPlugin.Settings')->get('pluginName')

   I will have a special post to cover this because there are many more tricks you can do with it

3. services.xml: if the plugin contains this file, it will be used to register service to the service container. If this file does not exist, then ZePLUF will automatically register all .php files inside the lib folder to the service container using the default settings (so all services will be registered as containers, not prototypes)
   This file is also quite important if you want to extend or override a plugin’s class as you can simply make changes to the class path inside this file (I’m not going to cover in details how Symfony’s service container works here as Symfony.com already does a pretty good job of that)

lib

This folder should contain all the logic files of the plugin which include models/controllers and whatever logic code you should need. We do recommend that you namespace all your classes/functions and such so that you can avoid conflicts with other plugins and with Zencart’s core.

One thing to note is that all the files inside this folder are not loaded by default, they are loaded on demand using ZenMagick’s classloader. By default, your namespace must follow your directory structure, so for example if your plugin’s name is myPlugin then within this lib folder you must use the namespace

Luckily, if you are like me, and you don’t like having long namespaces, you can easily cut short by creating a file named classloader.ini inside this lib folder and define all your namespaces here (view the above link for some examples)

If you use subfolders here, your namespaces must follow the directory structure or you MUST also define them in classloader.ini.

content

Basically all templates and resources files should here. Since there are lots of things going in this folder regarding the template rendering, resources loading and overriding I will cover it in a separate post.

vendor

If you use 3rd party developed packages you should place them all here. You can also have a classloader.php in this folder to define your namespace(s).

pluginName.php

This file, if exists, will be automatically loaded. This file is also expected to have a method named init which does not take any parameter and will be called once the plugin is first loaded.

If you need to use Zencart’s auto loader, you can define it within this method, there is no need to put a file into includes/auto_loaders/ which will just create another garbage file for users later once they want to remove the plugin. Another nice thing is that this is loaded only when the the plugin is enabled.
Below is an example take from one of our plugins:

plugin.xml

This file contains the plugin’s information such as: developer(s), version, release date, update url, dependencies, changelog and such…

translations

ZePLUF use gettext to translate text for several reasons:

1. Very easy to use, big time saver
2. Readily available editors such as poedit
3. Less error prone compared to Zencart’s php constants

There will be a post on our blog that cover this in much more details, stay tuned.