k-shym/urfa-client

Universal PHP client billing system NetUp UTM5 based api.xml

, _(*1)

URFAClient

Универсальный PHP клиент для биллинговой системы NetUp UTM5 на основе api.xml, _(*2)

Установка (composer)

composer require k-shym/urfa-client "^2.0"

Зависимости

• UTM 5.2.1-008 >=
• PHP 5.4 >=
• Ext: JSON, OpenSSL, SimpleXML, Hash, Filter

Описание параметров

CMD

bin/urfaclient -h

The options are as follows:
   [-a, --api <path> ]             Path to api.xml
   [-f, --function <name>]         Name function from api.xml
   [-t, --type <type>]             Type return (array, json, xml), default: array
   [-l, --list]                    List of functions from api.xml
   [-h, --help ]                   This help
   [-v, --version ]                Version URFAClient

Пример

Рассмотрим пример использования библиотеки на примере функции rpcf_add_user_new, у нас есть XML описание:, _(*3)

<function name="rpcf_add_user_new" id="0x2125">
    <input>
        <string name="login"/>
        <string name="password"/>
        <string name="full_name" default=""/>
        <integer name="is_juridical" default="0"/>
        <string name="jur_address" default=""/>
        <string name="act_address" default=""/>
        <string name="flat_number" default=""/>
        <string name="entrance" default=""/>
        <string name="floor" default=""/>
        <string name="district" default=""/>
        <string name="building" default=""/>
        <string name="passport" default=""/>
        <integer name="house_id" default="0"/>
        <string name="work_tel" default=""/>
        <string name="home_tel" default=""/>
        <string name="mob_tel" default=""/>
        <string name="web_page" default=""/>
        <string name="icq_number" default=""/>
        <string name="tax_number" default=""/>
        <string name="kpp_number" default=""/>
        <string name="email" default=""/>
        <integer name="bank_id" default="0"/>
        <string name="bank_account" default=""/>
        <string name="comments" default=""/>
        <string name="personal_manager" default=""/>
        <integer name="connect_date" default="0"/>
        <integer name="is_send_invoice" default="0"/>
        <integer name="advance_payment" default="0"/>

        <integer name="switch_id" default="0"/>
        <integer name="port_number" default="0"/>
        <integer name="binded_currency_id" default="810"/>

        <integer name="parameters_count" default="size(parameter_value)"/>
        <for name="i" from="0" count="size(parameter_value)">
            <integer name="parameter_id" array_index="i"/>
            <string name="parameter_value" array_index="i"/>
        </for>

        <integer name="groups_count" default="size(groups)"/>
        <for name="i" from="0" count="size(groups)">
            <integer name="groups" array_index="i"/>
        </for>

        <integer name="is_blocked" default="0"/>
        <double name="balance" default="0.0"/>
        <double name="credit" default="0.0"/>
        <double name="vat_rate" default="0.0"/>
        <double name="sale_tax_rate" default="0.0"/>
        <integer name="int_status" default="1"/>
    </input>
    <output>
        <integer name="user_id"/>
        <if variable="user_id" value="0" condition="eq">
            <integer name="error_code"/>
            <string name="error_description"/>
        </if>
        <if variable="user_id" value="0" condition="ne">
            <integer name="basic_account"/>
        </if>
    </output>
</function>

И так, нам нужно описать входные параметры (элемент input) в ассоциативный массив. Если в элементе присутствует атрибут default, параметр считается необязательным., _(*4)

Получаем полное описание параметров функции rpcf_add_user_new из api.xml:, _(*5)

bin/urfaclient -f rpcf_add_user_new -t json

```json { "login": "", "password": "", "full_name": "", "is_juridical": 0, "jur_address": "", "act_address": "", "flat_number": "", "entrance": "", "floor": "", "district": "", "building": "", "passport": "", "house_id": 0, "work_tel": "", "home_tel": "", "mob_tel": "", "web_page": "", "icq_number": "", "tax_number": "", "kpp_number": "", "email": "", "bank_id": 0, "bank_account": "", "comments": "", "personal_manager": "", "connect_date": 0, "is_send_invoice": 0, "advance_payment": 0, "switch_id": 0, "port_number": 0, "binded_currency_id": 0, "parameters_count": [ { "parameter_id": 0, "parameter_value": "" } ], "groups_count": [ { "groups": 0 } ], "is_blocked": 0, "balance": 0, "credit": 0, "vat_rate": 0, "sale_tax_rate": 0, "int_status": 0 }, <sub>(*6)</sub>

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

Как было замечено, разработчики UTM5 не пришли к единому формату описания функций. Отсюда возник вопрос, какое имя давать параметру `for` для элементов массива?
Поэтому было принято решение, в качестве имени использовать имя атрибута счетчика `*_count`. В нашем случае будет так:
```php
[
    // ...
    'parameters_count' => [
        [
            'parameter_id' => 0,
            'parameter_value' => 'м',
        ],
        [
            'parameter_id' => 1,
            'parameter_value' => '13.06.2014',
        ],
    ],
    'groups_count' => [
        [
            'groups' => 1000,
        ],
        [
            'groups' => 1001,
        ],
    ],
    // ...
];

Если попадется элемент error будет выброшено исключение XML Described error:, а далее атрибуты ошибки., <sub>(*7)</sub>

C условиями if все просто, если истина, то заходим внутрь. И содержание обрабатывается, как описано выше., <sub>(*8)</sub>

В итоге, получаем минимальный набор параметров для создания пользователя:, <sub>(*9)</sub>

require __DIR__ . '/vendor/autoload.php';
use URFAClient\URFAClient;

$urfa = URFAClient::init([
    'login'    => 'init',
    'password' => 'init',
    'address'  => 'localhost',
]);

$result = $urfa->rpcf_add_user_new([
    'login'=>'test',
    'password'=>'test',
]);

$result = $urfa->rpcf_add_user_new('{
  "login": "test2",
  "password": "test2"
}');

В переменную $result попадут данные которые описаны в элементе output., <sub>(*10)</sub>

Тесты

docker-compose up -d
docker exec -t urfa composer install
docker exec -t urfa vendor/bin/phpunit --coverage-text

Возможные проблемы

• Тестировалось на версии биллинга UTM-5.3-003, UTM-5.4-004 и UTM-5.5-015
• Тестировались не все функции из api.xml
• При обновлении api.xml обязательно проверяйте используемые функции

По возникшим проблемам присылайте api.xml и полную версию ядра UTM5. Удачи!, <sub>(*11)</sub>