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

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

Вот пример файла 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

DNS

dns

Примеры

example

Развлечения

fun

Помощь и решение проблем

help

Почта

mail

Мониторинг

monitoring

Безопасность

security

Серверные инструменты

server_tool

SEO & Социальные сети

social

Веб-приложения & Редактирование сайтов

web_app

Веб-разработка

developer

Веб-серверы

webserver

  • версия

    Версия расширения. Может быть произвольной строкой, но мы рекомендуем использовать следующий формат: 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 отображается в тот момент, когда администратор 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();