Áèáëèîòåêà LibPHP

Библиотека LibPHP

 Top Next

Представленная библиотека классов предназначена для оптимизации процесса создания плагинов на языке PHP для панелей от ISPsystem, таких как ISP manager, BILL manager и т.д.

Библиотека формально является плагином и устанавливается в директорию /usr/local/ispmgr/lib/php, становясь в один ряд с библиотеками для других языков программирования, поставляемыми изначально.


Îáùàÿ èíôîðìàöèÿ

Общая информация

 Top Previous Next

Функциональность классов библиотеки:

· Получение плагином параметров, переданных панелью в обработчик, в обоих форматах: CGI и XML.
· Возможности отладки:
o Получение параметров из агрументов командной строки,
o Эмуляция получения параметров в коде,
o Ведение лога с опциональным отладочным режимом автоматизированного перехвата всех ошибок и исключений, возникающих во время работы плагина.
o Включение режима отладки может быть проинициировано как в коде, так и при помощи файла /usr/local/ispmgr/etc/имя_плагина.debug.
· Вызов функции панели из плагина.

Системные требования:

· PHP 5+
· Модуль PHP: DOM.

Версия библиотеки: 1.0

Автор: Dmitry

URL: http://usings.ru/isp_plugin_libphp/

Лицензия: GPL


Êëàññû

Классы

Библиотека содержит следующие классы:

· ISP_Plugin
· ISP_Parser
· ISP_Parser_CGI
· ISP_Parser_XML
· EventLog
· Mgr


Êëàññ ISP_Plugin

Класс ISP_Plugin

Базовый класс плагина.

Обеспечивает наиболее простой, но в то же время и гибкий, способ использования данной библиотеки для создания плагина.

Содержит следующие общедоступные методы:

· Конструктор
· GetParser
· LogEvent
· OutPlain
· OutXML
· Error

Пример:

require_once('/usr/local/ispmgr/lib/php/isp_plugin.php');
$plugin = new ISP_Plugin('myplugin', PARSER_TYPE_XML);
$xmlParser = $plugin->GetParser();
$func = $xmlParser->GetParam('func');


Êîíñòðóêòîð

Конструктор

Создать новый экземпляр класса.

Синтаксис:

new ISP_Plugin($name, $parser_type, $create_log = false, $debug = false, $input = '')

Параметры:

· $name

Название плагина в файловой системе.

Это название будет использовано при создании лога, а также при проверке наличия файла /usr/local/ispmgr/etc/имя_плагина.debug.

· $parser_type

Формат передаваемых параметров.

Может принимать одно из значений: PARSER_TYPE_CGI, PARSER_TYPE_XML.

· $create_log

(необязательный параметр) Создавать лог.

Если разрешено, будет автоматически создан файл /usr/local/ispmgr/var/имя_плагина.log.

В этот файл можно вносить произвольные записи, используя метод LogEvent.

Значение этого параметра перекрывается параметром $debug.

· $debug

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

Если разрешено, то значение параметра $create_log не имеет значения.

· $input

(необязательный параметр) Использовать указанную строку в качестве входных данных.

Позволяет установить входные данные плагина. Служит для целей отладки.

Возвращаемое значение:

Новый экземпляр класса.

Примечание 1:

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

· $debug = true
· Наличие непустого файла /usr/local/ispmgr/etc/имя_плагина.debug, содержащего ненулевое значение (например: 1, YES, on и т.д.).

Примечание 2:

Если запуск плагина осуществлен из командной строки, и, при этом, ему переданы параметры (в формате, соответствующем значению $parser_type), то эти параметры будут переданы в качестве значения $input (переопределяя значение $input, если оно указано в коде вызова конструктора).


Ìåòîä GetParser

Метод GetParser

Получить экземпляр класса ISP_Parser, ассоциированного с данным плагином.

Синтаксис:

function GetParser()

Возвращаемое значение:

Экземпляр класса ISP_Parser.

Примечание:

Поскольку класс ISP_Parser является абстрактным, тип реально возвращаемого класса может быть одним из: ISP_Parser_CGI, ISP_Parser_XML в зависимости от значения параметра $parser_type, использованного в конструкторе данного класса.


Ìåòîä LogEvent

Метод LogEvent

Произвести запись в лог плагина, если это было разрешено в конструкторе установкой параметра $create_log, либо в случае активированного режима отладки.

Синтаксис:

LogEvent($text)

Параметры:

· $text

Текст новой записи лога.

Примечание:

В случае, если ведение лога не разрешено в конструкторе класса, данные метод не произведет никаких действий и не вызовет ошибки.


Ìåòîä OutPlain

Метод OutPlain

Произвести вывод в формате XML данных, заданных в виде строки, и завершить работу плагина.

Синтаксис:

OutPlain($text)

Параметры:

· $text

Текст, представляющий собой корректный вид содержимого тега doc, предназначенный для вывода в качестве выходных данных плагина.


