Расширение Plesk представляет собой архив ZIP, который содержит организованную специальным образом структуру папок и файл с метаданными, описывающими программное обеспечение. Начиная с Plesk 11, разработчики могут упаковывать расширения в кроссплатформенном формате ? в виде архива ZIP, в котором файл метаданных находится в корневой папке. Такие расширения поддерживаются Plesk для Linux и для Windows.

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

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

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

Вот пример файла meta.xml, описывающего расширение с названием «Тестовое расширение».

<?xml version="1.0"?>
<module>
 <id>test-extension</id>
 <name>Тестовое расширение</name>
 <description>Добавьте здесь описание...</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://сайт-вашей-компании</url>
 <support_url>http://сайт-вашей-компании/support</support_url>
 <plesk_min_version>12.5.0</plesk_min_version>
</module>

Ниже описаны элементы, доступные внутри узла module:

  • id

    Идентификатор расширения. Он используется как часть URL-адреса корня расширения. Например, если ID расширения – sample-extension, расширение доступно по адресу http://<plesk-host-name>:<port>/modules/sample-extension.

    • Составьте ID на основании выбранного названия расширения (читайте о нем ниже). Имейте в виду, что ID расширения – часть его URL-адреса в каталоге, поэтому использование уникальных значимых слов может способствовать его более эффективному продвижению в поисковых системах (SEO).
    • Все слова должны быть введены в нижнем регистре.
    • Разделяйте слова с помощью тире.
  • name

    Название, которое администраторы увидят в списке расширений в Plesk (Управление сервером > Расширения) после установки расширения.

    • Выберите название длиной менее 60 символов. Предпочтительная длина – 25 символов или менее, чтобы название гарантированно полностью помещалось в заголовок рекламного блока на сайте.
    • Название должно быть на английском языке. Использование других языков рекомендуется, но необязательно.
    • Избегайте слов, которые не добавляют уникальной значимой информации, например: extension, plugin, Plesk, installer, integration и так далее.
  • description

    Описание расширения, которое администраторы увидят в списке расширений в Plesk (Управление сервером > Расширения) после установки расширения.

  • category

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

Название категории (удобочитаемое) Код категории (указывается в файле meta.xml)
Внешний вид appearance
Аутентификация auth
Резервное копирование backup
Инструменты клиента client_tool
Облака clouds
DNS dns
Примеры example
Пакеты функций feature_pack
Развлечения fun
Помощь и решение проблем help
Почта mail
Мониторинг monitoring
Безопасность security
Серверные инструменты server_tool
SEO и социальные сети social
Веб-приложения и редактирование сайтов web_app
Веб-разработка developer
Веб-серверы webserver
Производительность сайтов performance
  • version

    Версия расширения. Может быть произвольной строкой, но мы рекомендуем использовать следующий формат: X.Y (где X и Y – числа), например, 1.0. Администраторы могут видеть ее в списке расширений.

  • release

    Версия пакета расширения. Она относится к изменениям, которые не затрагивают код расширения, но меняют что-либо в самом пакете (например, послеустановочный скрипт). Может быть произвольной строкой, но мы рекомендуем использовать следующий формат: X (где X – число), например, 1. Администраторы могут видеть ее в списке расширений.

  • vendor

    Имя поставщика.

  • url

    Сайт поставщика расширения.

  • support_url

    Ссылка на страницу службы поддержки поставщика расширения. Администраторы могут видеть ее на странице расширения в Каталоге расширений. Наличие URL-адреса службы поддержки обязательно для платных расширений.

  • help_url

    Ссылка на документацию к расширению. Администраторы могут видеть ее в списке расширений.

  • buy_url (необязательно)

    URL-адрес сайта или интернет-магазина, где можно купить лицензию на расширение. Расширению может требоваться лицензия для работы некоторых или всех функций. Указание URL-адреса приведет к появлению кнопки «Купить сейчас» рядом с именем расширения в Каталоге расширений. При нажатии этой кнопки в окне браузера откроется указанный URL-адрес. Имейте в виду, что платные расширения должны содержать ссылку на страницу службы поддержки поставщика расширения – смотрите описание support_url выше.

    Значение по умолчанию для buy_url – следующий URL-адрес: https://go.plesk.com/buy-plesk-ext/<id>, где id – идентификатор вашего расширения (смотрите описание id выше).

  • plesk_min_version (необязательно)

    Минимальная версия Plesk, поддерживаемая расширением.

    Выбор минимальной поддерживаемой версии Plesk обычно зависит от используемой версии Plesk SDK.

    Примечание: Готовое расширение необходимо тщательно протестировать на всех поддерживаемых версиях Plesk, чтобы удостовериться в том, что оно работает правильно и не зависит от различий в версиях ядра и SDK.

  • plesk_max_version (необязательно)

    Максимальная версия Plesk, поддерживаемая расширением.

    Этот параметр полезен в случае наличия известных или вероятных проблем при работе с версиями Plesk выше указанной. Например, если в этих версиях была добавлена поддержка новой версии PHP, и это может каким-либо образом нарушить работу.

  • os (необязательно)

    Операционные системы, поддерживаемые расширением. Возможные значения: unix (для Linux) и win (для Windows).

Локализация элементов

Чтобы перевести значение элемента на другой язык, продублируйте его и добавьте атрибут xml:lang с 4-буквенным кодом языка в соответствии с RFC1766. Например:

3563<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 находится в корневой папке расширения. В файле DESCRIPTION.md должен использоваться английский язык.

Локализация описания расширения

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

Примечание: Эта опция возможна, начиная с Plesk 17.8.

Для переводов описаний расширений создаются отдельные файлы описаний.

  • Файлы описаний имеют формат Markdown (.md).
  • Файлы описаний хранятся в папке /_meta/descriptions/.
  • Можно создать несколько файлов описаний, по одному для каждой локали. В зависимости от текущей локали Plesk, будет выбираться нужный файл.
  • Имя файла описания соответствует идентификатору его локали: en-US.md, de-DE.md, ru-RU.md и так далее.

Описание расширения будет отображаться с помощью файла описания, соответствующего локали, которая в данный момент используется в Plesk. Если подходящий файл описания не найден в папке descriptions/, описание будет отображаться с помощью файла 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. Фон значка должен быть прозрачным.

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

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

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

extension --create <EXTENSION_NAME>

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

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

extension -p my-project

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