Extension Structure

Plesk extension is a ZIP archive containing a specifically-organized directory structure and a file with meta information describing the software. 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 supported by Plesk for both Linux and Windows.

In this chapter:

File Structure

meta.xml

DESCRIPTION.md

CHANGES.md

Icons and Screenshots (_meta/)

Conflict Resolution on Upgrade

Removal Procedure

 

File Structure

A typical ZIP archive with an extension has the following structure of files and directories:

example-extension.zip
 |
 +-meta.xml
 +-DESCRIPTION.md
 +-CHANGES.md
 +-/htdocs/
   |
   +-index.php
   +-public/
   +-...
 +-/plib/
   |  
   +--controllers
   |       IndexController.php
   |  
   +---scripts
   |       post-install.php
   |       pre-install.php
   |       pre-uninstall.php
   |
   +---views
   |   \---scripts
   |       \---index
   |               index.phtml
   |
   +-/hooks/
     |
     +-...
   +-/library/
     |
     +-...
    +-/sbin/
   |
   +-...
 +-/var/
   |
   +-...
 +-/_meta/
   |
   +-...

The description of the most important files and directories is as follows:

meta.xml - The XML-formatted description of the extension. During the extension installation, this 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. See the detailed description of this file structure.

DESCRIPTION.md - The extended description of the extension. The description must be written in markdown. See the detailed description for more information.

CHANGES.md - The changelog of the extension. The changelog must be written in markdown. See the detailed description for more information.

/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 the /PRODUCT_ROOT_DIR/admin/htdocs/modules/EXTENSION_ID/ directory.

/htdocs/public - Contains the scripts that do not require authorization (bypassing controllers). For example if your extension exposes its own API.

/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 the PRODUCT_ROOT_D/admin/plib/modules/MODULE_ID/ directory.

/plib/conrollers - This directory should contain the extension's controllers (for details, read the description of MVC pattern). This directory is automatically generated when the extension is created and contains the default controller for requests processing, IndexController.php.

/plib/library - This directory should contain files with extension logic implementation. Classes from this directory are loaded automatically. For more details read Class Naming Conventions.

/plib/scripts - This directory should contain scripts that the system runs immediately before the extension installation, after the installation, or before the extension 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 and should not do any modifications on the server. 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 and makes all changes required for the extension to work. For example, using this script, we can create databases or prepare the necessary directory structure.

