xtables
xTables Base
xtables@yandex.ru
AppService
Описание

Класс xtables\base\AppService обеспечивает сохранение сервисных данных в базе данных в зашифрованном виде.
К подобным сервисным данным относятся логин-пароль от Яндекс.диска, почтового ящика, используемого для передачи писем по SMTP, и любых других аналогичных данных.

Использование

Могут быть использованы следующие прокси интерфейсы.

AppService::save(string $name, array|string $data);

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

  • $name - обязательно название для типа сервисных данных;
    по умолчанию используются названия:
    \xtables\components\upload\model\Yandex::APP_SERVICE_NAME - для Яндекс.диска;
    \xtables\base\SendMail::APP_SERVICE_NAME - для почты по SMTP
  • $data - обязательно строка или массив с данными, которые должны быть зашифрованы, например: ['login' => 'some_login', 'pass' => 'some_pass'] 

AppService::save('some_name', [
    'login' => 'some_login',
    'pass' => 'some_pass'
]);

AppService::getData(string $name)

Для получения сервисных данных в расшифрованном виде.
$name - обязательно наименование типа сервисных данных. 


AppService::getData('some_name');

AppService::exists(string $name)

Для проверки существуют ли данные данного типа. 


AppService::exists('some_name');

AppService::getKey() 


AppService::getKey();

получение служебного ключа для самостоятельно шифрования чего-либо.
Состояние ключа по умолчанию показывается в кабинете пользователя. Если ключ пользователя активен, то он сможет воспользоваться сервисами, данные к которым зашифрованы служебным ключом.

Если сервисные данные сохранены не в первую в настройках базу данных (база данных по умолчанию), то до любых вызовов нужно установить эту БД по ее наименованию в пуле подключений в файле /config/config.php.
Для этого нужно воспользоваться методом AppService::setDbc(string $dbc).
Настройки

Не предусмотрены.

Autocomplete
Описание

Класс xtables\base\Autocomplete используется для организации функции автокомплита при вводе с клиента данных в поля input | textarea.
Функциональность обеспечивается JS функцией-оберткой xtables.autocomplete() и плагином для jquery: Ajax Autocomplete for jQuery Tomas Kirda
https://github.com/devbridge/jQuery-Autocomplete

Использование

Для использования автокомплита необходимо в настройках для компонентов cardNew, cardView, tableView добавить параметр autocomplete:

  • расширенный создать массив параметров:
    • table - название sql таблицы, в которой должен осуществляться поиск; по умолчанию, если данный параметр не определен, то будет взято название таблицы из имени ячейки, которое должно состоять из имени sql таблицы + колонки через точку;
    • column - колонка sql таблицы, в которой должен осуществляться поиск; по умолчанию, если данный параметр не определен, то будет взято название колонки из имени ячейки, которое должно состоять из имени sql таблицы + колонки через точку;
    • min_chars - минимальное количество символов, после ввода которых будет начинаться поиск для осуществления автокомплита; значение по умолчанию равняется 4;
    • time - время в милисекундах, по прошествии которого будет производится поиск; по умолчанию равняется 300;
    • dbc - название подключения к базе данных, по умолчанию будет использоваться первое подключение в настройках подключения к базе данных в файле /config/config.php;
    • top - если необходимо осуществлять поиск только с начала строки, то необходимо определить данный параметр со значением true.
  • упрощенный установить значение для параметра true; будут подставлены значения параметров по умолчанию. 

'autocomplete' => true

'autocomplete' => [
    'table' => 'some_table',
    'column' => 'some_column',
    'min_chars' => 4,
    'time' => 300,
    'dbc' => 'some_conn',
    //'top' => true // from begining only
]

В компонентах cardView, tableView параметры автокомплита добавляются к конкретной ячейке в группе параметров edit. 


'edit' => [
    'items' => [
        'some_table.some_column' => [
            'type' => 'input',
            'max_len' => 50,
            'autocomplete' => [
                'table' => 'some_table',
                'column' => 'some_column',
                'min_chars' => 4,
                'time' => 300,
                'dbc' => 'some_conn'
            ]
        ],

    ]
]
Настройки

Для настройки внешнего вида автокомплита измените классы в файле /css/style.css (или переопределите их):

  • .autocomplete-suggestions
  • .autocomplete-suggestion
  • .autocomplete-selected
  • .autocomplete-suggestions strong
  • .autocomplete-group
  • .autocomplete-group strong
CellAction
Описание

Класс xtables\base\CellAction обеспечивает создание ссылки, следуя параметрам.

Использование

Использование осуществляется в компонентах CardView и TableView.

Настройки

Для настройки в компонентах CardView и TableView нужно создать массив с полным именем (sql табилица + колнка через точку) колонки в качестве ключа и параметрами:

  • string 'path' - путь ссылки (атрибут href);
  • string|array 'params' - параметр или параметры, которые должны быть подставлены к ссылке в следующем виде:
    • если в качестве значения указана строка и она совпадает с названием sql таблицы + колонки из текущей выборки из базы данных, то в качестве параметра будет подставлено соответствующее значение из выборки, если не совпадает, то будет подставлена данная строка; подстановка будет произведена через /;
    • если в качестве значения указан массив, то в нем будут предприняты попытки подставить значения из выборки базы данных, если в качестве значения будет введено действительное значение, совпадающее с полным именем (sql таблица + колонка через точку); если значение будет не найдено, то в качестве значения параметра будет передано введенное значение; передача массив в ссылке здесь не поддерживается, так как параметры не кодируются в json_encoded, base64_encoded строку;
  • string 'css_classes' - строка с названиями классов, которые должны быть добавлены к ссылке;
  • string 'css_id' - идентификатор, которым должна быть помечена ссылка;
  • string 'target' - атрибут target ссылки, в качестве значения нужно использовать любой действительный атрибут, например, _blank; если открытие ссылки в другом окне (вкладке) не нужно, то не нужно определять данный параметр;
  • array 'data_attr' - массив для добавления к ссылке дата атрибутов, префикс data- будет добавлен автоматически, указываеть его в настройках не нужно; можно подставить либо статическое значение либо определить sql таблицу и колонку через точку, в этом случае значение подставится автоматически из выборки из базы данных; 
    