Ìåòîä OutXML

Метод OutXML

Произвести вывод в формате XML данных, заданных в виде объекта XMLDocument, и завершить работу плагина.

Синтаксис:

OutXML($xml)

Параметры:

· $xml

Объект типа XMLDocument.


Ìåòîä Error

Метод Error

Произвести вывод ошибки, и завершить работу плагина.

Синтаксис:

Error($code, $text = '')

Параметры:

· $code

Код ошибки (согласно странице документации Коды ошибок).

· $text

(необязательный параметр) Текст, представляющий собой описание ошибки.


Êëàññ ISP_Parser

Класс ISP_Parser

Базовый абстрактный класс парсера входных данных.

Обеспечивает основу полиморфизма для дочерних реализаций: классов ISP_Parser_CGI и ISP_Parser_XML.

Содержит следующие общедоступные статические методы:

· Create

Содержит следующие общедоступные методы:

· GetInput
· GetParams
· GetParam

Содержит следующие общедоступные свойства:

· UserLevel
· UserName


Ñòàòè÷åñêèé ìåòîä Create

Статический метод Create

Создать новый экземпляр дочернего класса: ISP_Parser_CGI или ISP_Parser_XML.

Синтаксис:

Create($type, $input = '')

Параметры:

· $type

Тип парсера.

Может принимать одно из значений: PARSER_TYPE_CGI, PARSER_TYPE_XML.

Созданный экземпляр класса будет соответственно: ISP_Parser_CGI или ISP_Parser_XML.

· $input

(необязательный параметр) Использовать указанную строку в качестве входных данных.

Позволяет установить входные данные плагина. Служит для целей отладки.

Возвращаемое значение:

Новый экземпляр дочернего класса.


Ìåòîä GetInput

Метод GetInput

Получить входные данные, полученные плагином, в необработанном (RAW) виде.

Синтаксис:

function GetInput()

Возвращаемое значение:

Строка, содержащая входные данные плагина в необработанном виде.


Ìåòîä GetParams

Метод GetParams

Получить ассоциативный массив всех параметров, содержащихся во входных данных.

Синтаксис:

function GetParams()

Возвращаемое значение:

Ассоциативный массив всех параметров.

Пример:

$xmlParser = ISP_Parser::Create(PARSER_TYPE_XML);
$params = $xmlParser->GetParams();

$func = $params['func'];
$sok = $params['sok'];


Ìåòîä GetParam

Метод GetParam

Получить значение указанного параметра, содержащегося во входных данных.

Синтаксис:

function GetParam($name)

Параметры:

· $name

Имя параметра.

Возвращаемое значение:

Значение указанного параметра.

Пример:

$xmlParser = ISP_Parser::Create(PARSER_TYPE_XML);
$func = $xmlParser->GetParam('func');


Ñâîéñòâî UserLevel

Свойство UserLevel

Содержит уровень доступа пользователя панели (1 .. 7).


Ñâîéñòâî UserName

Свойство UserName

Содержит имя пользователя панели.


Êëàññ ISP_Parser_CGI

Класс ISP_Parser_CGI

Класс парсера входных данных, переданных панелью в формате CGI.

Содержит следующие общедоступные методы:

· Конструктор
· GetInput (унаследовано от класса ISP_Parser)
· GetParams (унаследовано от класса ISP_Parser)
· GetParam (унаследовано от класса ISP_Parser)

Содержит следующие общедоступные свойства:

· UserLevel (унаследовано от класса ISP_Parser)
· UserName (унаследовано от класса ISP_Parser)

Класс не может быть унаследован.


Êîíñòðóêòîð

Конструктор

Создать новый экземпляр класса.

Синтаксис:

new ISP_Parser_CGI($input = '')

Параметры:

· $input

(необязательный параметр) Использовать указанную строку в качестве входных данных.

Позволяет установить входные данные плагина. Служит для целей отладки.

Возвращаемое значение:

Новый экземпляр класса.

Примечание:

Если запуск плагина осуществлен из командной строки, и, при этом, ему переданы параметры (в формате CGI), то эти параметры будут переданы в качестве значения $input (переопределяя значение $input, если оно указано в коде вызова конструктора).


Êëàññ ISP_Parser_XML

Класс ISP_Parser_XML

Класс парсера входных данных, переданных панелью в формате XML.

Содержит следующие общедоступные методы:

· Конструктор
· GetInput (унаследовано от класса ISP_Parser)
· GetParams (унаследовано от класса ISP_Parser)
· GetParam (унаследовано от класса ISP_Parser)
· GetXML

Содержит следующие общедоступные свойства:

· UserLevel (унаследовано от класса ISP_Parser)
· UserName (унаследовано от класса ISP_Parser)

Класс не может быть унаследован.


Êîíñòðóêòîð

Конструктор

Создать новый экземпляр класса.

Синтаксис:

new ISP_Parser_XML($input = '')

Параметры:

· $input

