Starting from Plesk 11, developers can pack extensions in a cross-platform format, in a ZIP archive with a metadata file placed in the root directory. Such extensions are also supported by Plesk for Windows.
Plesk for Linux is backwards-compatible with previously used extension (module) packages in RPM and Deb package formats. However, we highly recommend that you pack and distribute extensions in ZIP archives.
A typical ZIP archive with an extension has the following structure of files and directories:
example-extension.zip
|
+-meta.xml
+-/htdocs/
|
+-index.php
+-public/
+-...
+-/plib/
|
+-/hooks/
|
+-...
+-/library/
|
+-EventListener.php
+-...
+-/scripts/
|
+-pre-install.php
+-post-install.php
+-pre-uninstall.php
+-...
+-/sbin/
|
+-...
+-/var/
|
+-...
The description of the most important files and directories is as follows:
meta.xml
The XML-formatted description of an extension. During the extension installation, the file is extracted to
PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/meta.xml
,
where PRODUCT_ROOT_D
is /usr/local/psa
on Linux systems and %plesk_dir%
on Windows systems.
/htdocs
All entry points of an extension, CSS, Javascript, and graphics files should be placed in this directory. During installation, the contents of this directory are extracted directly into /PRODUCT_ROOT_DIR/admin/htdocs/modules/EXTENSION_ID/
.
/htdocs/public
Includes scripts that do not require authorization (bypassing controllers).
/plib
This directory should contain PHP classes that are responsible for the logic of an extension. During installation, the contents of this directory are extracted directly into PRODUCT_ROOT_D/admin/plib/modules/MODULE_ID/
.
/plib/hooks
This directory should contain Plesk's hooks.
/plib/scripts
This directory should contain scripts that the system runs instantly before the extension installation, after the installation, or after the removal.
The following scripts are available:
pre-install.php
- runs before extension files are copied. This script makes sure that the system meets the extension’s requirements. Extension files are not available at this stage.post-install.php
- runs after extension files are copied. This script prepares the system for the installation of the extension. Using this script, you can create databases or prepare the necessary directory structure.pre-uninstall.php
- runs before the removal of an extension. This script helps remove files used by the extension - databases, templates, user content.If a script exits with a non-zero status, the current action is interrupted with an error. The script output will be displayed to the Plesk administrator as an error message.
/sbin/
This directory should contain scripts that require elevated privileges during execution.
/var
The directory for storing data used by the extension, for example, SQLite databases.
During the extension installation, the contents of this directory are extracted to PRODUCT_ROOT_D/var/modules/EXTENSION_ID/
. This directory is not removed when upgrading an extension.
A file that describes an extension, meta.xml
, can look as follows:
<?xml version="1.0"?>
<module>
<id>test-extension</id>
<name>Test extension</name>
<description>Add description here...</description>
<version>1.0</version>
<release>1</release>
<vendor>Plesk</vendor>
<url>http://your-company-web-site</url>
<plesk_min_version>12.5.0</plesk_min_version>
</module>
The description of the available elements within the module node is as follows:
The identifier of an extension. It is used as a part of the URL of the extension root. For example, if an extension ID is sample-extension, the extension is available at http://<plesk-host-name>:<port>/modules/sample-extension.
The name the administrators will see in the extensions list in Plesk (Server Management > Extensions) after installing the extension.
The extension description the administrators will see in the extensions list in Plesk (Server Management > Extensions) after installing the extension.
The extension version. Can be an arbitrary string, though we recommend using the following format: X.Y (where X and Y are numbers), e.g. 1.0. Administrators can see it in the extensions list.
The module package version. It corresponds to the package changes that do not affect the code of the extension, but change something in the package itself (such as the post-install script). Can be an arbitrary string, though we recommend using the following format: X (where X is a number), e.g. 1. Administrators can see it in the extensions list.
The vendor name.
The extension's vendor site.
The minimal version of Plesk which supports the extension.
The maximum version of Plesk which supports the extension.
The link to the extension documentation. Administrators can see it in the extensions list.
Operating systems supported by the extension. Possible values: unix and win.
Use this element if your extension is encoded by ionCube. Possible values: ioncube.
When administrators upload a new version of an extension to Plesk, the possible conflicts between the existing and new files are resolved in the following way.
If one of these conflict resolution rules is not satisfied (for example, an existing file is blocked and cannot be overwritten), the upgrade procedure fails.
The following files are removed when an extension is removed:
PRODUCT_ROOT_D/admin/htdocs/modules/EXTENSION_ID/
PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/
PRODUCT_ROOT_D/var/modules/EXTENSION_ID/
Here PRODUCT_ROOT_D
is /usr/local/psa
on Linux systems and %plesk_dir%
on Windows systems.
If an extension file cannot be removed, the removal procedure fails.
All files that are used by an extension should be removed by the pre-uninstall
script.
You can create the file structure necessary for an extension in one step, using the following command-line call:
plesk bin extension --create <EXTENSION_NAME>
Read more about the utility in the following documents:
With this utility, you can create a ready-for-distribution extension (by creating a ZIP archive of the extension file structure). The following call prepares the archive in the current directory:
plesk bin extension -p my-project
If you need to create an archive in a different directory, supply the utility call with the -destination /path/to/directory/ option.
The system allows to call your classes from almost all places of your code without preliminary requiring them. For this, you should properly name the classes and put the file which contains the class into a particular directory. This simplification is not necessary in most cases, it just makes your code more compact, but sometimes you are required to adhere to the naming conventions. For example, if you wish to add a dashboard widget, you are required follow the conventions because the system needs to automatically discover and load this class.
The naming conventions are as follows:
Example: my-site is transformed to MySite.
/plib/library/
directory.For example, if a class is in /plib/library/website/Promo.php
and the extension ID is my-site, the class name must be:
Modules_MySite_Website_Promo.
Zend uses a similar approach for auto-loading classes. Read more about it in http://framework.zend.com/manual/1.11/en/learning.autoloading.design.html .
The auto-loading of classes does not work in the /htdocs/public/
directory. If you need this feature, start the auto-loading manually by adding the following code to the beginning of a file:
require_once('sdk.php');