Расширения могут получать полную информацию о сущностях Plesk (учетных записях клиентов, тарифных планах и так далее), а также управлять ими через интерфейс XML API. Этот интерфейс подразумевает обмен запросами операций в виде пакетов XML. Plesk получает такой запрос операции в виде XML-структуры, обрабатывает его и отвечает с помощью класса PHP, поля которого повторяют исходную структуру дерева XML. Структура пакетов XML определяется протоколом XML API (смотрите XML API Guide).

Каждый сервер Plesk поддерживает несколько версий XML API (для обратной совместимости). Можно отправлять пакеты для конкретной версии XML API, явно указав версию протокола. Если вы не указываете версию, будет использоваться последняя поддерживаемая версия XML API.

Для выполнения операции через XML API используйте класс pm_ApiRpc. Используются следующие методы:

Кроме того, Plesk предоставляет библиотеку PHP, которая упрощает работу с XML API. Эта библиотека может использоваться в качестве альтернативы или дополнения описанного здесь метода. В разделе Использование библиотеки PHP XML API ниже смотрите инструкции по добавлению и использованию этой библиотеки в вашем расширении.

Пример 1: Получение информации о подписке (с указанием версии протокола XML API)

Чтобы выполнить операцию получения информации о подписке через XML API с указанной версией протокола, используйте следующий код:

$request = <<<APICALL
<webspace>
  <get>
    <filter>
      <id>170</id>
    </filter>
    <dataset>
      <gen_info/>
    </dataset>
  </get>
</webspace>
APICALL;

$response = pm_ApiRpc::getService('1.6.3.3')->call($request);
echo 'Domain name: ' . $response->webspace->get->result->data->gen_info->name;

Библиотека PHP позволяет достичь той же цели, используя следующий код:

$client = new \PleskX\Api\InternalClient();

echo 'Domain name: ' . $client->webspace()->get('id', 170)->name;

Следующий пример проекта предоставлен Plesk, чтобы проиллюстрировать использование библиотеки PHP XML API: https://github.com/plesk/ext-php-api-lib-demo.

Пример 2: Получение статистики по серверу (без указания версии протокола XML API)

Вот пример вызова XML API без указания версии протокола.

$request = '<server><get><stat/></get></server>';
$stats = pm_ApiRpc::getService()->call($request)->server->get->result->stat->objects;

Библиотека PHP позволяет достичь той же цели, используя следующий код:

$stats = $client->server()->getStatistics()->objects;

Пример 3: Включение настроек PHP для подписки (требуются права администратора)

По умолчанию вызовы API выполняются с правами текущего пользователя. Однако некоторые действия требуют прав администратора. В таких случаях следует использовать аргумент $login метода call().

Например, рассмотрим расширение, которое включает настройки PHP для подписки. Это расширение отправляет следующий запрос:

$request = <<<APICALL
<webspace>
  <set>
    <filter>
      <id>2</id>
    </filter>
    <values>
      <php-settings>
        <setting>
          <name>extension</name>
          <value>msql.so</value>
        </setting>
      </php-settings>
    </values>
  </set>
</webspace>
APICALL;

Для выполнения этого запроса необходимы права администратора:

$response = pm_ApiRpc::getService()->call($request, 'admin');

Обработка ошибок

Если вы запускаете вызов XML API, содержащий данные в форме, не соответствующей корректному дереву XML, будет выдано предупреждение в PHP.

Если пакет XML не является корректным вызовом операции, система выдаст исключение PleskAPIParseException.

Использование библиотеки PHP XML API

  1. Добавьте библиотеку к своему расширению

    В файле composer.json добавьте требование plesk/api-php-lib

    Например: https://github.com/plesk/ext-php-api-lib-demo/blob/master/composer.json#L7

  2. Создайте экземпляра клиента

    $client = new \PleskX\Api\InternalClient();

    Например: https://github.com/plesk/ext-php-api-lib-demo/blob/master/src/plib/controllers/IndexController.php#L10

  3. Используйте нужные вызовы API с помощью клиента

    $client->...

Следующий пример проекта предоставлен Plesk, чтобы проиллюстрировать использование библиотеки PHP XML API: https://github.com/plesk/ext-php-api-lib-demo.