Примечание. Этот документ описывает концептуальный API событий. Актуальная реализация скриптов использует класс-ориентированный подход на базе Scope-классов.
Подробнее: docs/control-scripts-guide.md

API для написания скриптов

• Скрипт должен быть написан на php
• Скрипт может находиться где угодно, при добавлении скрипта можно указать директорию где его нужно искать.
• Скрипт сам должен обеспечитьвать подключение дополнительных файлов, если это необходимо.
• Скрипт свободен в своей реализации
• Скрипты подключаться сразу все, а потом уже запускаются по очереди. Порядок запуска - как-нибудь :)
• Взаимодействия между скриптами желательно вести через ивенты.

Основные положения. INIT

• Файл скрипта должен содержать как минимум одну функцию, название которой должно формироваться по следующему принципу: script_[filename]_init, именно эта функция и будет точкой входа скрипта. Её основная задача - зарегистрировать всё, что нужно, подписаться на ивенты и передать управление дальше
• Основная фукция должна принимать 2 параметра: $server - ссылка на само приложение сервера, $params - произвольный набор параметров.
• Система ожидает, что функция вернёт результат выполнения.

Пример

    <?php
    function script_example_init($server, $params) {
        // something...

        return true; // result of executing
    }

Основные положения. INVOKE

• Скрипт может быть вызван принудительно через rest api, в таком случае будет вызвана определённая функция из файла скрипта.
• Функция должна называться по схожему принципу script_[filename]_invoke
• Эта функция принимает всё те же 2 параметра: $server - ссылка на само приложение сервера, $params - произвольный набор параметров. Параметры должны быть переданы при вызове через RESP API
• Эта функция должна вернуть ассоциативный массив с минимум одним ключём status выполнения скрипта (true|false)
• Если функция хочет что-то вернуть в ответ на запрос REST API, она должна в return включить поле response

Пример

    <?php
    function script_example_invoke($server, $params) {
        // something...

        return [
            "status" => true, // result of executing
            "response" => [
                // ...
            ]
        ]; 
    }

Основные положения. EVENTS

• Скрипт может работать с ивентами. Он может подписаться на ивент, или стригерить существующий ивент, или зарегистрировать свой, на который потом смогут подписаться другие скрипты.
• Регистрацию ивентов нужно проводить при инициализации скрипта.
• Подписываться на ивенты нужно при инициализации скрипта.
• Запуск обработчика ивента не произойдёт в момент вызова тригера ивента. Вместо этого нужно передать колбек функцию тригера, которая будет вызвана как только ивент станет доступным в системе, ведь на момент тригера он ещё может быть не зарегистрированным.

Пример регистрации ивента

    <?php
    function script_example_init($server, $params) {
        $server -> events -> add("name_of_event");
        return true; 
    }

Пример тригера ивента

    <?php
    function script_example_invoke($server, $params) {
        $server -> events -> trigger("name_of_event", $data);
        return true; 
    }

Пример подписки обработчика события

    <?php
    function script_example_init($server, $params) {
        $server -> events -> new_handler("name_of_event", function($event) {
            var_dump($event -> data);
        });
        return true; 
    }