'data_attr' => [
    'some' => 'val', // not use 'data-some'
    'some2' => 'val2',
    'some3' => 'some_table.id' // get from db
]
// will be <a data-some="val" data-some2="val2"></a>


'cell_link' => [
    // link will be /outgoing/card?id=someid
    'outgoing_docs.number' => [
        'path' => 'outgoing/card',
        'params' => [
            'id' => 'outgoing_docs.id'
        ],
        'css_classes' => 'ajax'
        'css_id' => 'some_id',
        'target' => '_blank',
        'data_attr' => [
            'some' => 'someval',
            'else' => 'elseval'
        ]
    ],

    //link will be /outgoing/card/someid
    'outgoing_docs2.number' => [
        'path' => 'outgoing/card',
        'params' => 'outgoing_docs.repeated_id'
    ]
]
CreateDir
Описание

Класс xtables\base\CreateDir обеспечивает проверку на наличие директории на сервере по запрашиваемому пути.

Использование

Может быть использован один из статических методов:

inWebRoot();

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

Для использования необходимо передать относительный путь.
Проверяет и создает папки относительно веб корня ROOT_PATH. Класс вернет true при удачном завершении либо выбросит исключение.
В качестве параметра может быть передана как строка с названием директории, так и массив директорий. 


use xtables\base\CreateDir;

CreateDir::inWebRoot('/somepath/to/dir');

CreateDir::inWebRoot([
    '/somepath/to/dir',
    '/somepath/to/dir2',
    '/some/dir'
]);

inProtected();

В случае отсутствия всех или части директорий они будут созданы внутри защищенного базового каталога в том количестве, которое соответствует запрашиваемому пути. В каждой диктории будет добавлен пустой файл-заглушка index.html.

Для использования необходимо передать относительный путь.
Проверяет и создает папки относительно защищенной базовой директории XTABLES_BASE. Класс вернет true при удачном завершении либо выбросит исключение.
В качестве параметра может быть передана как строка с названием директории, так и массив директорий. 


use xtables\base\CreateDir;

CreateDir::inProtected('/somepath/to/dir');

CreateDir::inProtected([
    '/somepath/to/dir',
    '/somepath/to/dir2',
    '/some/dir'
]);

direct();

Метод создает директории по абсолютному пути без каких-либо заглушек. Возвращает true или выбрасывает исключение. 


use xtables\base\CreateDir;

CreateDir::direct(XTABLES_BASE . '/somepath/to/dir');
CreateDir::direct([
    XTABLES_BASE . '/somepath/to/dir',
    XTABLES_BASE . '/somepath/to/dir2',
    XTABLES_BASE . '/some/dir'
]);
Настройки

Не предусмотрены.

HeadConnector
Описание

Класс xtables\base\HeadConnector служит для подключения css, js файлов и meta тегов в head страницы.
В связи со спецификой приложения, предусматривающей его многократное использование на одном и том же клиенте, механизм подключения файлов в конце body не рассматривался, так как подключаемые файлы кешируются и не замедляют последующую загрузку и эксплуатацию приложения.

Также имеется возможность подключить какой-то файл в любом месте шаблоне макета страницы (layout). В этом случае данный файл будет подключаться к каждой странице, где используется шаблон.

Однако если имеется необходимость включать разные файлы или использовать разные meta теги на разных страницах, определяемых роутами, то нужно использовать HeadConnector.

По умолчанию HeadConnector объединит все css файлы в один и поместит его в веб каталог /tmp.

Будут объединены лишь те JS файлы, которые будут указаны в настройках в параметре combine_js. Какая-либо минификация файлов не производится, при необходимости нужно подключать минифицированные версии файлов, которые будут объединены.

Содержимое head страницы кешируется.
Если необходимо обновить шапку head и созданные в папке /tmp комбинированные файлы, то можно воспользоваться роутом для очистики всего кеша /xtables-settings/clear-all-cache.
Использование

Для использования нужно создать экземпляр класса и передать в него массив с данными мета тегов. 


use xtables\base\HeadConnector;

$head = new HeadConnector([
    'title' => 'some title'
    'description' => 'some description',
    'keywords' => 'some keywords'
], [
    'bootstrap' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js'
], [
    'bootstrap' => 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css'
]);

Ни одни из указанных данных не являются обязательными к передаче. Массивы с данными может вообще не передаваться. Если данные не будут переданы, то будут использованы данные из конфигурационного файла /config/congig.php: 'app' - 'name', 'meta_description', 'keywords'. Второй массив служит для переопределения js, третий - css обозначений из конфигурационного файла /config/js-css-meta.php.

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


$head->get([
    'meta' => ['', ''],
    'css' => [ '', ''],
    'js' => [ '', '']
]);
Однако правильным по логике xTables является не использование класса HeadConnector напрямую,
а подключение файлов через View.
Настройки