pre-uninstall.php - runs before the removal of an extension. This script helps to remove files used by the extension, such as databases, templates, and user content. Also, before the removal, extension should revert all changes done on the server (for example, it the extension makes changes to the services' configuration files, these changes should be reverted).

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.

Also, the /plib/scripts directory can be used to store your custom scripts. For example, many extensions' authors put the scripts which are later run via scheduled tasks here.

/plib/views - This directory contains the extension's views that define the presentation of the data to the user (read more about views here). This directory is automatically generated when the extension is created and contains the default view file scripts/index/index.phtml.

/plib/hooks - This directory should contain Plesk hooks (integration points, such as custom buttons or authorization).

/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.

/_meta – This directory contains the extension's icons and screenshots.

 

meta.xml

Here is a sample meta.xml file describing an extension called "Test extension".

<?xml version="1.0"?>
<module>
  <id>test-extension</id>
  <name>Test extension</name>
  <description>Add description here...</description>
  <category>example</category>
  <category>help</category>
  <buy_url>http://example.com/</buy_url>
  <version>1.0</version>
  <release>1</release>
  <vendor>Plesk</vendor>
  <url>http://your-company-web-site</url>
  <support_url>http://your-company-web-site/support</support_url>
  <plesk_min_version>12.5.0</plesk_min_version>
</module>

The description of the available elements within the module node is as follows:

  • id

    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.

  • name

    The name the administrators will see in the extensions list in Plesk (Server Management > Extensions) after installing the extension.

  • description

    The extension description the administrators will see in the extensions list in Plesk (Server Management > Extensions) after installing the extension.

  • category

    The category or categories to which the extension belongs. Users can sort extensions available in the Extension Catalog by category, so assigning your extension to the correct category or categories will increase the amount of exposure it gets. You can specify more than one category for your extension, but each one must be on a new line and marked by its own set of tags. Note that when assigning a category to your extension, you need to specify the category code in the meta.xml file, not the human readable category name. Refer to the table below for a complete list of available categories and their codes.

Category name (human readable) Category code (goes in the meta.xml file)

Appearance

appearance

Authentication

auth

Backup

backup

Client Tools

client_tool

DNS

dns

Examples

example

Fun

fun

Help & Troubleshooting

help

Mail

mail

Monitoring

monitoring

Security

security

Server Tools

server_tool

SEO & Social Media

social

Web Apps & Site Editing

web_app

Web Development

developer

Web Servers

webserver

  • version

    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.

  • release

    The extension 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.

  • vendor

    The vendor name.

  • url

    The extension's vendor site.

  • support_url

    The link to the extension vendor's support page. Administrators can see it on the extension's page in the Extension Catalog. Having a support URL is mandatory for paid extensions.

  • help_url

    The link to the extension documentation. Administrators can see it in the extensions list.

  • (Optional) buy_url

    The URL of the website or online store where a license for the extension can be purchased. An extension can require a license for some or all of its functions to operate. Specifying the URL will add a "Buy Now" button next to the extension's name in the Extension Catalog. Clicking the button will open the specified URL in a browser window. Note that paid extensions must feature a link to the extension vendor's support page - see support_url below.

  • (Optional) plesk_min_version

    The minimal version of Plesk which supports the extension.

  • (Optional) plesk_max_version

    The maximum version of Plesk which supports the extension.

  • (Optional) os

    Operating systems supported by the extension. Possible values: unix (for Linux) and win (for Windows) .

Localization of the nodes

To translate a node, duplicate it and append the xml:lang attribute with a 4-letter language code conforming to RFC1766. For example:

<description>Easily add customers and websites</description>
<description  xml:lang="de-DE">Einfache Neukundenerfassung & simple Website-Erstellung</description>
 

DESCRIPTION.md

Before a Plesk administrator downloads an extension, they want to see a detailed description of the extension's functionality and limitations. This is especially true when there are multiple extensions from different vendors performing the same task or filling the same niche.

Use the DESCRIPTION.md file to inform Plesk administrators about the functions your extension has and the tasks it can help perform. If your extension has any limitations, or requires a paid license to unlock some or all of its functionality, be sure to add this information to the file.

The information in the DESCRIPTION.md file is displayed when a Plesk administrator clicks an extension in the Extension Catalog. If the file is missing, the short description defined by the description element in the meta.xml file is displayed instead.

Here is a sample DESCRIPTION.md file for an extension released by Plesk. Feel free to use it for reference.

To help you meet the evolving requirements of your customers, Plesk Onyx comes with Docker support. Here is what you can do with it:

 - Have on-demand access to a wide range of modern technologies, such as redis, mongodb, memcached, and many more.
 - Choose from a catalog of available images, or upload a custom image.
 - Deploy and manage Docker containers straight from the Plesk interface.
 - Install Docker containers locally, or to a remote node registered in Plesk.

[Learn More](https://docs.plesk.com/en-US/current/administrator-guide/web-hosting/using-docker.75823/)

**This extension is **FREE** with Plesk. You can also get remote node support for only $5.00 a month.**
 

CHANGES.md

When a Plesk administrator downloads an extension, they want to see what changes happened in the recent extension updates. They may also want to see if a specific issue has been addressed.

Use the CHANGES.md file to inform Plesk administrators about the changes you make to the extension, including but not limited to:

  • Design changes.
  • New and improved features.
  • Fixed bugs and resolved issues.
  • Changes to the pricing policy.

The information in the CHANGES.md file is displayed when a Plesk administrator clicks an extension in the Extension Catalog.

Here is a sample CHANGES.md file for an extension released by Plesk. Feel free to use it for reference.

# 1.3.0

* [*] Docker is supported on Virtuozzo 7 and separate Virtuozzo Application templates are now available for Plesk Docker.

# 1.2

* [*] Docker extension installation hung on Linode servers with Ubuntu 16.04. (EXTDOCKER-25)

# 1.1

* [-] Incorrect hint was displayed in the Environmental variable value field in a container's settings. (EXTDOCKER-19)
* [-] In the case of using a remote Docker, no hint was displayed for the SSL icon on the "Tools & Settings > Docker" page. (EXTDOCKER-8)
* [-] HTML tags were displayed in the Plesk search results for the found Docker Catalog location. (EXTDOCKER-6)
* [-] When a Docker proxy rule was deleted from the domain's Proxy Rules page and from Websites & Domains, different confirmation dialogs were displayed. (EXTDOCKER-2)
 

Icons and Screenshots (_meta/)

The directory /_meta/ inside the extension’s root directory contains the extension’s icons and screenshots.

Icons

An extension’s icons are displayed in different areas of the Plesk interface. Please adhere to the following guidelines when designing and creating an icon for your extension:

  1. The image must occupy maximum space of the icon’s canvas.
  2. The image must be centered on the icon’s canvas.
  3. The icon’s background must be transparent.

1

The icons must be PNG file format, and available in the following sizes.

Size Location

32 px * 32 px

_meta/icons/32x32.png

64 px * 64 px

_meta/icons/64x64.png

128 px * 128 px

_meta/icons/128x128.png

Only for paid extensions: 160 px * 160 px

_meta/icons/160x160.png

Screenshots

Screenshots accompany the extension’s description on the extension overview page. They must be PNG file format. There may be up to three screenshots.

Note: At least one screenshot must be available.

Size Location

1024 px * 768 px

_meta/screenshots/1.png (required)

_meta/screenshots/2.png (optional)

_meta/screenshots/3.png (optional)

 

Conflict Resolution on Upgrade

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 a file already exists, it is overwritten.
  • If a directory already exists, files inside it are overwritten.
  • Files that were present in the previous version of an extension, but are missing in the newer version, are removed.

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.

 

Removal Procedure

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.

 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.