Revisions Pro¶

Установка¶

Установить плагин Revisions Pro можно одним из трёх способов: способ через GPM (менеджер пакетов Grav) позволяет быстро установить плагин простой командой в терминале, ручной способ — с помощью zip-файла, а способ через админку — с помощью плагина Admin.

Зависимости¶

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

• Grav CMS >= 1.7.0 — требование к ядру системы
• Admin Plugin >= 1.10.0 — для интерфейса управления версиями
• PHP >= 7.4 — со стандартными расширениями

Установка через GPM (предпочтительно)¶

Чтобы установить плагин через GPM, откройте терминал вашей системы (он же командная строка), перейдите в корень установки Grav и введите:

bin/gpm install revisions-pro

Плагин Revisions Pro будет установлен в папку /user/plugins внутри Grav. Его файлы можно найти по пути /your/site/grav/user/plugins/revisions-pro.

Установка вручную¶

Чтобы установить плагин вручную:

1. Скачайте zip-версию этого репозитория
2. Распакуйте её в /your/site/grav/user/plugins
3. Переименуйте папку в revisions-pro
4. Перейдите в папку плагина и выполните composer install, чтобы установить зависимости

Теперь все файлы плагина должны находиться в:

/your/site/grav/user/plugins/revisions-pro

Плагин Admin¶

Если вы используете плагин Admin, плагин можно установить напрямую: откройте меню Plugins и нажмите кнопку Add.

Конфигурация¶

Прежде чем настраивать этот плагин, скопируйте user/plugins/revisions-pro/revisions-pro.yaml в user/config/plugins/revisions-pro.yaml и редактируйте только эту копию.

Ниже приведена конфигурация по умолчанию и пояснения к доступным параметрам:

enabled: true                    # Включить плагин

# Параметры хранилища
max_revisions_per_page: 50      # Максимум версий на ресурс (0 = без ограничений)
auto_cleanup: true              # Включить автоматическую ежедневную очистку
cleanup_older_than: 90          # Удалять версии старше X дней

# Переключатели фич
track_pages: true               # Отслеживать изменения страниц
track_config: true              # Отслеживать системную конфигурацию и конфигурацию сайта
track_plugins: true             # Отслеживать конфигурацию плагинов и тем

# Параметры интерфейса
show_revision_count: true       # Показывать значок с количеством версий на панели инструментов

Подробности конфигурации¶

Параметры хранилища¶

max_revisions_per_page¶

• Тип: целое число
• По умолчанию: 50
• Описание: максимальное количество версий, сохраняемых для каждого ресурса
• Примечания:
• Когда лимит достигнут, самые старые версии удаляются автоматически
• Установите 0, чтобы количество версий было неограниченным (не рекомендуется для боевого сайта)
• Применяется ко всем отслеживаемым типам контента

auto_cleanup¶

• Тип: логическое значение
• По умолчанию: true
• Описание: включить автоматическую очистку старых версий
• Примечания:
• Выполняется ежедневно в 3:00 по времени сервера через планировщик Grav
• Требует настроенного задания cron для планировщика
• Может также запускаться вручную из CLI

cleanup_older_than¶

• Тип: целое число
• По умолчанию: 90
• Описание: предельный возраст версий в днях для очистки
• Примечания:
• Версии старше этого срока удаляются при очистке
• Применяется и к автоматической, и к ручной очистке
• Учитывайте требования соответствия, устанавливая это значение

Переключатели фич¶

track_pages¶

• Тип: логическое значение
• По умолчанию: true
• Описание: отслеживать изменения содержимого страницы и метаданных страницы
• Примечания:
• Включает все типы страниц (стандартные, модульные и т. д.)
• Отслеживает изменения и содержимого, и метаданных страницы
• Поддерживает многоязычные страницы

track_config¶

• Тип: логическое значение
• По умолчанию: true
• Описание: отслеживать изменения системной конфигурации и конфигурации сайта
• Примечания:
• Отслеживает /user/config/system.yaml и /user/config/site.yaml
• Учитывает конфигурации, специфичные для окружения
• Необходим для отслеживания критичных изменений системы

track_plugins¶