(необязательный параметр) Использовать указанную строку в качестве входных данных.

Позволяет установить входные данные плагина. Служит для целей отладки.

Возвращаемое значение:

Новый экземпляр класса.

Примечание:

Если запуск плагина осуществлен из командной строки, и, при этом, ему переданы параметры (в формате XML), то эти параметры будут переданы в качестве значения $input (переопределяя значение $input, если оно указано в коде вызова конструктора).


Ìåòîä GetXML

Метод GetXML

Получить входные данные, полученные плагином, в виде объекта XMLDocument.

Синтаксис:

function GetInput()

Возвращаемое значение:

Объект XMLDocument, содержащий входные данные плагина в виде документа XML.


Êëàññ EventLog

Класс EventLog

Класс лога (журнала) работы плагина.

Обеспечивает внесение записей в лог, в том числе - в автоматическом режиме.

Класс является реализацией паттерна проектирования singleton. Таким образом, класс не имеет общедоступного конструктора и может быль инстанциирован лишь единожды при помощи статического метода Open.

Содержит следующие общедоступные статические методы:

· Open

Содержит следующие общедоступные методы:

· Close
· Write
· GetPath


Ñòàòè÷åñêèé ìåòîä Open

Статический метод Open

Создать новый (и единственный) экземпляр класса.

Синтаксис:

function Open($filename, $handleErrors = true)

Параметры:

· $filename

Имя файла, в который будет вестись запись лога.

Может содержать абсолютный путь.

Если имя файла не содержит абсолютный путь, путь будет назначен по умолчанию: /usr/local/ispmgr/var.

Если имя файла не содержит расширение .log, это расширение будет добавлено автоматически.

· $handleErrors

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

Возвращаемое значение:

Новый экземпляр класса, если иной экземпляр не был инстанциирован ранее, иначе - ранее инстанциированный экземпляр.


Ìåòîä Close

Метод Close

Закрыть файл лога и прекратить его ведение.

Синтаксис:

function Close()

Возвращаемое значение:

Нет.


Ìåòîä Write

Метод Write

Произвести запись указанной строки в конец файла лога.

Синтаксис:

function Write($text)

Параметры:

· $text

Строка, содержащая произвольный текст.

Текущая дата и время будут добавлены перед началом строки автоматически.

Символ переноса строки будет добавлен в конце записи автоматически.

Возвращаемое значение:

Нет.


Ìåòîä GetPath

Метод GetPath

Получить имя файла, в который ведется лог.

Синтаксис:

function GetPath()

Возвращаемое значение:

Строка, содержащая имя файла лога.


Êëàññ Mgr

Класс Mgr

Класс, предназначенный для взаимодействия плагина с панелью.

Обеспечивает несколько наиболее простых способов взаимодействия с любой установленной панелью от компании ISPsystem при помощи вызова утилиты mgrctl.

Содержит следующие общедоступные статические методы:

· Query

Содержит следующие общедоступные методы:

· Конструктор
· RunQuery


Ñòàòè÷åñêèé ìåòîä Query

Статический метод Query

Выполнить запрос к указанной панели управления.

Синтаксис:

function Query($func, $params = '', $out = 'xml', $mgr = 'ispmgr')

Параметры:

· $func

Имя вызываемой функции, согласно API используемой панели (документация: Главная страница).

· $params

(необязательный параметр) Строка, представляющая собой список параметров в виде key1=value1 key2=value2 ...

Либо ассоциативный массив:

['key1'] => value1,

['key2'] => value2,

и т.д.

· $out

(необязательный параметр) Тип вывода. Может принимать значения: xml (по-умолчанию), devel, text.

· $mgr

(необязательный параметр) Название панели в файловой системе.

Возвращаемое значение:

Вывод указанной функции в указанном формате.


Êîíñòðóêòîð

Конструктор

Создать новый экземпляр класса для взаимодействия с указанной панелью.

Синтаксис:

new ISP_Plugin($name = 'ispmgr')

Параметры:

· $name

Название панели в файловой системе.

Возвращаемое значение:

Новый экземпляр класса.


Ìåòîä RunQuery

Метод RunQuery

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

Синтаксис:

function RunQuery($func, $params = '', $out = 'xml')

Параметры:

· $func

Имя вызываемой функции, согласно API используемой панели (документация: Главная страница).

· $params

(необязательный параметр) Строка, представляющая собой список параметров в виде key1=value1 key2=value2 ...

Либо ассоциативный массив:

['key1'] => value1,

['key2'] => value2,

и т.д.

· $out

(необязательный параметр) Тип вывода. Может принимать значения: xml (по-умолчанию), devel, text.

Возвращаемое значение:

Вывод указанной функции в указанном формате.


Ïóáëèêàöèÿ ïëàãèíà

Публикация плагина

 Top Previous

При публикации плагина, укажите в своем репозитории ссылку на него внутри тега depend.

Пример:

<depend>libphp</depend>