Merge pull request #756 from createit-ru/master

smartSessions докуменация (ru, en)

docs/components/smartsessions.md

@@ -0,0 +1,66 @@
+---
+title: smartSessions
+description: Расширенное управление сессиями MODX
+author: createit-ru
+modstore: https://modstore.pro/packages/utilities/smartsessions
+
+---
+# smartSessions
+
+Компонент расширяет стандартный обработчик сессий ```modSessionHandler```, добавляя следующие колонки в таблицу с сессиями (используется таблица с именем ```modx_smart_sessions```):
+
+* ```ip``` — ip адрес пользователя;
+* ```user_agent``` - User-Agent браузера;
+* ```user_id``` — id пользователя, если он авторизован.
+
+Благодаря этому можно получить расширенную информацию о посетителях на вашем сайте, а также задать различное время хранения сессий для разных посетителей сайта.
+
+## Установка
+
+1. Установите пакет из репозитория.
+2. В системной настройке ```session_handler_class``` поставьте значение ```smartSessionHandler```.
+3. Проверьте, что данные начали собираться в таблицу ```modx_smart_sessions```. При этом таблица ```modx_sessions``` больше не используется, ее можно очистить.
+
+## Удаление
+
+Верните стандартное значение ```modSessionHandler``` в системной настойке ```session_handler_class```, после чего можете удалить пакет.
+
+## Настройки
+
+Для настройки компонента перейдите в раздел "Системные настройки", пространство имен "smartsessions".
+
+* ```smartsessions_bot_signatures``` — список сигнатур поисковых ботов, разделенных вертикальной чертой, для поиска (через LIKE) по полю ```user_agent```. Добавьте сюда ботов, которые часто посещают ваш сайт.
+
+* ```smartsessions_bots_gc_maxlifetime``` — время жизни сессий ботов, указанных в настройке ```smartsessions_bot_signatures```. Уменьшая его вы уменьшите срок хранения сессий ботов и сократите размер таблицы с сессиями.
+
+* ```smartsessions_empty_user_agent_gc_maxlifetime``` — время жизни сессий с пустым User-Agent. Как правило, его можно задать таким же, как и для ботов.
+
+* ```smartsessions_authorized_users_gc_maxlifetime``` — время жизни сессий авторизованных пользователей. Вы можете увеличить его
+и сделать значение больше, чем в настройке ```session_gc_maxlifetime```.
+
+Стандартное время жизни сессий по прежнему определяется настройкой ```session_gc_maxlifetime```.
+
+### Пример сценария настройки компонента:
+
+* ```session_gc_maxlifetime``` — стандартное значение 604800 (7 дней);
+* ```smartsessions_bots_gc_maxlifetime``` — 10800, сессии ботов хранятся 3 часа и занимают минимум места в базе;
+* ```smartsessions_empty_user_agent_gc_maxlifetime``` — 10800, сессии с пустым User-Agent хранятся 3 часа и занимают минимум места в базе;
+* ```smartsessions_authorized_users_gc_maxlifetime``` — 2592000, сессии авторизованных пользователей хранятся 30 суток, что позволит дольше сохранять авторизацию и список покупок в корзине.
+
+## Известные проблемы
+
+Пункт меню "Управление" / "Завершить все сеансы" перестанет работать. Происходит это по той причине, что данное действие работает только со стандартным обработчиком сессий ```modSessionHandler```, что жестко прописано в коде.
+
+
+# Полезное
+
+SQL запрос для просмотра количества сессий, сгруппированных по user_agent, который позволит найти самые частотные User-Agent в вашей базе:
+
+``` sql
+SELECT `user_agent`, COUNT(*) 
+FROM `modx_smart_sessions` 
+GROUP BY `user_agent` 
+ORDER BY `COUNT(*)` DESC
+```
+
+![Пример результата выполнения sql-запроса](https://file.modx.pro/files/3/c/e/3ceeaaa952ac502b07822eebc7247bad.jpeg)

docs/en/components/smartsessions.md

@@ -0,0 +1,65 @@
+---
+title: smartSessions
+description: Advanced MODX session management
+author: createit-ru
+modstore: https://modstore.pro/packages/utilities/smartsessions
+
+---
+# smartSessions
+
+The component extends the standard session handler ```modSessionHandler```, by adding the following columns to the sessions table (the new table is called ```modx_smart_sessions```):
+
+* ```ip``` — user ip address;
+* ```user_agent``` - browser User-Agent;
+* ```user_id``` — user id if authorized.
+
+Using this data, you can obtain expanded information about visitors to your site. And most importantly, you can set different session storage times for different site visitors.
+
+## Installation
+
+1. Install the package from repository (modstore.pro or extras.modx.com).
+2. In system setting ```session_handler_class``` set the value ```smartSessionHandler```.
+3. Check that the data has started to be collected in the table ```modx_smart_sessions```. The ```modx_sessions``` table is no longer used and can be cleared.
+
+## Removal
+
+Return the default value of ```modSessionHandler``` in the system setting ```session_handler_class```, after which you can remove the package.
+
+## Settings
+
+To configure the component, go to the "System Settings", "smartsessions" namespace.
+
+* ```smartsessions_bot_signatures``` — a list of search bot signatures, separated by a vertical bar, for searching (via LIKE) by the ```user_agent``` field. Add bots that frequently visit your site.
+
+* ```smartsessions_bots_gc_maxlifetime``` — lifetime of bot sessions specified in the ```smartsessions_bot_signatures``` setting. By decreasing it, you will reduce the storage period of bot sessions and reduce the size of the table with sessions.
+
+* ```smartsessions_empty_user_agent_gc_maxlifetime``` — lifetime of sessions with an empty User-Agent. For example, it can be set the same as for bots.
+
+* ```smartsessions_authorized_users_gc_maxlifetime``` — lifetime of sessions of authorized users. You can increase it and make the value greater than in the ```session_gc_maxlifetime``` setting.
+
+The standard session lifetime is still determined by the ```session_gc_maxlifetime``` setting.
+
+### Example component configuration script:
+
+* ```session_gc_maxlifetime``` — standart value 604800 (7 days);
+* ```smartsessions_bots_gc_maxlifetime``` — 10800, bot sessions are stored for 3 hours and take up minimal space in the database;
+* ```smartsessions_empty_user_agent_gc_maxlifetime``` — 10800, sessions with an empty User-Agent are stored for 3 hours and take up minimal space in the database;
+* ```smartsessions_authorized_users_gc_maxlifetime``` — 2592000, sessions of authorized users are stored for 30 days, which will allow you to save authorization and the shopping list in the cart longer.
+
+## Known Issues
+
+The menu item "Manage" / "Logout All Users" will no longer work. This happens because this action only works with the standard session handler ```modSessionHandler```, which is hard-coded in the code.
+
+
+# Useful
+
+SQL query to view the number of sessions grouped by user_agent, which will allow you to find the most frequent User-Agents in your database:
+
+``` sql
+SELECT `user_agent`, COUNT(*) 
+FROM `modx_smart_sessions` 
+GROUP BY `user_agent` 
+ORDER BY `COUNT(*)` DESC
+```
+
+![SQL query result](https://file.modx.pro/files/3/c/e/3ceeaaa952ac502b07822eebc7247bad.jpeg)