/config/all-head.php
/config/js-css-meta.php @since cv1.4.8

В файле /config/js-css-meta.php находится массив со всеми файлами и мета тегами, которые могут быть подключены через HeadConnector.

Массив состоит из:

  • 'meta' - наименования мета тегов; всегда подключаются мета теги favicon, apple_icon, noscript; 
    
'meta' => [
    'favicon' => '<link href="/images/favicon.png" rel="shortcut icon" type="image/x-icon" />', // always connected
    'apple_icon' => '<link rel="apple-touch-icon" href="/images/favicon.png">', // always connected
    'noscript' => '<noscript><meta http-equiv="refresh" content="0; url=/xtables-info/show/eyJjb250ZW50IjoxMH0="></noscript>', // always connected
    'device' => '<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">',
    'fragment' => '<meta name="fragment" content="!">'
],
  • 'css' - css файлы; всегда подключаются:
    • bootstrap - основной файл css фреймворка bootstrap, нужно указать расположение файла;
    • style - расположение файла стилей, который подключается в конце и служит для переопределения любых других стилей bootstrap, xtables...;
    • font_awesome - расположение до файлы для подключения шрифтовых иконок font awesome; 
    
'css' => [
    'style' => '/css/style.css', // always connected
    'bootstrap' => '/css/bootstrap.min.css', // always connected
    'font_awesome' => '/css/font-awesome.min.css', // always connected
    'date_picker' => '/css/jquery.datetimepicker.css',
    'offcanvas' => '/css/offcanvas.min.css',
    'rainbow' => '/css/rainbow/github.css'
]
  • 'js' - js файлы; должен быть указан путь к файлу от веб корня; может быть указан как один путь, так и массив путей;
    всегда подключаются:
    • jquery - расположение к файлу фреймворка jquery;
    • bootstrap - расположение к файлу фреймворка bootstrap;
    • xtables - расположение основного js файла xtables;
    • user - файл для личного кабинета; 
    
'js' => [
        'jquery' => [
            '/js/jquery-3.0.0.min.js',
            '/js/jquery-migrate-3.0.0.js'
        ], // always connected
        'bootstrap' => '/js/bootstrap.js', // always connected
        'xtables' => '/js/xtables.js', // always connected
        'user' => '/js/user.js'
]
  • combine_css - массив из обозначений css файлов, которые могут быть объединены в один комбинированный файл; 
    
'combine_css' => [
    'bootstrap' => true,
    'style' => true,
    'font_awesome' => true,
    'date_picker' => true,
    'offcanvas' => true
]
  • combine_js - массив из обозначений js файлов, которые могут быть объединены в один комбинированный файл; 
    
'combine_js' => [
    'jquery' => true,
    'bootstrap' => true,
    'xtables' => true
]
  • xtables_js_settings - массив с настройками, которые могут быть использованы в js функциях; формируется файл /tmp/xtables.settings.json с настройками, который подгружается при загрузке страницы и настройки становятся доступны в объекте xtables.settings 
    
'xtables_js_settings' => [
    'someSet' => 'someval'
]

// in js functions can be used
xtables.settings.someSet;
xtables\base\Home @deprecated since 1.6.4
config\Home @since version 1.6.4
Описание

Класс Home обеспечивает:
- отображение главной страницы при обращении к корневой веб директории, соответствующей относительному url /;
- возможности обращения к actions без создания роутов.

Использование

Для использования необходимо отредактировать класс cofig\Home путем редактирования метода index и создания дополнительных необходимых методов, если нужно.

Метод index соответствует простому обращению по имени домена без каких-либо параметров. Он может принимать только POST параметры.

Другие методы соответствуют отсутствующим роутам. Они могут принимать все типы параметров. 


class Home extends Controller
{
    public function accessLevels()
    {
        return Access::FREE;
    }
    
    /**
     * special method for root home page
     * only domain or domain/
     * without any other data
     */
    public function index()
    {
        // domain or domain/
    }
    
    public function about()
    {
        // domain/about
    }
    
    public function test()
    {
        // domain/test
    }
Настройки

InputFilter @deprecated since cv1.4.0

Request @since cv1.4.0

Описание

Класс xtables\base\Request производит фильтрацию всех входных параметров типов _GET, _POST, _FILES.
В ходе фильтрации происходит рекурсивный обход массива, таким образом степень вложенности массива не является ограничением.
Фильтр является грубым. При фильтрации используются фильтры PHP filter_var и черный список слов.

Класс осуществляет разбор и фильтрацию параметров роута.

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