• Тип: логическое значение
• По умолчанию: true
• Описание: отслеживать изменения конфигурации плагинов и тем
• Примечания:
• Отслеживает все файлы в /user/config/plugins/ и /user/config/themes/
• Помогает отслеживать изменения настроек плагинов с течением времени
• Полезен при отладке проблем с конфигурацией

show_revision_count¶

• Тип: логическое значение
• По умолчанию: true
• Описание: показывать значок с количеством версий на кнопке истории на панели инструментов
• Примечания:
• Показывает общее количество версий для текущего ресурса
• Обновляется автоматически при создании или удалении версий
• Можно отключить для более чистого интерфейса, если это предпочтительнее

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

Доступ к версиям¶

Плагин Revisions Pro без швов встраивается в интерфейс админки Grav. Открывайте версии кнопкой История (🕐) на панели инструментов админки при редактировании любого поддерживаемого типа контента.

Поддерживаемые типы контента¶

1. Страницы — все типы страниц, включая:
2. Стандартные страницы
3. Модульные страницы
4. Многоязычные страницы

5. Записи блога

6. Файлы конфигурации:

7. Системная конфигурация (system.yaml)
8. Конфигурация сайта (site.yaml)

9. Конфигурации для конкретных окружений

10. Конфигурации плагинов и тем:

11. Все настройки плагинов
12. Конфигурации тем

Панель версий¶

При нажатии кнопки истории с правой стороны выезжает панель, показывающая:

• Список версий: все версии текущего ресурса
• Отметка времени: когда было сделано изменение (со звездой ⭐ для текущей версии)
• Автор: пользователь, сделавший изменение
• Размер файла: размер версии
• Кнопки действий: просмотр, сравнение, восстановление, удаление

Просмотр версий¶

Нажмите кнопку Просмотр на любой версии, чтобы увидеть её полное содержимое в режиме только для чтения с подсветкой синтаксиса.

Сравнение версий¶

1. Нажмите кнопку Сравнить на любой версии
2. Выезжает дополнительная панель, показывающая:
3. Сравнение различий бок о бок
4. Зелёная подсветка добавлений
5. Красная подсветка удалений
6. Корректная подсветка синтаксиса (YAML, Markdown и т. д.)
7. Вариант объединённого просмотра различий

Восстановление версий¶

1. Нажмите кнопку Восстановить на той версии, которую хотите восстановить
2. Подтвердите действие в появившемся диалоге
3. Система:
4. создаст резервную копию текущей версии
5. восстановит выбранную версию
6. перезагрузит страницу с сообщением об успехе

Удаление версий¶

1. Нажмите кнопку Удалить на любой версии (кроме текущей)
2. Подтвердите удаление в диалоге
3. Версия удаляется безвозвратно

Поддержка многоязычности¶

Revisions Pro полностью поддерживает фичи многоязычности Grav:

Как это работает¶

• Определение языка: автоматически определяет текущий язык по URL админки
• Раздельное отслеживание: каждая языковая версия отслеживается независимо
• Правильное хранение: версии сохраняются с языковыми суффиксами (например, :fr, :de)
• Язык по умолчанию: обрабатывает файлы языка по умолчанию с языковыми расширениями и без них

Версии для конкретного языка¶

При редактировании страницы на определённом языке: - отображаются только версии для этого языка - счётчик версий отражает только историю этого языка - восстановление затрагивает только текущую языковую версию

Пример¶

Для страницы, доступной на английском (по умолчанию) и французском: - английские версии: typography.md.20240130-143022.rev - французские версии: typography.fr.md.20240130-143022.rev

Команды CLI¶

Revisions Pro предоставляет мощные инструменты командной строки для обслуживания и автоматизации.

Команда очистки¶

Удаление старых версий по возрасту или другим критериям:

# Использовать настройки по умолчанию из конфигурации
bin/plugin revisions-pro cleanup

# Указать свой предельный возраст (переопределяет конфигурацию)
bin/plugin revisions-pro cleanup --days=30

# Предварительный просмотр: что будет удалено, без фактического удаления
bin/plugin revisions-pro cleanup --dry-run

# Тихий режим (вывод только ошибок)
bin/plugin revisions-pro cleanup --quiet

# Указать окружение
bin/plugin revisions-pro cleanup --env=production

Параметры команды¶

Примеры автоматизации¶

Задание cron для ежедневной очистки¶

