Ядро xTables раположено в каталоге xtables, в котором находятся три каталога /xtables/base, /xtables/components, /xtables/config и файл xTables.php.
Приложение построено с использованием иерархической парадигмы HMVC. Для доступа к классам используется входной скрипт /index.php и mod_rewrite.
Для правильной переадресации запросов нужно использовать правило:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !favicon.ico
RewriteRule ^(.*)$ index.php?r=/$1 [QSA,L]
Код входного скрипта является небольшим и его основная задача - определить базовые константы и запустить xTables.
Необходимо определить константы:
ROOT_PATH
- абсолютный путь до корневой веб директории сервера;
XTABLES_BASE
- абсолютный путь до каталога, где размещаются:
/accessory
- вспомогательный каталог, в том числе для кеша;
/config
- каталог с настройками;
/xtables
- каталог с ядром xTables (может быть перемещен и в другую директорию).
/app
или с другим названием или несколько каталогов проекта
при необходимости);
/Documents
- каталог для хранения вложений (файлов, документов);
при необходимости осуществлять хранение файлов в другой папке, в том числе находящейся
вне веб директории, необходимо в файле настроек /config/config.php
указать абсолютный путь до этой папки, включая ее название, в параметре server_doc_folder
;
/**
* root path
* uses in many parts of xtables
*/
define('ROOT_PATH', __DIR__);
/**
* path to base folder
*/
define('XTABLES_BASE', __DIR__ . '/protected');
/**
* main xtables file
*/
include XTABLES_BASE . '/xtables/xTables.php';
/**
* composer autoload
*/
include XTABLES_BASE . '/vendor/autoload.php';
/**
* xtables initiate and execute http request
*/
xtables\xTables::start();
Класс xtables\base\Sheduler
обеспечивает возможность периодического выполнения функций и файлов в командной строке.
Для этого необходимо подключить соответствующую функцию или файл в расписании в /cofig/shedule.json
.
Подробнее см. Sheduler.
Для работы Sheduler
в типовых расширениях /ext/cli
существует файл-обработчик, который будет запускать данный класс.
Остается только обеспечить его периодический запуск, например, по cron, раз в минуту, несколько минут.
Также в папке /ext/cli
имеется файл index.php
, в котором необходимо отредактировать значения двух
констант:
PHP_CLI_SHEDULER
- путь к файлу интерпретатора, работающему в командной строке (как узнать, см. далее по тексту);
ROOT_PATH
- путь к корневой веб-директории, необходим, чтобы имелась возможность работать с xTables в командной строке
как обычно в веб-окружении.
Запуск файла-обработчика sheduler.php
по cron может быть сделан через панель управления, например, ISPManager или командную строку.
Для запуска файла-обработчика sheduler.php
по cron в командной строке можно воспользоваться алгоритмом:
/usr/local/bin/php
, этот путь нужно указать в константе
PHP_CLI_SHEDULER
в файле /ext/cli/index.php
;
/ext/cli
имеется файл cron_do
(можно создать другой файл),
в котором указаны параметры для запуска файла-обработчика раз в минуту и отправки уведомлений на почту,
при необходимости отредактируйте их:
MAILTO=some@mail_adress_if_need
* * * * * /usr/local/bin/php /path/to/protected/ext/cli/sheduler.php
Запускаемые через командную строку callable функции являются обычными и не отличаются от запускаемых в веб окружении.
Для обеспечения работы модулей и компонентов xTables и приложения как обычно (в веб окружении) в файлах, запускаемых через Sheduler
в командной строке необходимо подключать в начале каждого такого файла файл /ext/cli/index.php
, описанный выше.
Этот файл инициализирует xTables, определяет базовые константы и позволяет работать как в обычном веб-окружении.
Для удобства такие файлы можно размещать в той же папке /ext/cli
.
/**
* include cli index file which defines paths, include autoloaders and initiate xtables
*/
include __DIR__ . '/index.php';
Главным классом является класс xtables\xTables
.
Этот класс, используя компоненты, обеспечивает разбор и фильтрацию входных параметров, проверку уровня доступа и подключение соответствующего роуту класса и метода.
Класс производит определение константы XTABLES_ROOT
.
Также класс содержит в себе автозагрузчик классов.
Автозагрузка системных классов xTables обеспечивается независимо от расположения каталога xtables,
базовая директория определяется автоматически.
Для обеспечения загрузки классов через автозагрузчик xTables namespaces классов проекта должны соответствовать
относительному базовой директории, определяемой в константе XTABLES_PATH
, пути.
При необходимости автозагрузка классов проекта может быть обеспечена через Composer.
Класс содержит глобальный обработчик не перехваченных исключений и обработчик ошибок.
'https' => true
в конфигурационном файле /config/congig.php
главный класс будет обеспечивать передачу cookies только при наличии https.
Что может вызывать неработоспособность приложения при отсутствии сертификата безопасности.
Класс xtables/xTables
содержит следующие публичные статические свойства:
$app
- экземпляр класса, который становится доступным после вызова xTables::initiate()
или xTables::start()
(создает экземпляр класса и запускает роутер);
$config
- массив с глобальными настройками, включая настройки доступа к базам данных и прочие;
хранится в файле /config/config.php
;
$appConfig
- массив с любыми специфическими настройками приложения, относящимися к его бизнес логике;
хранится в файле /config/app-config.json
;
$response
- экземпляр класса xtables\base\Response
, обеспечивающий запись данных
в выходной поток и присвоение заголовков;
$access
- создаваемый при инициализации xTables экземпляр класса xtables/components/auth/model/Access
,
который используется для проверки доступа к классам xTables и может быть использован в компонентах проекта;set()
и check()
;
xTables::$access->set(['LEVEL1']);
if (!xTables::$access->check()) {
// some action
}
$lang
- массив со всеми значениями, используемыми для локализации; при инициализации приложения
формируется минимальный массив, который по необходимости, в зависимости от вызываемых классов, в том числе
классов проекта, дополняется данными;
$langDef
- определение текущего языка; по умолчанию используется ru
; определяется по
значению в куки lang
, если данная куки не определена, то используется значение из глобальных параметров.
Массив настроек располагается в файле /config/config.php
и состоит из следующих значений:
debug
- включение и отключение режима разработки для подробного отображения ошибок и исключений;
/**
* debug mode for show detailed info
*/
'debug' => true,
profile
- включение и отключение режима профилирования
(записывается время исполнения и использованная память);
/**
* reduce performance!!!
* profile execution
*/
'profile' => [
/**
* common execution
*/
'exc' => true,
/**
* execution of each db query
*/
'db' => true
],
db
- массив настроек подключения к базам данных, который состоит из:
/**
* pool of data base connections
*/
'db' => [
'main' => [ // free name for current connection
'dsn' => 'mysql:dbname=;host=localhost;charset=UTF8', // add base name
'user' => '', // add user name
'pass' => '', // add pass
/**
* by default if not set is empty array
* may be set specific options for current db pdo driver
*/
//'options' => []
],
'mssql' => [
'dsn' => 'sqlsrv:server=(local)\sqlexpress;database=', // add base name
'user' => '', // may be empty
'pass' => '' // may be empty
],
'pgsql' => [
'dsn' => 'pgsql:dbname=;host=localhost', // add base name
'user' => '', // add user name
'pass' => '', // add pass
]
],
access_ses
- настройки для авторизационных сессий;
данная настройка служит для изменения значений по умолчанию и может состоят из параметров:
engine
- по умолчанию, если данный параметр не определен,
то для сохранения авторизационных сессий будет использоваться текущий провайдер кеша;
для использования другого провайдера нужно определить его настройки здесь, указав
параметры:
type
- название, соответствующее одной из констант класса
Cache
(Cache::FILE
, Cache::REDIS
,
Cache::MEMCACHE
, Cache::DB
);
server
- при необходимости можно определить параметры сервера
соответствующего провайдера;
paralell
- разрешены ли паралелльные авторизационные
сессии одного и того же пользователя; по умолчанию запрещены;
min_life
- минимальное время жизни сессии в секундах;
по прошествии этого времени сессия будет обновляться;
max_life
- максимальное время жизни сессии в секундах;
по прошествии этого времени сессия будет устаревать и удаляться.
/**
* special sessions for access purporses
* @since version 1.5.3
*/
'access_ses' => [
/**
* by default (if not set) use cache engine settings
*/
'engine' => [
'type' => Cache::REDIS
/*
* OR
*
'type' => Cache::MEMCACHE,
'server' => [
[
'host' => '127.0.0.1',
'port' => 11211,
'weight' => 100
]
]
*
* OR
*
'type' => Cache::REDIS,
'server' => [
'params' => [
],
'options' => [
]
]
*
* OR
*
'type' => Cache::DB,
'server' => 'pgsql'
*
*/
//],
/**
* set true to allow parallel user access sessions
* by default (if not set) false
*/
'paralell' => false,
/**
* min life in sec; after regenerate
* by default (if not set) 120
* must be 7 or more
*/
'min_life' => 60,
/**
* max life in sec; after clear
* by default (if not set) 1200
* must be 21 or more
*/
'max_life' => 80
],
buffer
- требуется ли буфферизация всего вывода, может быть необходимо, если
xTables интегрируется с каким-то старым кодом, который производит вывод данных произвольно;
/**
* buffering of all output if true
*/
'buffer' => false,
app
- мета описания приложения:
name
- название приложения, оно будет использоваться в качестве title страницы по умолчанию, а также
в других случаях, например, в уведомлении об электронной подписи, письмах-уведомления и др.;
meta_description
- будет использоваться как значение по умолчанию в теге meta description
keywords
- будет использоваться как значения по умолчанию в теге keywords
/**
* app meta settings
*/
'app' => [
/**
* app name
*/
'name' => 'xTables', // edit app name
/**
* default meta for pages
* can be changed for every page in Particular agents
*/
'meta_description' => 'xTables', // edit
'keywords' => 'xTables' // edit
],
lang
- сокращенное обозначение языка локализации по умолчанию, если не определено, то
будет использоваться ru
/**
* default lang
* if not set uses ru
*/
'lang' => 'en',
smtp
- параметры отправки почты через SMTP для изменения дефолтных значений
port
- порт, по умолчанию 465
;
secure
- по умолчанию ssl
, могут быть использованы значения:
ssl, tls, false
.
/**
* smtp settings for mailing
* port int 465 as default if not set
* secure string ssl as default if not set, may be ssl|tls|false (not use secure)
*/
'smtp' => [
'port' => 465,
'secure' => 'ssl'
],
local_only
- если нужно ограничить работу приложения только внутри локальной сети,
то нужно определить данный параметр со значением true
/**
* use this params for using app in local net only
*/
'local_only' => true,
https
- для принудительного перехода на протокол https при авторизации
/**
* set true if required https only
*/
'https' => false,
cache
- определение параметр драйвера кеша обоих видов: специального и обычного кеша,
подробнее см. Cache.
/**
* cache engine; default - file
* may be used:
* Cache::FILE,
* Cache::MEMCACHE (php ext memcache)
* Cache::REDIS (composer require predis/predis)
* Cache::DB (db)
*/
'cache' => [
'type' => Cache::REDIS
/*
* OR
*
'type' => 'memcache',
'server' => [
[
'host' => '127.0.0.1',
'port' => 11211,
'weight' => 100
]
]
*
* OR
*
'type' => 'redis',
'server' => [
'params' => [
],
'options' => [
]
]
*
* OR
*
'type' => Cache::DB,
'server' => 'pgsql'
*
*/
],
onpage
- количество строк для показа в таблице по умолчанию для компонента TableView
/**
* global settings for number of shown rows in tables forms; max 200
* can be edited in settings in Particular agents
*/
'onpage' => 200
page_range
- количество страниц по умолчанию в строке пагинации для компонента TableView
/**
* page range in pagination index row
* current page + page range to right
* - page range to left
*/
'page_range' => 5,
empty_show
- показывамая строка в случае, если значение поля пусто, для компонента TableView
/**
* default html for empty values
*/
'empty_show' => '•••••',
ajdi_preloader
- большой прелоадер (запускается в период работы ajax dispatcher)
/**
* html string for ajax_dispatcher preloader
* can be used .timer to show system timer in sec & milisec
* if !defined use standart one
*/
//'ajdi_preloader' => '<span class="xtables-preloader"><i class="fa fa-cog fa-spin"></i></span>'
// . '<div class="h3">WAIT... <span class="badge timer"></span></div>',
ajdi_preloader_inicon
- маленький прелоадер (запускается в период работы ajax dispatcher)
/**
* html string for ajax_dispatcher preloader for in icon type (small)
* if !defined use standart one
*/
//'ajdi_preloader_inicon' => '<i class="fa fa-refresh fa-spin"></i>',
server_doc_folder
- абсолютный путь к папке с документами
/**
* document folder ABSOLUTE PATH (inc. use outside of web folder); by default if not set - XTABLES_BASE . '/Documents'
* ******************************************************
* provided work with one document's folder only; if change this value move documents there
* ******************************************************
*/
//'server_doc_folder' => '/absolute/path/Documents',
form_rsa_keys_valid
- длительность в секундах, в течение которой действительны
открытый и закрытый ключи, используемые для шифрования значений передаваемых с клиента html форм
/**
* period of validity for rsa form keys (in sec)
* by default 86400 sec
*/
//'form_rsa_keys_valid' => 86400,
max_file_cache
- максимальное количество файлов в каждом из кешей (разбит по каталогам:
sql, output, other)
/**
* max qty in each type (sql, output, other) of file cache
* by default 3000
*/
//'max_file_cache' => 5000,
date_format
- формат даты для отображения в компонентах xTables по умолчанию
/**
* date format for show result from DB and js datepicker mask for inputs with datetime
* by default (if not set) d.m.Y
* time format always H:i:s
* ******************************************************
* CAN BE USED ONLY!!!
* d - date
* m - month
* Y - year
* delimiters /._-: (don't use space)
* ******************************************************
*/
'date_format' => 'm-d-Y',
breaking_input_filter
- для отключения грубого фильтра входящих значений
нужно определить данный параметр со значением false
/**
* breaking input filter add _ to some registered values for strong protection
* by default it is on
* you can turn it off by defining this parametr with value false
*/
//'breaking_input_filter' => false,
nontrack_targets
- массив с относительными именами путей (без домена),
исполнение запросов по которым не нужно записывать во включенном режиме rec_exc
;/xtables-
./config/base/debug-panel.php
.#xtables-debug-panel
.
/**
* array of exclusion service targets from record to database performance table
*/
'nontrack_targets' => [
'/logs/performance-ajax-data' => true,
'/logs/performance' => true
]
check_cache_every
- осуществлением очистки кеша при загрузке формы входа
через заданный промежуток времени в секундах, по умолчанию 3 часа (10800 сек)
/**
* check cache for:
* clear invalid if current cache engine not execute auto cleaning
* such as FileEngine and DbEngine
* clear exeed file cache
* by default 10800 sec
*/
//'check_cache_every' => 10800
access_data_in
- для добавления данных в авторизационную сессию
можно определить данный параметр, указав в нем имя файла с абсолютным путем или callable
,
которые должны возвращать array
/**
* filename with absolute path or callable
* which must return array for adding to session data
* during authorization
*/
'access_data_in' => XTABLES_BASE . '/config/add-sesdata.php'
//'access_data_in' => 'Some\Callable::func'
В приложении используется отложенное формирование данных локализации, которые добавляются в массив локализации по мере необходимости. В случае наличия в массиве блока с данными локализации повторная загрузка не производится.
Главный класс xtables/xTables
обеспечивает функционирование файлов локализации.
Файлы локализации системных компонентов присутствуют в папке настроек /config
в папке каждого
компонента lang
. При необходимости добавления нового языка необходимо обеспечить добавление файла в формате
json с именем, соответствующим короткому имени языка, в каждую такую папку lang
.
При необходимости загрузки новых специфичных значений локализации для использования локализации можно
воспользоваться методом addLangData($folder)
. В качестве параметра нужно передать
относительный (базовой директории xtables, соответствующей константе XTABLES_BASE
)
путь до папки lang
.
Вызов локализованного значения осуществляется через статическое свойство $lang
.
use xtables\xTables;
xTables::$app->addLangData('/some/path');
xTables::$lang['some_lang_value'];