Структура лицензий

Plesk 11 поддерживает новый формат лицензий – архив ZIP с файлом метаданных в корневой папке. Формат, который использовался раньше, также поддерживается для совместимости с модулями Linux (это прежнее название расширений Plesk), но мы настоятельно рекомендуем использовать новый формат при создании новых расширений.

В этой главе:

Структура файлов

meta.xml

DESCRIPTION.md

CHANGES.md

Значки и снимки экрана (_meta/)

Разрешение конфликтов при обновлении

Процедура удаления

Создание и упаковка расширений

 

Структура файлов

Типичное расширение имеет следующую файловую структуру:

example-extension.zip
 |
 +-meta.xml
 +-/htdocs/
 |
 +-index.php
 +-public/
 +-...
 +-/plib/
 |
 +-/library/
 |
 +-EventListener.php
 +-...
 +-/scripts/
 |
 +-pre-install.php
 +-post-install.php
 +-pre-uninstall.php
 +-...
 +-/var/
 |
 +-...

Ниже описаны наиболее важные файлы и папки:

  • meta.xml

    Описание расширения в XML-формате. Во время установки расширения файл извлекается в

    PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/meta.xml,

    где PRODUCT_ROOT_D – это /usr/local/psa в Linux и %plesk_dir% в Windows.

  • /htdocs

    Первая точка входа расширения. Поместите в эту папку типы CSS и файлы Javascript. Во время установки расширения содержимое этой папки извлекается в /PRODUCT_ROOT_DIR/admin/htdocs/modules/EXTENSION_ID/.

  • /htdocs/public

    Содержит скрипты, которые не требуют авторизации (обходные контроллеры).

  • /plib

    Папка, которая должна содержать классы PHP, которые отвечают за бизнес-логику расширения.

  • /plib/scripts

    Папка, которая должна содержать скрипты, которые система запускает непосредственно перед установкой, после установки или после удаления расширения.

    Доступны следующие скрипты:

    • pre-install.php – запускается перед копированием файлов расширения. Этот скрипт помогает подготовить систему к установке расширения. Используя этот скрипт, вы можете создать базы данных или подготовить необходимую структуру папок.
    • post-install.php – запускается после копирования файлов расширения.
    • pre-uninstall.php – запускается перед удалением расширения. Этот скрипт помогает удалить файлы, которые использовались расширением – базы данных, шаблоны, пользовательское содержимое.

    Если скрипт прекращает работу с ненулевым статусом, выполняемое действие прерывается с ошибкой. В выводе скрипта администратор Plesk увидит сообщение об ошибке.

  • /var

    Папка для хранения данных, используемых расширением, например, баз данных SQLite.

    Во время установки расширения содержимое этой папки извлекается в PRODUCT_ROOT_D/var/modules/EXTENSION_ID/. Эта папка не удаляется при обновлении расширения.

 

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

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.

  • 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

Прежде чем загрузить расширение, администраторы Plesk хотят видеть подробное описание его функциональности и ограничений. Это особенно актуально в случае, когда есть несколько расширений от различных поставщиков, выполняющие одну и ту же задачу или занимающие одну и ту же нишу.

Используйте файл DESCRIPTION.md, чтобы сообщить администраторам Plesk о том, какие функции имеет ваше расширение, и какие задачи оно помогает выполнять. Если расширение имеет ограничения или требует покупки лицензии для разблокировки некоторых или всех своих функций, удостоверьтесь, что информация об этом добавлена в файл.

Информация из файла DESCRIPTION.md отображается в тот момент, когда администратор Plesk нажимает имя расширения в каталоге расширений. Если этот файл отсутствует, вместо его содержимого отображается короткое описание из элемента description файла meta.xml.

Вот пример содержимого файла DESCRIPTION.md для расширения, выпущенного Plesk. Вы можете использовать его для справки.

Чтобы помочь вам соответствовать постоянно растущим требованиям ваших клиентов, Plesk Onyx предлагает поддержку Docker. Вот что вы можете делать с его помощью:

 - Получать по необходимости доступ к широкому спектру современных технологий, таких как redis, mongodb, memcached и многие другие.
 - Выбирать доступные образы из каталога или загружать персональные образы.
 - Развертывать контейнеры Docker непосредственно из интерфейса Plesk.
 - Устанавливать контейнеры Docker локально или на удаленном сервере, зарегистрированном в Plesk.