# Запускать очистку ежедневно в 2:00
0 2 * * * cd /path/to/grav && bin/plugin revisions-pro cleanup --quiet --days=30

Плановая очистка через планировщик Grav¶

# Добавьте в crontab, чтобы планировщик Grav запускался каждую минуту
* * * * * cd /path/to/grav && bin/grav scheduler 1>> /dev/null 2>&1

Архитектура хранилища¶

Понимание того, как хранятся версии, помогает при планировании резервных копий и решении проблем.

Расположение хранилища¶

Версии страниц¶

Хранятся рядом с файлами страницы:

/user/pages/02.typography/
├── default.md                          # Текущая страница
├── default.md.20240130-143022.rev     # Версия
├── default.md.20240129-102015.rev     # Более старая версия
├── default.fr.md                      # Французская версия
└── default.fr.md.20240130-145530.rev  # Французская версия

Версии конфигурации¶

Хранятся рядом с файлами конфигурации:

/user/config/
├── system.yaml                         # Текущая конфигурация
├── system.yaml.20240130-143022.rev    # Версия
└── system.yaml.20240129-102015.rev    # Более старая версия

/user/config/plugins/
├── revisions-pro.yaml                 # Текущая конфигурация плагина
└── revisions-pro.yaml.20240130-143022.rev

Конфигурации для конкретных окружений¶

/user/env/production/config/
├── system.yaml
└── system.yaml.20240130-143022.rev

Индекс версий¶

Централизованный индекс отслеживает все версии для эффективного управления:

/user/data/revisions/index.json

Этот индекс содержит метаданные обо всех версиях и используется для: - быстрого поиска версий - операций очистки - контроля лимита хранилища

Соглашение об именовании файлов¶

Версии используют единый шаблон именования:

[original-filename].[timestamp].rev

Формат отметки времени: YYYYMMDD-HHMMSS

Справочник API¶

Для разработчиков, которые хотят интегрироваться с Revisions Pro программно.

Получение менеджера версий¶

// Получить экземпляр менеджера версий
$revisionManager = $grav['plugins']
    ->get('revisions-pro')
    ->revisionManager;

Типовые операции¶

Получение версий страницы¶

// Получить все версии страницы
$page = $grav['pages']->find('/typography');
$revisions = $revisionManager->getRevisions($page);

// Получить ограниченное количество версий
$revisions = $revisionManager->getPageRevisions($page->path(), 10);

Получение версий конфигурации¶

// Версии системной конфигурации
$revisions = $revisionManager->getRevisionsForRoute(
    'system', 
    'config-system'
);

// Версии конфигурации плагина
$revisions = $revisionManager->getRevisionsForRoute(
    'revisions-pro', 
    'plugin-config'
);

Создание версии вручную¶

// Создать версию текущего состояния страницы
$result = $revisionManager->createRevision($page, 'page');

// Создать версию конфигурации
$result = $revisionManager->createRevision($config, 'config-system');

Восстановление версии¶

// Восстановить по ID версии
$success = $revisionManager->restoreRevision($revisionId);

// Получить подробности результата восстановления
if ($success) {
    $restoredFile = $revisionManager->getRevision($revisionId);
}

Удаление версии¶

// Удалить конкретную версию
$success = $revisionManager->deleteRevision($revisionId);

// Очистить старые версии
$deletedCount = $revisionManager->cleanupOldRevisions(30); // дней

События¶

Revisions Pro вызывает события, к которым можно подключиться:

// В вашем плагине
public static function getSubscribedEvents()
{
    return [
        'onRevisionCreate' => ['onRevisionCreate', 0],
        'onRevisionRestore' => ['onRevisionRestore', 0],
        'onRevisionDelete' => ['onRevisionDelete', 0]
    ];
}

public function onRevisionCreate($event)
{
    $revision = $event['revision'];
    $type = $event['type'];
    // Пользовательская логика здесь
}

Решение проблем¶

Версии не создаются¶

1. Проверьте состояние плагина
2. Убедитесь, что плагин включён в конфигурации

3. Проверьте, что нужный переключатель отслеживания включён

4. Права доступа к файлам

5. Веб-сервер должен иметь права на запись в папки контента

6. Проверьте права доступа к /user/pages/, /user/config/ и т. д.

7. Проверьте журналы

   tail -f logs/grav.log
   