  • add_log
  • edit
  • pre_condition
  • pre_order
  • search
  • select
  • structure
  • table
  • table_add
После фильтрации значения суперглобальных переменных _GET, _POST, _FILES, _REQUEST удаляются
для исключения возможности прямого обращения к ним в компонентах проекта.
Использование

В каждом контроллере, который наследует класс \xtables\base\Controller доступны экземпляры классов \xtables\base\Request в свойстве $this->request, \xtables\base\Response в свойстве $this->response.

$this->request->isRouteParam()

Проверка на наличие route_param (Request::ROUTE_PARAM).

$this->request->routeParam()

Получение значения route_param (Request::ROUTE_PARAM), если отсутствует, то возвращает пустую строку.
Также может быть получен из массива параметров $this->request->params[Request::ROUTE_PARAM].

Для работы с данным классом могут использоваться методы, доступные через статический прокси интерфейс, что сделано для облегчения юнит тестирования.
Также методы прокси класса доступны через статический метод proxy(). 

Request::isPost(); // static proxy interface

Request::proxy()->isPost();

Могут быть использованы следующие методы статического прокси интерфейса:

isPost(): bool

Проверка того, что данные переданы методом POST. Для авторизованного пользователя будет также проводиться проверка csrf-токена. Будет возвращено true в случае успеха. 


if ($this->request->isPost()) {
    // some code
}

if (Request::isPost()) {
    // some code
}

csrfHiddenInput(): string

Для авторизованного пользователя будет добавлять в форму скрытый input с csrf-токеном.

Все данные, которые отправляются через ajax запросы, используют метод xtables.ajax(),
который является оберткой над jQuery.ajax() и автоматически добавляет csrf-токен.

isAjax(): bool

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


if ($this->request->isAjax()) {
    // some code
}

if (Request::isAjax()) {
    // some code
}

isAjDi(): bool

Проверка того, что данные переданы методом POST и с использованием аякс диспетчера. Может использоваться для установления состояний на action (адресе урл):
- если есть запрос через аякс диспетчер, то отдается только часть страницы;
- если нет аякс диспетчера, страница загружается полностью, включая лейаут. 


if ($this->request->isAjDi()) {

}

if (Request::isAjDi()) {
    $this->response->json();
} else {
    $this->response->write();
}

primary(array $params): array

Для рекурсивного обхода массива параметров нужно вызвать метод xtables\base\Request::primary(), в который передать массив с данными. 


$this->request->primary([
    'some' => 'value'
]);

$handled = Request::primary([
    'some_param' => 'value',
    'else_param' => 'else_value'
]);

recast(string $param): string

Для очистки единичного значения можно использовать метод xtables\base\Request::recast(), в который передать значение в виде строки. 


$handled = $this->request->recast('some_value');

$handled = Request::recast('some_value');

getCookie(string $name): string

Для получения очищенного значения cookie можно использовать данный метод Request::getCookie(), в который в качестве параметра нужно передать имя cookie. 


$value = $this->request->getCookie('some_name');

$value = Request::getCookie('some_name');

getFilenameFromCookie(string $name): string

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


$value = $this->request->getFilenameFromCookie('some_name');

$value = Request::getFilenameFromCookie('some_name');

isCookie(string $name): bool

Для проверки существования cookie можно использовать данный метод Request::isCookie(), который вернет true в случае наличия соответствующего cookie. 


if ($this->request->isCookie('some_name')) {
    // ***************
}

if (Request::isCookie('some_name')) {
    // ***************
}

clearCookie(string $name): RequestProxy

Удаление куки с определенным именем. 


Request::clearCookie('some_name');

$this->request
    ->clearCookie('some_name1')
    ->clearCookie('some_name2')
    ->clearCookie('some_name3');

Валидация входящих параметров
@since version 1.7.32

param(string $name): Validate

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

Методы класса \xtables\base\Validate

exists(): bool

Простая проверка на существование во входящих параметрах параметра с определенным именем.

notEmpty(): bool

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

isValidEmail(): bool

Проверяет, что входящий параметр с определенным именем является валидным адресом электронной почты.

isValidDate(): bool

Проверяет, что входящий параметр с определенным именем является валидной датой в соответствии с форматом, заданным в /config/config.php в параметре date_format.
По умолчанию используется формат d.m.Y.

isValidLogin(): bool

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

isValidPass(): bool

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


if ($this->request->param('some_name')->exists()) {
    // some code
}

if ($this->request->param('some_name')->notEmpty()) {
    // some code
}

if ($this->request->param('some_date')->isValidDate()) {
    // some code
}
Настройки

Не предусмотрены.

News

Описание

Класс xtables\base\News обеспечивает показ системных новостей и оповещений всем пользователям. После показа новость приобретает статус показанной и более данному пользователю не отображается.

Использование

С данным классом взаимодействует компонент авторизации. Для добавления, редактирования и запуска новостей (оповещений) нужно воспользоваться расширением News.

Настройки

Не предусмотрены

Notices

Описание

Класс xtables\base\Notices обеспечивает показ внутренних системных уведомлений тому, пользователю, которому оно предназначено. Уведомление пропадает из списка после того, как пользователь нажмет на соответствующий пункт для его активации.

Использование

Данный класс взаимодействует с классом xtables\base\Layout и входит в состав инфоблока лейаута (см. Layout). Загрузка и обновление происходят с использованием Ajax dispatcher.

Внутренние уведомления загружаются через ajax
в css идентификатор xtables-notices.

Могут быть использованы статические прокси интерфейсы:

get()

Для ручного (без использования инфоблока лейаута) получения js кода, который будет загружать уведомления в css идентификатор xtables-notices. В качестве аргумента в метод может быть передано время обновления в секундах, по умолчанию составляет 180 сек. 


Notices::get();

Notices::get(60);

add()

Добавления уведомления с список.
В качестве аргументов должен быть передан массив массивов с настройками:

  • url - ссылка для перехода при активации уведомления;
  • user_id - идентификатор пользователя, которому предназначено уведомление;
  • from_user_id - необязательно идентификатор пользователя, от которого поступило уведомление;
  • notice - сам текст уведомления. 

$notices = [];

$notices[] = [
    'url' => '/some/url',
    'user_id' => 15,
    'from_id' => 3, // or without this param
    'notice' => 'some notice text'
];

$notices[] = [
    'url' => '/some/url',
    'user_id' => 16,
    'from_id' => 3, // or without this param
    'notice' => 'some notice text'
];

Notices::add($notices);

Настройки

Не предусмотрены

OpenSslCrypt @deprecated since 1.7.0
Crypt @since 1.7.0
Описание

Класс xtables\base\Crypt обеспечивает:

  • шифрование данных, которые передаются с клиента на сервер , с использованием ассиметричного шифрования; для шифрования данных на клиенте используется библиотека jsencrypt.js; подобным образом могут передавать данные авторизационных форм (пароли, логины и пр.), что обеспечивает защиту от прослушивания трафика, если не используется SSL или как дополнительная мера защиты к SSL;
  • методы для работы с электронной подписью (весь цикл от создания сертификата и закрытого ключа электронной подписи до подписания и проверки файлов). Для электронной подписи используется самоподписанный владельцем сертификат.
В компонент xtables\components\Auth добавлен модуль, автоматизирующий работу с электронной подписью для всех пользователей приложения от создания сертификата и генерации уведомления до блока подписания файла-документа. В большинстве случаев возможностей этого модуля достаточно для организации работы пользователей с электронной подписью. См. подробнее в компоненте Auth.
Использование
Передача шифрованных данных с клиента на сервер

Для передачи шифрованных данных с клиента на сервер можно воспользоваться аякс формой, добавив к форме класс .ajax-form. К полям, которые должны быть зашифрованы, необходимо добавить класс .crypt.

См. AjaxDispatcher

Максимальная длина шифруемых в одном поле данных должна быть не более 465 символов.

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

Ключи для шифрования данных подобным образом сохраняются в кеше сервера. Период устаревания ключей составляет 86400 сек (24 ч). Данное значение можно изменить в настройках в файле /config/config.php в параметре form_rsa_keys_valid. 


'form_rsa_keys_valid' => 3600 // by default 86400
Работа с электронной подписью

Работа с электронной подписью может осуществляться через возможности компонента xtable\components\Auth, который использует методы класса xtables\base\Crypt:

  • setDn() - установить значения DN сертификата (имя, компания, период действия ...) в публичной переменной $this->dn, значения берутся из файла настроек /config/config.php;
  • setConfig() - установить параметры шифрования, значения берутся из файла настроек /config/config.php;
  • generateNewCert() - создает:
    • новый закрытый ключ электронной подписи, шифрует его паролем, помещает в файл с расширением pem в папку /accessory/ds/private/ и публичную переменную этого класса $this->privkey, путь к этому файлу от папки, соответствующей константе XTABLES_BASE, - в $this->filePrKey;
    • соответствующий закрытому ключу сертификат X.509, помещает его в файл с расширением cer в папку /accessory/ds/cert/, путь к этому файлу от папки, соответствующей константе XTABLES_BASE, - в $this->fileCert;
  • setPrivate($filePrKey, $err = true) - получает закрытый ключ электронной подписи из файла и возвращает его; при установке параметра $err как false не выбрасывается исключение в случае ошибки получения ключа;
  • setPublic($certPath, $err = true) - получает открытый ключ проверки электронной подписи из файла сертификата и возвращает его; при установке параметра $err как false не выбрасывается исключение в случае ошибки получения ключа;
  • sign($data) - подписывает переданные данные алгоритмом SHA512 и возвращает подпись;
  • verify($data, $signature) - проверяет по алгоритму SHA512 подпись переданные данных и возвращает результат: 1 (true) - подпись правильна; 0 (false) - подпись не правильна; генерирует исключение в случае ошибки.
Настройки

Осуществляются путем установки параметров в файле настроек /config/config.php и сеттерах класса. 


/**
 * settings for digital signatures
 */
'digital_sign' => [
    'dn' => [
        'countryName' => 'RU', // 2 symb code
        'stateOrProvinceName' => 'Moscow',
        'localityName' => 'Moscow',
        'organizationName' => 'some firm',
        'organizationalUnitName' => 'some',
        'commonName' => 'name', // uses if no specific info got
        'emailAddress' => 'email' // uses if no specific info got
    ],
    'config' => [
        'encrypt_key' => true,
        'digest_alg' => 'sha512',
        'x509_extensions' => 'v3_ca',
        'private_key_bits' => 2048,
        'private_key_type' => OPENSSL_KEYTYPE_RSA
    ],
    'valid' => 730, // period in days
],
Queue
Описание

Класс xtables\base\Queue обеспечивает выполнение задач (функций) в очереди (в фоне). Это может быть удобно для отправки почты.

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

Данный класс поддерживает выполнение только callable функций,
которые выполняются последовательно.
Использование

Для добавления задачи в очередь нужно использовать статический метод Queue::push(), в который нужно передать в качестве параметров:

  • $task - callable функция, нужно указать ее имя с учетом namespace;
  • $params - если необходимо, то в массиве можно указать параметры, которые будут переданы в callable функцию;
  • $maxAttempts - количество попыток на запуск задачи; по умолчанию (если не определено), то составляет 5;
  • $delay - если необходима задержка на выполнение, то нужно указать количество секунд, на которое должно быть отложено выполнение задачи; по умолчанию (если не определено), то задержка выполнения отсутствует. 

use xtables\base\Queue;

Queue::push('some\name\to\SomeClass::someFunc');
Queue::push('some\name\to\SomeClass::someFunc', ['param', 'key' => 'val'], 2, 3600);

Результаты запуска заданий отражаются в файле /accessory/queue-report.json, произошедшие при запуске ошибки - в общем файле логов /accessory/log.md.

Если что-то идет не так, как планировалось, и задания не выполняются,
то необходимо проверить наличие ошибок в файле /accessory/log.md.
Настройки
ReplaceCell
Описание

Класс xtables\base\ReplaceCell обеспечивает автозамену значений, полученых в результате выборки из базы данных, на другие, следуя определенным условиям.

Использование

Для использования необходимо создать массив 'replace' в настройках для компонентов CardView и TableView.

Настройки

В настройках нужно создать массив 'replace' с массивом полных имен (sql таблица + колонка через точку), каждый из которых может иметь следующие параметры (указаны в порядке убывания их приоритета):