[Узнайте больше](https://docs.plesk.com/en-US/current/administrator-guide/web-hosting/using-docker.75823/)

**Это расширение предоставляется **БЕСПЛАТНО** с Plesk. Вы также можете получить поддержку удаленного сервера всего за $5.00 в месяц.**
 

CHANGES.md

Прежде чем загрузить расширение, администраторы Plesk хотят видеть, какие изменения добавились в последних обновлениях расширения. Они также могут захотеть увидеть информацию об устранении той или иной неисправности.

Используйте файл CHANGES.md, чтобы сообщить администраторам Plesk о том, какие изменения вы вносите в расширение, включая следующие изменения (но не ограничиваясь ими):

  • Изменения в дизайне.
  • Новые и улучшенные функции.
  • Исправленные ошибки и решенные проблемы.
  • Изменения в ценовой политике.

Информация из файла CHANGES.md отображается в тот момент, когда администратор Plesk нажимает имя расширения в каталоге расширений.

Вот пример содержимого файла CHANGES.md для расширения, выпущенного Plesk. Вы можете использовать его для справки.

# 1.3.0

* [*] Docker поддерживается на Virtuozzo 7, и в Plesk Docker теперь доступны отдельные шаблоны приложений для Virtuozzo.

# 1.2

* [*] Установка расширения Docker зависала на серверах Linode с Ubuntu 16.04. (EXTDOCKER-25)

# 1.1

* [-] В поле Переменные среды в настройках контейнера отображалась неправильная подсказка. (EXTDOCKER-19)
* [-] В случае использования удаленного Docker подсказка не отображалась для значка SSL на странице "Инструменты и настройки > Docker". (EXTDOCKER-8)
* [-] В результатах поиска в Plesk в случае найденного контейнера из каталога Docker отображались HTML-теги. (EXTDOCKER-6)
* [-] При удалении правила проксификации Docker со страницы Правила проксификации и со страницы Сайты и домены отображались разные диалоги подтверждения. (EXTDOCKER-2)
 

Значки и снимки экрана (_meta/)

Папка /_meta/ в корневой папке расширения содержит значки и снимки экрана расширения.

Значки

Значки расширения отображаются в разных частях интерфейса Plesk. Пожалуйста, придерживайтесь следующих правил при проектировании и создании значков для вашего расширения:

  1. Изображение должно занимать как можно большую часть рабочей области значка.
  2. Изображение должно быть расположено в центре рабочей области значка.
  3. Фон значка должен быть прозрачным.

1

Значки должны иметь формат PNG и быть доступны в следующих размерах.

Размер Расположение

32 px * 32 px

_meta/icons/32x32.png

64 px * 64 px

_meta/icons/64x64.png

128 px * 128 px

_meta/icons/128x128.png

Только для платных расширений: 160 px * 160 px

_meta/icons/160x160.png

Снимки экрана

Снимки экрана сопровождают описание расширения на странице обзора расширения. Они должны иметь формат PNG. Можно создать до трех снимков экрана.

Примечание. Должен быть доступен хотя бы один снимок экрана.

Размер Расположение

1024 px * 768 px

_meta/screenshots/1.png (обязательно)

_meta/screenshots/2.png (необязательно)

_meta/screenshots/3.png (необязательно)

 

Разрешение конфликтов при обновлении

Когда администратор загружает новую версию расширения в Plesk, возможные конфликты между существующими и новыми файлами разрешаются следующим образом.

  • Если файл существует, он будет перезаписан.
  • Если папка уже существует, файлы внутри нее будут перезаписаны.
  • Существующие файлы, которые не присутствуют в новой версии файлов расширения, будут удалены.

Если какое-либо из этих правил разрешения конфликтов не может быть выполнено (например, существующий файл заблокирован и не может быть перезаписан), процедура обновления прерывается.

 

Процедура удаления

При удалении расширения удаляются следующие файлы:

  • PRODUCT_ROOT_D/admin/htdocs/modules/EXTENSION_ID/
  • PRODUCT_ROOT_D/admin/plib/modules/EXTENSION_ID/
  • PRODUCT_ROOT_D/var/modules/EXTENSION_ID/

Здесь PRODUCT_ROOT_D – это /usr/local/psa на системах Linux и %plesk_dir% – на системах Windows.

Если расширение не может быть удалено, процедура удаления прерывается.

Все файлы, используемые расширением, должны быть удалены с помощью скрипта pre-uninstall.

 

Создание и упаковка расширений

Вы можете создать файловую структуру, необходимую для расширения, за один шаг, используя следующий вызов командной строки:

<code>extension --create <EXTENSION_NAME></code>

Читайте больше об этой утилите в следующих документах:

С этой утилитой вы можете создать расширение, готовое к распространению (создав архив ZIP файловой структуры расширения). Следующий вызов создает архив в текущей папке:

extension -p my-project

Если вы хотите создать архив в другой папке, добавьте к вызову утилиты опцию -destination /path/to/directory/.

 

Соглашения по именованию классов

Система позволяет вызывать классы практически из любого места кода без их предварительного включения. Для этого вам надо правильно именовать классы и поместить файл, содержащий класс, в специальную папку. Это упрощение необязательно в большинстве случаев, оно лишь делает ваш код более компактным, но в некоторых случаях вам необходимо придерживаться соглашения по именованию. Например, если вы хотите добавить виджет dashboard (информационная панель), вам необходимо придерживаться соглашений, потому что система должна автоматически найти и загрузить этот класс.

Соглашения по именованию заключаются в следующем:

  • Имя класса должно начинаться с префикса Modules_ExtensionName. Здесь ExtensionName – это идентификатор вашего расширения, обработанный согласно следующей инструкции:
    1. Необходимо убрать дефисы (-).
    2. Необходимо перевести первую букву и буквы, которым предшествуют дефисы, в верхний регистр.

    Пример: my-site изменяется на MySite.

  • Имя класса должно включать путь к папке, в которой находится файл с содержимым класса. Косые черты (/) в этом пути заменяются на подчеркивания (_). Путь должен быть указан относительно папки /plib/library/ расширения.

    Например, если класс находится в файле /plib/library/website/Promo.php, а идентификатор расширения – my-site, имя класса должно быть:

    Modules_MySite_Website_Promo.

Zend использует аналогичный подход к автозагрузке классов. Читайте об этом больше в http://framework.zend.com/manual/en/learning.autoloading.design.html.

Ограничения

Автозагрузка классов не работает в папке /htdocs/public/. Если вам требуется эта возможность, запустите автозагрузку вручную, добавив следующий код в начале файла:

require_once('pm/Loader.php');
pm_Loader::registerAutoload();
pm_Bootstrap::init();
 

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.