Очистка не запускается автоматически¶

1. Проверьте конфигурацию

   auto_cleanup: true
   

2. Проверьте планировщик

3. Убедитесь, что планировщик Grav включён и работает правильно

4. Проверьте, что задание cron настроено:

   crontab -l | grep scheduler
   

5. Проверьте вручную

   bin/plugin revisions-pro cleanup --dry-run
   

Проблемы с хранилищем¶

1. Следите за дисковым пространством

   # Проверить, сколько места занимают версии
   du -sh user/pages/**/*.rev
   du -sh user/config/**/*.rev
   

2. Скорректируйте параметры хранения

3. Уменьшите max_revisions_per_page
4. Сократите cleanup_older_than
5. Запускайте ручную очистку чаще

Проблемы с производительностью¶

1. Большое количество версий
2. Подумайте об уменьшении max_revisions_per_page

3. Запустите очистку, чтобы удалить старые версии

4. Медленная загрузка панели

5. Проверьте, нет ли у отдельных ресурсов чрезмерного количества версий
6. Подумайте о внедрении пагинации (обратитесь в поддержку)

Проблемы, связанные с языками¶

1. Отображаются версии не того языка
2. Очистите кэш Grav: bin/grav clear-cache

3. Убедитесь, что в админке открыт URL правильного языка

4. Отсутствуют версии для языка

5. Проверьте, что многоязычность настроена правильно
6. Убедитесь, что для контента существуют языковые файлы

Режим отладки¶

Включите режим отладки для подробных сообщений об ошибках:

# user/config/system.yaml
debugger:
  enabled: true

# Также проверьте журналы плагина
log:
  handler: file
  syslog:
    facility: local6

Типичные сообщения об ошибках¶

Рекомендации¶

Управление хранилищем¶

1. Устанавливайте разумные лимиты
2. Рабочая версия сайта: 20–50 версий на страницу

3. Разработка: 10–20 версий на страницу

4. Регулярная очистка

5. Включите автоматическую очистку
6. Установите подходящие предельные сроки исходя из ваших потребностей
7. Периодически следите за использованием хранилища

Вопросы безопасности¶

1. Контроль доступа
2. Доступ к версиям имеют только администраторы

3. Подумайте о дополнительных ограничениях по ролям

4. Конфиденциальные данные

5. Учитывайте, что версии могут содержать конфиденциальные данные
6. Удаляйте старые версии, содержащие устаревшую конфиденциальную информацию
7. Рассмотрите более короткий срок хранения для файлов конфигурации

Оптимизация производительности¶

1. Совместимость с кэшированием
2. Revisions Pro полностью совместим с кэшированием Grav

3. Отключать кэширование на страницах с версиями не нужно

4. Большие сайты

5. Используйте более агрессивные настройки очистки
6. Подумайте об отключении значков с количеством версий для лучшей производительности
7. Следите за размером индекса версий

Стратегия резервного копирования¶

1. Включайте версии в резервные копии
2. Файлы версий (.rev) следует включать в резервные копии

3. Индекс версий (/user/data/revisions/index.json) важен

4. Процедуры восстановления

5. После восстановления резервной копии версии будут доступны
6. После восстановления выполните bin/grav clear-cache

Руководство по миграции¶

С ручных резервных копий¶

Если вы делали резервные копии файлов вручную:

1. Установите и настройте Revisions Pro
2. Ваш существующий контент станет «текущей» версией
3. Новые версии будут создаваться автоматически в дальнейшем
4. Старые ручные резервные копии можно хранить отдельно

Из другой системы контроля версий¶

Если вы переходите с Git или другой VCS:

1. Revisions Pro дополняет Git, а не заменяет его
2. Git — для кода, Revisions Pro — для контента
3. Оба можно использовать одновременно
4. Рассмотрите более короткий срок хранения для Revisions Pro, если используете Git

Поддержка¶

По вопросам, проблемам или запросам новых фич:

1. Документация: сначала обратитесь к этому руководству
2. GitHub Issues: сообщайте об ошибках по адресу задач
3. Grav Discord: помощь сообщества в #premium-support
4. Premium Support: доступна для владельцев лицензий

При сообщении о проблемах указывайте: - версию Grav - версию PHP - версию плагина - сообщения об ошибках из журналов - шаги для воспроизведения