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.

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.

    • Compose the ID based on the chosen extension name (see below). Note that the extension ID is used as a part of its URL in the catalog, therefore, unique meaningful words can provide for more effective SEO.
    • All words must be in lower case.
    • Separate words with dashes.

  • name

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

    • Choose a name shorter than 60 characters. Preferably, 25 characters or less, to make sure the name fits whole into a promotion block title on the web site.
    • The name must be in English. Other languages are recommended, but optional.
    • Avoid using words that do not add unique meaning, for example: extension, plugin, Plesk, installer, integration, etc.

  • 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
    Beta beta
    Client Tools client_tool
    Clouds clouds
    CRM crm
    DNS dns
    Examples example
    Feature Packs feature_pack
    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
    Website Performance performance

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

  • buy_url (optional)

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

    The default value for buy_url is the following URL: https://go.plesk.com/buy-plesk-ext/<id>, where id is your extension’s identifier – see id above.

  • plesk_min_version (optional)

    The earliest version of Plesk which supports the extension.

    The choice for the minimal supported Plesk version is usually dictated by the version of the Plesk SDK used.

    Note: The completed extension must be thoroughly tested on all Plesk product versions that are supported to make sure it works correctly and is not influenced by differences in engines and SDK versions.

  • plesk_max_version (optional)

    The latest version of Plesk which supports the extension.

    This parameter is useful in cases when there are known or suspected issues with versions of Plesk that are more recent than the specified. For example, when a new version of PHP will be adopted, and it will break something.

  • os (optional)

    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.

DESCRIPTION.md is located in the extension’s root directory. The language used in DESCRIPTION.md must be English.

Localizing Extension’s Description

Make sure more people notice your extension by translating your extension’s description into various languages.

Note: This option is available starting with Plesk 17.8.

Separate description files are created for translated description.

  • Description files are using the Markdown format (.md).
  • Description files are stored in the /_meta/descriptions/ directory.
  • Multiple description files may be created, one for each different locale. An appropriate file is chosen based on the active Plesk locale.
  • The name of a description file matches its locale ID: en-US.md, de-DE.md, ru-RU.md, etc.

Based on the locale used by Plesk, the description from the appropriate description file is displayed. If the appropriate file is unavailable in the descriptions/ directory, the description from the DESCRIPTION.md file will be displayed.

Here is a sample description 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.

image 78985

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.