docs: документация для easyRedirects

docs/components/easyredirects.md

@@ -0,0 +1,81 @@
+---
+title: easyRedirects
+description: Управляйте редиректами (с кодами 301, 302, 307, 308) на вашем сайте на базе MODX Revolution
+author: createit-ru
+modstore: https://modstore.pro/packages/utilities/easyredirects
+repository: https://github.com/createit-ru/easyRedirects
+---
+# easyRedirects
+
+Дополнение easyRedirects для MODX Revolution (создано для MODX 2, но работает и в MODX 3) дает возможность управлять редиректами со старых URL страниц на новые через административную панель.
+
+Весь функционал доступен в единственном разделе, перейти в который можно через основное меню панели управления сайтом "Пакеты" / "easyRedirects". В этом разделе вы сможете создавать и просматривать правила редиректов для различных url адресов.
+
+## Возможности компонента
+
+Итак, компонент позволяет:
+
+* создавать произвольное количество правил редиректа в админке;
+* выбрать код статуса ответа сервера (301, 302, 307, 308);
+* указывать для редиректа просто url адрес, например, catalog/telefony => catalog/phones;
+* использовать регулярные выражения с подстановками, например: ^catalog\/category-(.*)$ => catalog/$1;
+* видеть статистику редиректов (количество срабатываний каждого редиректа, дата и время первого и последнего срабатывания);
+* задать метку для правил редиректа, чтобы в дальнейшем проще их находить (например, пометить «старые редиректы», «редиректы_2023» и т.п.);
+* отследить кто и когда создал или изменил редирект (см. поля createdon, createdby, updatedon, updatedby в таблице modx_easy_redirects);
+* автоматически отслеживать смену url страниц сайта (без учета вложенности дочерних страниц) и создавать правила редиректа, см. системную настройку easyredirects_track, работает также, как в компоненте Redirector;
+* проводить пакетный импорт правил из текста в формате csv.
+
+Само собой вы не сможете управлять редиректами, если запрос "не дойдет" до MODX, например, будет обработан на уровне веб-сервера Nginx или Apache (такое бывает, если запрашивается файл).
+
+## Принцип работы
+
+Общий принцип работы компонента: 
+
+* плагин на событии OnPageNotFound сравнивает запрашиваемый url (без учета query, т.е. без get параметров) с существующими правилами;
+* сначала проверяются правила, в которых url совпадает точно, затем проверяются правила с регулярными выражениями;
+* если нашлось подходящее правило – осуществляется редирект с нужным кодом.
+
+## Системные настройки
+
+У компонента единственная системная настройка:
+
+* easyredirects_track - если включена, то компонент будет автоматически создавать новый редирект при смене uri страницы при редактировании рресурса. Примечание: этот механизм не учитывает смену адреса для дочерних страниц.
+
+## Примеры правил редиректов
+
+**Сменим url для одной страницы:**
+
+> url: catalog/phones/iphone-13-cherniy \
+цель: catalog/phones/iphone-13-black
+
+или 
+
+> url: catalog/telephony \
+цель: catalog/phones
+
+**Правило с регулярным выражением, переместим все страницы внутри раздела по новому адресу:**
+
+>url: ^catalog\\/telephony\\/(.*)$ \
+цель: catalog/phones/$1
+
+Обратите внимание, что регулярное выражение в поле url начинается с символа ^, заканчивается символом $ и все слеши экранированы. При этом целевой адрес уже не является регулярным выражением, но мы можем использовать в нем подстановку $1.
+
+Обратите внимание, что url не должен содержать адрес сайта или слеш / в начале.
+
+## Поддерживаемые коды статуса
+
+**301 Moved Permanently**
+
+Этот код статуса указывает, что запрошенный ресурс был окончательно перемещен на новый постоянный URL, и будущие запросы должны использовать новый адрес.
+
+**302 Found (или Moved Temporarily)**
+
+Этот код статуса указывает, что запрошенный ресурс временно перемещен на другой URL, и клиент должен использовать новый адрес только для текущего запроса. Например, может быть полезно при временных (до нескольких дней) работах со страницей, когда вместо неё лучше показать другую страницу.
+
+**307 Temporary Redirect**
+
+Аналогичен 302 Found, но требует, чтобы клиент сохранял метод HTTP при повторной отправке запроса к новому адресу.
+
+**308 Permanent Redirect**
+
+Этот код статуса аналогичен 301 Moved Permanently, но, как и 307 Temporary Redirect, требует, чтобы клиент сохранял метод HTTP при повторной отправке запроса к новому адресу.