  • конкретное значение - если полученное из базы данных значение совпадет с данным, указанным в качестве ключа этого параметра, то будет применена замена, указанная в качестве значения данного параметра, например: 1 => 'Да', если из базы данных получена 1, то показано будет Да.
  • 'function' - масиив для применения к значению callable функции:
    • 'name' - строка с именем callable функции, например: '\app\SomeClass::someFunction';
    • 'params' - массив с параметрами, которые будут переданы в функцию; если имя параметра совпадет с полным именем (sql столбец + колонка через точку), соответствующим одному из значений выборки, то вместо этого имени будет подставлено значение из выборки базы данных;
  • 'numpad' - будет произведено дополнение цифрового значения, полученного из базы данных цифрой 0, в качестве значения должна быть указана длина для автодополнения, например: 6 - любое число с количеством знаков меньше шести будет дополено нолями (000001, 000362, ...);
    данный параметр предустановлен, поскольку является частым случаем для показа идентификаторов и номеров документов, но может быть достигнут и через callable функцию, что будет чуть медленнее;
  • 'cut' - нужно включить данный параметр, если необходимо обрезать строку до заданной в качестве значения этого параметра длины;
  • 'make_array' - будет произведено преобразование значения в массив, который будет обработан и преобразован в строку согласно параметрам:
    • 'explode_by' - разделитель, который будет использоваться при преобразовании строки в массив (в случае, если параметр не определен, то по умолчанию используется знак ',');
    • 'delimiter' - разделитель для элементов полученного в ходе обработки строки массива (в случае, если параметр не определен, то по умолчанию используется тег <br />
    • 'swap' - массив, ключами в котором должны быть значения из строки, которая преобразуется в массив; значения этого массива 'swap', соответствующие искомым, будут потом преобразованы в строку через 'delimiter' и возвращены;
  • 'empty' - если полученное из базы данных значение для данной ячейки является пустым, то будет применена замена, указанная в качестве значения данного параметра;
  • 'any_int' - если полученное из базы данных значение будет числом, то будет применена замена, указанная в качестве значения данного параметра;
  • 'any_string' - если полученное из базы данных значение будет любой строкой, то будет применена замена, указанная в качестве значения данного параметра; 

'replace' => [
    'some_table.some_column' => [
        'some_current_value' => 'Да',
        'function' => [
            'name' => '\app\SomeClass::someFunction',
            'params' => [
                'some_table.some_column',
                'some_param',
                'else_param'
            ]
        ],
        'numpad' => 6,
        'cut' => 50,
        'make_array' => [
            //'explode_by' => ',',
            //'delimiter' => '<br />',
            'swap' => [
                1 => 'some',
                2 => 'else',
                3 => 'more'
            ]
        ],
        'empty' => 'пустое значение',
        'any_int' => 'число',
        'any_string' => 'строка'
    ],
]
Response
Описание

Класс xtables\base\Response обеспечивает запись в выходной поток данных для их отображения в браузере клиента.

Использование

В каждый класс, который вызывается через роуты передается экземпляр класса Response, который доступен через свойство $this->response.
Также он может быть вызван через статическое свойство xTables::$response.

Могут быть вызваны следующие методы:

write(string $output)

Запись любых данных, автоматически добавляется header text/html. 


$this->response->write('some data');

json(string $json)

Запись json кодированной строки, автоматически добавляется header application/json. 


$this->response->json($jsonEncoded);

jsonp(string $json)

Кросс доменная передача json кодированной строки, автоматически добавляется header application/javascript.
Для использования данного метода в качестве входного параметра должен быть указан параметр callback.
Данный параметр формируется и автоматически посылается при использовании абсолютных адресов (http, //) в функциях аякс диспетчера (см. AjaxDispatcher). 


ajDi::getJs('//domain.ru/some');

/* reply */
$this->response->jsonp($jsonEncoded);

redirect(string $location)

Немедленный переход по указанному адресу с остановкой дальнейшего выполения скрипта. 


$this->response->redirect('/some/url');

setCode(int $code)

Добавление кода ответа сервера. 


$this->response->setCode(404);

setHeaders(array $headers)

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


$this->response->setHeaders([
    'content-type' => 'application/javascript'
]);

sendHeaders()

Реальная отправка заголовков. 


$this->response->sendHeaders();

clearHeaders()

Очистка всех подготовленных к передаче заголовков. 


$this->response->clearHeaders();

setNoCacheHeader()

Добавление заголовка для обновления содержимого без учета кеша браузера. 


$this->response->setNoCacheHeader();

post(string $url, array $data)

Отправка сервером запроса методом POST (используется curl). Метод возвращает ответ, возвращающийся в результате запроса по url. 


$this->response->post('//somedomain.com/some/url', [
    'param1' => 'value1',
    'param2' => 'value2'
]);

ajDiReload(string $url = '', array $data = [])

Перезагрузка аякс диспетчера, в котором могут быть откорректированы url и data, которые нужно передать в качестве параметров в этот метод.
Для использования данного метода нужно, чтобы запрос был сделан с клиента с использованием аякс и аякс диспетчера (здесь это проверяется автоматически). 


$this->response->ajDiReload();

$this->response->ajDiReload('/new/url', [
    'new_data' => 'some data'
]);
Настройки

Не предусмотрены.

Router
Описание

Класс xtables\base\Router обеспечивает разбор параметров, поступающих через _GET, _POST, _FILES.
Он также обеспечивает их очистку, через запуск класса xtables\base\Request.

Осуществляется разбор строки url для запуска соответствующего роута и его метода. Если метод не указан, то по умолчанию будет вызван метод index.

Если соответствующий метод в классе будет не найден или роут окажется недействительным,
то приложение выведет сообщение со стандартной ошибкой 404.
Тело сообщения о несуществующей странице 404 может быть отредактировано в файле /config/infoBoxes/404.php.

Поддерживаются следующие типы роутов:

domain
domain/

controller - xtables\base\Home;
action - index

domain/controller/action?param=val&param2=val2

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод класса (все знаки - заменяются на _, чтобы обеспечить корректные имена методов);
params - параметре в массиве.

domain/controller/action/base64encodedparams

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод класса (все знаки - заменяются на _, чтобы обеспечить корректные имена методов);
params - параметры в массиве.

domain/controller/action/route-param

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод класса (все знаки - заменяются на _, чтобы обеспечить корректные имена методов);
params - строка в параметре с именем route_param (Request::ROUTE_PARAM).

domain/controller?param=val&param2=val2

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод index;
params - параметре в массиве.

domain/controller/base64encodedparams

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод index;
params - параметры в массиве.

domain/controller/route-param

controller - соответствующий роуту класс (роуты могут быть добавлены в файле /config/route-map.json);
если роут не будет обнаружен, то будет осуществляться поиск на соответствие имени метода в классе cofing\Home;
action - метод index;
params - строка в параметре с именем route_param (Request::ROUTE_PARAM).

route-param может содержать элементы / в своем составе, все они будут переданы в качестве параметра и могут быть при необходимости обработаны.

Параметры GET могут передавать в роутер традиционно, то есть после знака ? через знак & либо после роута через знак / могут быть переданы в виде jsone_encoded и base64_encoded строки.

Все параметры объединяются в единый ассоциативный массив и становятся доступны в объекте xtables\base\Request, который передается в конструтор xtables\base\Controller.

Использование

Данный класс является системным классом xTables и не предполагает непосредственного взаимодействия с классами проекта app.
С данным классом взаимодействует лишь главный класс xtables/xTables

Настройки

Правила домашней страницы могут быть указаны в файле /cofig/homepage-rules.php.
Настройка осуществляется путем создания роутов.
Добавлять роуты проекта необходимо в файле /config/route-map.php.
Для обеспечения быстрой работы с учетом специфики приложения применяются только прямые роуты, прямо названные в данном файле.

При установке расширений и обновлениях роуты обновляются автоматически. 


"logs": "ext\\logs\\Logs"

RouterInterface @deprecated since cv1.6.0

Controller @since cv1.6.0

Описание

Все классы, которые вызваются через роуты и содержат в себе actions, должны расширять класс xtables\base\Controller, который получает в свой конструктор экземпляр класса xtables\base\Request, включая все входящие параметры в массиве params.

Для определения уровней доступа нужно переопределить методо accessLevels(), который должен возвращать строку с именем доступа или массив с именами доступа. По умолчанию, если данный метод не переопределен, то устанавливается высший уровень доступа.

При отсутствии необходимости ограничения доступа к соответствующему классу в качестве уровня доступа нужно использовать константу xtables\components\auth\Access::FREE.
Использование 

use xtables\base\Controller;
use xtables\components\auth\Access;

class SomeClass extends Controller
{
    public function accessLevels()
    {
        return Access::FREE;
    }

    public function some_action()
    {
        $some = new SomeClass($this->request);
        if ($this->request->isAjDi()) {
            // ................
        } else {
            // ................
        }
        //$this->request->params;
    }


}
Настройки

Не предусмотрены.

SendMail
Описание

Класс xtables\base\SendMail обеспечивает отправку писем через SMTP. Для использования класса необходимо сохранить данные о названии smtp сервера, например: smtp.yandex.ru, названии почтового ящика, через который будут отправляться письма, и пароле к нему. Для сохранения данных могут использовать встроенные возможности, доступные по роуту /xtables-settings/mail. Данные сохраняются в базу данных в таблицу app_service в зашифрованном виде.

Для отправки почты используется библиотека https://github.com/PHPMailer/PHPMailer

Использование

Для использования необходимо создать экзмепляр класса xtables\base\SendMail.

В конструктор класса могут быть переданы параметры:

  • dbc - название подключения к базе данных в пуле подключений; если не указано, то используется первое подключение в настройках; подключение к базе данных необходимо в случае, если авторизационные данные для подключения к почте хранятся в базе данных в зашифрованном виде; это действует только для случаев работы с зарегистрированными пользователями; если необходимо отправлять почту свободно, то нужно сохранять данные авторизации в файле настроек;
  • login - логин к почте, для свободного доступа, когда почта отправляется при отсутствии авторизованного пользователя;
  • pass - пароль к почте, для свободного доступа, когда почта отправляется при отсутствии авторизованного пользователя;
  • host - хост почты, для свободного доступа, когда почта отправляется при отсутствии авторизованного пользователя, например, smtp.yandex.ru.

Для отправки письма можно воспользоваться следующими публичными методами класса:

  • send - метод только для отправки писем без каких-либо дополнительных функций;
  • sendNgetReport - отправляет письма и возвращает массив:
    • 'ok' - массив адресов, по которым письма отправлены успешно;
    • 'fail' - массив адресов, отправить письма на которые не удалось.
    В качестве параметра может быть определен $limit - количество адресов, на которые должны быть отправлены письма (если список состоит из большего количества адресов, то отправка прерывается).
  • mailGenerator - отправляет письма и возвращает через yield пару ключ/значение с результатом отправки: 'ok' => address, 'fail' => address.
    В качестве параметра может быть определен $limit - количество адресов, на которые должны быть отправлены письма (если список состоит из большего количества адресов, то отправка прерывается).
Отправка писем с использованием метода mailGenerator() позволяет получать информацию о каждой отправке и выполнять после этого какие-то действия, не дожидаясь отправки всех писем целиком.
Настройки

Настройка осуществляется путем вызова методов:

  • to() - в функцию нужно передать массив с почтовыми ящиками получателей либо строка, в которой получатели перечислены через запятую;
  • subject() - в функцию нужно передать строку с темой письма;
  • message() - в функцию нужно передать строку с содержанием письма;
  • attach() - массив со списком путей к файлам (абсолютные пути) или один путь к файлу приложения. 

use xtables\base\SendMail;

$mail = new SendMail();

//$mail = new SendMail(['dbc' => 'some_name']);
//$mail = new SendMail([
  //  'login' => 'some_login',
  //  'pass' => 'some_pass',
  //  'host' => 'smtp.yandex_or_other'
//]);

$mail->to('some@mail.ru')->subject('some subject')->message('some message')->attach('/path_to_web_root');

function someFunctionWithMailGenerator($report = []) {
    foreach ($mail->mailGenerator as $result => $address) {
        if ($result === 'ok') {
            // some action
        } else {
            $report['fail'][] = $address;
        }
    }
}
Session
Описание

Класс xtables\base\Session обеспечивает работу с сессиями.

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

Использование
Для работы с сессия могут использоваться статические прокси интерфейсы, что сделано в целях обеспечения возможности юнит тестирования. Также методы прокси класса доступны через статический метод proxy(). 

Session::get('some_key'); // static proxy interface

Session::proxy()->get('some_key');

Для работы с сессиями могут использоваться следующие статические интерфейсы:

  • get() - получение значения по ключу, если подобный ключ существует в сессии 
    
Session::get('some_name');
  • set() - сохранение данных в сессию; может быть передано один ключ и значение либо массив из ключей и значений 
    
Session::set('some_name', 'some_value');
Session::set([
    'some_name1' => 'value1',
    'some_name2' => 'value2',
    'some_name3' => 'value3',
    'some_name4' => 'value4'
]);
  • clear() - очистка данных сессии; может быть передано как одно, так и несколько значений 
    
Session::clear('some_name');
Session::clear(['some_name1', 'some_name2', 'some_name3']);
Session::clear('some_name1, some_name2, some_name3');
  • exists() - проверка наличия ключа в сессии, возвращает true при нахождении 
    
if (Session::exists('some_name')) {
    // some action
}
  • destroy() - очистка всех данных сессии 
    
Session::destroy();
Настройки

Не предусмотрены.

Sheduler
Описание

Класс xtables\base\Sheduler обеспечивает периодическое выполнение функций и файлов через интерфейс командной строки (CLI).

Для работы Sheduler нужно создать файл-обработчик, который будет запускать данный класс. В свою очередь необходимо обеспечить периодический запуск данного обработчика, например, по cron, раз в минуту, несколько минут. Подробнее см. CLI.

Данный класс поддерживает выполнение callable функций и файлов.

Файлы запускаются и выполняются параллельно друг другу,
функции запускаются последовательно.
Использование

Для использования необходимо подключить в файле /config/shedule.json callable функцию, указав ее имя с учетом namespace, или файл, указав относительный директории XTABLES_BASE путь к нему, и определить параметр запуска.

Результаты запуска заданий отражаются в файле /accessory/shedule-report.json, произошедшие при запуске ошибки - в общем файле логов /accessory/log.md.

Если что-то идет не так, как планировалось, и задания не выполняются,
то необходимо проверить наличие ошибок в файле /accessory/log.md.
Настройки

При подключении можно определить параметры запуска. В качестве параметров запуска поддерживаются:

  • each - каждый раз при выполнении расписания;
  • min - запуск через определенное количество минут, необходимо указать цифру и параметр min, например: 5min - каждые 5 минут, 30min - каждые 30 минут, 45min - каждые 45 минут;
  • hour - запуск через определенное количество часов, необходимо указать цифру и параметр hour, например: 1hour - каждый час, 6hour - каждые 6 часов;
  • day - запуск через определенное количество дней, необходимо указать цифру и параметр day, например: 3day - каждые 3 дня, 10day - каждые 10 дней;
  • daily - запуск ежедневно в 00 часов;
  • weekly - запуск еженедельно в воскресенье в 00 часов;
  • monthly - запуск ежемесячно 1 числа в 00 часов.

Пример расписания файла /config/shedule.json: 


{
    "/path/to/xtables/base/file.php": "each",
    "/path/to/xtables/base/file2.php": "weekly",
    "somenamespace\\tocallable::functionName": "3day"
}