Core

Ядро 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();
    

Командная строка. CLI

Класс 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 в командной строке можно воспользоваться алгоритмом:

  1. наберите chmod +x /path/to/protected/ext/cli/sheduler.php; это делает файл обработчика исполняемым, что необходимо для его запуска по cron;
  2. наберите which php; это возвратит путь к файлу интерпретатора, работающему в командной строке, например /usr/local/bin/php, этот путь нужно указать в константе PHP_CLI_SHEDULER в файле /ext/cli/index.php;
  3. в папке /ext/cli имеется файл cron_do (можно создать другой файл), в котором указаны параметры для запуска файла-обработчика раз в минуту и отправки уведомлений на почту, при необходимости отредактируйте их:
    
    MAILTO=some@mail_adress_if_need
    * * * * * /usr/local/bin/php /path/to/protected/ext/cli/sheduler.php
    
  4. наберите crontab cron_do; это обновит задания cron
  5. наберите crontab -l для проверки, что задание в cron обновилось

Функции

Запускаемые через командную строку 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.

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

Класс производит определение константы XTABLES_ROOT.

Также класс содержит в себе автозагрузчик классов.
Автозагрузка системных классов xTables обеспечивается независимо от расположения каталога xtables, базовая директория определяется автоматически.
Для обеспечения загрузки классов через автозагрузчик xTables namespaces классов проекта должны соответствовать относительному базовой директории, определяемой в константе XTABLES_PATH, пути.

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

Класс содержит глобальный обработчик не перехваченных исключений и обработчик ошибок.

Класс 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 и состоит из следующих значений:

  • boolean debug - включение и отключение режима разработки для подробного отображения ошибок и исключений;
    
    /**
     * debug mode for show detailed info
     */
    'debug' => true,
    
  • boolean profile - включение и отключение режима профилирования (записывается время исполнения и использованная память);
    
    /**
     * reduce performance!!!
     * profile execution
     */
    'profile' => [
        /**
         * common execution
         */
        'exc' => true,
        /**
         * execution of each db query
         */
        'db' => true
    ],
    
  • array db - массив настроек подключения к базам данных, который состоит из:
    • свободное название подключения в качестве ключа;
    • массив параметров в качестве значения, включающий параметры dsn, user, pass, options
    
    /**
     * 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
        ]
    ],
    
  • array access_ses - настройки для авторизационных сессий; данная настройка служит для изменения значений по умолчанию и может состоят из параметров:
    • array engine - по умолчанию, если данный параметр не определен, то для сохранения авторизационных сессий будет использоваться текущий провайдер кеша; для использования другого провайдера нужно определить его настройки здесь, указав параметры:
      • type - название, соответствующее одной из констант класса Cache (Cache::FILE, Cache::REDIS, Cache::MEMCACHE, Cache::DB);
      • server - при необходимости можно определить параметры сервера соответствующего провайдера;
    • boolean paralell - разрешены ли паралелльные авторизационные сессии одного и того же пользователя; по умолчанию запрещены;
    • int min_life - минимальное время жизни сессии в секундах; по прошествии этого времени сессия будет обновляться;
    • int 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
    ],
    
  • boolean buffer - требуется ли буфферизация всего вывода, может быть необходимо, если xTables интегрируется с каким-то старым кодом, который производит вывод данных произвольно;
    
    /**
     * buffering of all output if true
     */
    'buffer' => false,
    
  • array 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
    ],
    
  • string lang - сокращенное обозначение языка локализации по умолчанию, если не определено, то будет использоваться ru
    
    /**
     * default lang
     * if not set uses ru
     */
    'lang' => 'en',
    
  • array 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'
    ],
    
  • boolean local_only - если нужно ограничить работу приложения только внутри локальной сети, то нужно определить данный параметр со значением true
    
    /**
     * use this params for using app in local net only
     */
    'local_only' => true,
    
  • boolean https - для принудительного перехода на протокол https при авторизации
    
    /**
     * set true if required https only
     */
    'https' => false,
    
  • array 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'
         * 
         */
    ],
    
  • int onpage - количество строк для показа в таблице по умолчанию для компонента TableView
    
    /**
     * global settings for number of shown rows in tables forms; max 200
     * can be edited in settings in Particular agents
     */
    'onpage' => 200
    
  • int page_range - количество страниц по умолчанию в строке пагинации для компонента TableView
    
    /**
     * page range in pagination index row
     * current page + page range to right
     *              - page range to left
     */
    'page_range' => 5,
    
  • string empty_show - показывамая строка в случае, если значение поля пусто, для компонента TableView
    
    /**
     * default html for empty values
     */
    'empty_show' => '•••••',
    
  • string 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>',
    
  • string 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>',
    
  • string 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',
    
  • int form_rsa_keys_valid - длительность в секундах, в течение которой действительны открытый и закрытый ключи, используемые для шифрования значений передаваемых с клиента html форм
    
    /**
     * period of validity for rsa form keys (in sec)
     * by default 86400 sec
     */
    //'form_rsa_keys_valid' => 86400,
    
  • int max_file_cache - максимальное количество файлов в каждом из кешей (разбит по каталогам: sql, output, other)
    
    /**
     * max qty in each type (sql, output, other) of file cache
     * by default 3000
     */
    //'max_file_cache' => 5000,
    
  • string 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',
    
  • boolean 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,
    
  • array nontrack_targets - массив с относительными именами путей (без домена), исполнение запросов по которым не нужно записывать во включенном режиме rec_exc;
    если не определен, то по умолчанию не записываются запросы с адресов:
    • /logs/performance-ajax-data
    • /logs/performance
    
    /**
     * array of exclusion service targets from record to database performance table
     */
    'nontrack_targets' => [
        '/logs/performance-ajax-data' => true,
        '/logs/performance' => true
    ]
    
  • int 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
    
  • string 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'];