GrIT Downloads - раздача файлов

Назначение компонента

GRIT Downloads - система управления файлами и статистикой скачиваний для Joomla. Компонент создаёт постоянную ссылку для каждого расширения, проверяет доступность файла, выдаёт его посетителю и сохраняет событие загрузки в базе данных.

Компонент подходит для публикации собственных плагинов, компонентов, модулей, пакетов Joomla, инструкций, архивов и других файлов, которые должны скачиваться по стабильному адресу с учётом статистики.

GRIT Downloads решает несколько задач:

• создаёт постоянные ссылки на скачивание;
• скрывает реальный путь к файлу от посетителя;
• учитывает общие и уникальные загрузки;
• показывает статистику по периодам;
• хранит историю опубликованных версий;
• позволяет безопасно заменить текущий ZIP-файл;
• формирует готовые шорткоды кнопки, версии, изменений текущего выпуска и истории выпусков;
• автоматически обновляет версию и примечания к выпуску в материалах Joomla;
• подключает стили кнопки в материалах Joomla;
• передаёт цель скачивания в Яндекс Метрику;
• сохраняет ClientID Метрики в событии;
• отделяет уникальные скачивания от повторных;
• не учитывает известных ботов по умолчанию.

Основные возможности

• Создание неограниченного количества карточек расширений и файлов.
• Автоматическое формирование алиаса из названия.
• Публикация и снятие записи с публикации.
• Автоматическое формирование пути к загруженному ZIP-файлу.
• Загрузка ZIP-файла непосредственно из административной панели.
• Проверка расширения, сигнатуры, MIME-типа и целостности ZIP-архива.
• Автоматическое вычисление размера и SHA-256.
• Сохранение исходного имени файла для пользователя.
• Безопасная замена файла без изменения публичной ссылки.
• Хранение отдельных примечаний к каждому выпуску.
• Редактирование примечаний текущего выпуска без повторной загрузки ZIP.
• Вывод изменений текущего выпуска в публичном каталоге.
• Статистика скачиваний отдельно для каждой версии.
• Возврат к предыдущей версии одной кнопкой.
• Копирование готовой ссылки на скачивание.
• Копирование готового шорткода кнопки с номером текущей версии.
• Копирование отдельного шорткода для вывода только номера версии.
• Копирование шорткода изменений текущего выпуска.
• Копирование шорткода истории выпусков с настраиваемым лимитом.
• Автоматическое обновление кнопки, версии и примечаний после смены текущего файла.
• Автоматическое подключение стилей кнопки в материалах Joomla.
• Публичный каталог опубликованных расширений.
• Опциональный публичный счётчик скачиваний.
• Главная панель с показателями за сегодня, 7 и 30 дней.
• Журнал событий с поиском, фильтрами и пагинацией.
• Фильтрация событий по расширению и уникальности.
• Сохранение безопасно сокращённого источника перехода.
• Определение известных ботов по User-Agent.
• Ограничение слишком частых запросов.
• Сброс статистики отдельно для выбранного файла.
• Русский и английский интерфейс.

Состав установочного пакета

Установочный архив GRIT Downloads является пакетом Joomla и устанавливает два связанных расширения. Имя ZIP-файла может меняться вместе с номером выпуска, поэтому ориентироваться следует на название пакета, указанное рядом с кнопкой скачивания.

После установки контент-плагин включается автоматически. Он обрабатывает четыре типа шорткодов в материалах Joomla, подключает стили кнопки и блоков истории, а при включённой настройке - интеграцию с Яндекс Метрикой.

Медиафайлы компонента

Системные требования

• Joomla 6.x.
• MySQL или MariaDB.
• Разрешённая загрузка файлов в PHP.
• Каталог хранения, доступный Joomla для записи и чтения.
• Расширение PHP ZipArchive рекомендуется для полной проверки целостности ZIP.
• Расширение PHP Fileinfo рекомендуется для проверки MIME-типа.
• Установленный счётчик Яндекс Метрики требуется только для интеграции с целью grit_download.

Установка

Во время установки создаются таблицы:

#__grit_download_items
#__grit_download_versions
#__grit_download_events

Быстрый старт

1. Откройте Компоненты - GRIT Downloads - Расширения и файлы.
2. Нажмите Создать.
3. Укажите название расширения.
4. Введите алиас или оставьте поле пустым для автоматического формирования.
5. Укажите номер версии.
6. Заполните поле «Что изменилось в версии» кратким описанием выпуска.
7. Выберите ZIP-файл в поле «Загрузить ZIP-файл».
8. Путь к файлу и имя скачиваемого архива будут сформированы автоматически после сохранения.
9. Установите состояние «Опубликовано».
10. Сохраните карточку.
11. В блоке «Готовые шорткоды» выберите нужный вариант и скопируйте его.
12. Вставьте шорткод в материал Joomla или пользовательский HTML-модуль, который обрабатывается контент-плагинами.

Кнопка скачивания:

{grit-download alias="grit-ajax-reservation" text="Скачать плагин"}

Только номер текущей версии:

{grit-version alias="grit-ajax-reservation"}

Изменения текущего выпуска:

{grit-changes alias="grit-ajax-reservation"}

История последних выпусков:

{grit-history alias="grit-ajax-reservation" limit="5"}

Постоянная ссылка, которую использует кнопка:

/index.php?option=com_gritdownloads&view=download&alias=grit-ajax-reservation

При последующих обновлениях меняются текущий ZIP-файл, номер версии и примечания к выпуску. Алиас, постоянный адрес и размещённые в материалах шорткоды остаются прежними.

Главная панель статистики

Главная страница компонента показывает состояние каталога и последние события без перехода между несколькими разделами.

Карточки показателей

Ниже расположены два рабочих блока:

• Популярные расширения - название, версия, общий и уникальный счётчики.
• Последние скачивания - расширение, дата, уникальность, ClientID и источник перехода.

В верхней части доступны быстрые действия: добавление расширения, переход к списку файлов и открытие полного журнала событий.

Раздел «Расширения и файлы»

В этом разделе находятся все карточки файлов. Каждая строка показывает основные сведения и предоставляет быстрые действия без открытия формы редактирования.

Список поддерживает:

• поиск по названию, алиасу и пути;
• фильтр по состоянию публикации;
• сортировку по названию;
• сортировку по количеству скачиваний;
• сортировку по дате изменения;
• стандартную пагинацию Joomla.

Загрузка файла и безопасная замена версии

ZIP-архив можно загрузить непосредственно в форме создания или редактирования расширения. Путь к файлу указывать вручную не требуется - компонент формирует его автоматически на основе алиаса и фактически загруженного архива.

Проверки при загрузке

• проверяется результат загрузки PHP;
• разрешено только расширение .zip;
• проверяется ZIP-сигнатура;
• при наличии ZipArchive выполняется проверка целостности архива;
• при наличии Fileinfo проверяется MIME-тип;
• создаётся безопасное имя каталога на основе алиаса;
• путь к файлу заполняется автоматически;
• исходное имя ZIP используется как имя скачиваемого файла, если отдельное имя не задано;
• файл получает уникальное внутреннее имя;
• вычисляются размер и SHA-256.

Пример внутреннего пути:

grit/files/grit-ajax-reservation/20260805-102200-a1b2c3d4-plg_grit_ajaxreservation.zip

Как происходит замена

1. Администратор указывает новый номер версии.
2. Заполняет поле «Что изменилось в версии» примечаниями к новому выпуску.
3. Загружает новый ZIP-файл.
4. Компонент проверяет и сохраняет архив отдельно от старого.
5. После успешного сохранения новая версия становится текущей.
6. Предыдущая версия остаётся в истории.
7. Постоянная ссылка начинает выдавать новый файл.
8. Общая статистика карточки не сбрасывается.

Примечания к выпуску

Поле «Что изменилось в версии» связано с текущей записью в истории версий. Текст сохраняется отдельно для каждого выпуска и используется административной историей, публичным каталогом и шорткодами изменений.

Примечания текущего выпуска можно исправить или очистить без повторной загрузки ZIP-файла. При назначении архивной версии текущей компонент подставляет примечания именно выбранного выпуска.

Автоматическое заполнение пути

При создании новой карточки поле «Путь к файлу» заполнять вручную не требуется. После выбора ZIP-архива компонент создаёт каталог на основе алиаса, сохраняет файл под безопасным уникальным именем и записывает полученный относительный путь автоматически.

Пример автоматически сформированного пути:

files/grit-downloads/20260805-130700-a1b2c3d4-pkg_gritdownloads.zip

История версий и примечания к выпускам

Каждая новая загрузка создаёт отдельную запись версии. Постоянная ссылка карточки всегда отдаёт файл, помеченный как текущий, а текст из поля «Что изменилось в версии» хранится вместе с соответствующим выпуском.

Для каждой версии сохраняются:

• номер версии;
• имя скачиваемого файла;
• внутренний путь;
• примечания к выпуску;
• размер файла;
• контрольная сумма SHA-256;
• дата добавления;
• общие скачивания версии;
• уникальные скачивания версии;
• признак текущей версии.

Использование поля «Что изменилось в версии»

Примечания отображаются в карточке текущего файла и в отдельной колонке административной истории. Текст текущего выпуска можно вывести в материале шорткодом {grit-changes alias="..."}, а несколько выпусков - шорткодом {grit-history alias="..." limit="5"}.

Возврат к предыдущей версии

Для архивной записи доступна кнопка «Сделать текущей». Перед переключением компонент проверяет, что файл существует и доступен для чтения.

После переключения:

• в карточке обновляются версия, путь и имя файла;
• подставляются примечания выбранного выпуска;
• публичная ссылка остаётся прежней;
• общие счётчики карточки сохраняются;
• новые события связываются с выбранной версией;
• шорткоды версии и изменений обновляются автоматически;
• старая текущая версия остаётся в истории.

Постоянные ссылки и шорткоды

Для каждой опубликованной записи компонент формирует постоянную ссылку и четыре готовых шорткода. Алиас подставляется автоматически, поэтому после обновления файла не требуется вручную менять кнопку, номер версии или историю изменений в материалах Joomla.

Постоянная ссылка

/index.php?option=com_gritdownloads&view=download&alias=grit-ajax-reservation

Ссылка сохраняется при загрузке новой версии и подходит для внешних страниц, писем и других мест, где контент-плагины Joomla не выполняются. В материалах Joomla предпочтительнее использовать шорткод кнопки.

Шорткод кнопки скачивания

{grit-download alias="grit-ajax-reservation" text="Скачать плагин"}

Шорткод выводит постоянную ссылку, SVG-иконку, текст кнопки и подпись с номером текущей версии.

Шорткод текущей версии

{grit-version alias="grit-downloads"}

Выводит только номер текущей версии без дополнительной HTML-разметки. Подходит для характеристик, таблиц, текста и структурированных данных.

<div class="grit-plugin-doc__meta">
	<span><strong>Версия:</strong> {grit-version alias="grit-downloads"}</span>
	<span><strong>Joomla:</strong> 6.x</span>
	<span><strong>Тип:</strong> пакет Joomla</span>
	<span><strong>Лицензия:</strong> GNU GPL</span>
</div>

Шорткод изменений текущего выпуска

{grit-changes alias="grit-downloads"}

Выводит оформленный блок с номером текущей версии и текстом из поля «Что изменилось в версии». Если примечания не заполнены, шорткод ничего не выводит.

Шорткод истории выпусков

{grit-history alias="grit-downloads" limit="5"}

Выводит последние версии, для которых заполнены примечания. Текущий выпуск располагается первым и получает отметку «Текущая». Затем записи сортируются по дате добавления.

Где находятся готовые шорткоды

Откройте Компоненты - GRIT Downloads - Расширения и файлы и выберите запись. В форме «Редактирование расширения» находится блок «Готовые шорткоды» с четырьмя полями и отдельными кнопками копирования.

Правила обработки

• контент-плагин «GRIT Downloads - кнопки и шорткоды» должен быть включён;
• запись должна быть опубликована;
• алиас должен точно совпадать с алиасом карточки;
• пользовательский HTML-модуль должен поддерживать обработку контент-плагинами;
• шорткоды внутри тегов pre, code, script, style и textarea намеренно не заменяются;
• при пустых примечаниях шорткоды изменений и истории не создают пустые блоки.

Автоматическое оформление

Контент-плагин подключает файл:

/media/com_gritdownloads/css/button.css

В нём находятся стили кнопки, блока изменений текущей версии и списка истории выпусков. При включённой интеграции для кнопки также подключается обработчик Яндекс Метрики и ClientID.

История изменений GRIT Downloads

Ниже компонент автоматически выводит последние выпуски, для которых заполнено поле «Что изменилось в версии». При публикации следующего обновления достаточно загрузить новый ZIP и записать примечания в карточке расширения - этот раздел обновится без редактирования статьи.

Публичный каталог загрузок

Компонент содержит публичное представление «Каталог загрузок». Оно выводит все опубликованные карточки расширений.

Для создания страницы каталога:

1. Откройте нужное меню Joomla.
2. Создайте новый пункт меню.
3. Выберите тип пункта GRIT Downloads - Каталог загрузок.
4. Укажите заголовок и сохраните пункт.

В каталоге отображаются:

• название расширения;
• номер текущей версии;
• описание;
• изменения текущего выпуска, если их показ включён в настройках;
• кнопка скачивания;
• количество скачиваний, если публичный счётчик включён.

Если опубликованных файлов нет, посетитель увидит сообщение «Файлы для скачивания пока не опубликованы».

Статистика и события скачивания

Событие создаётся на сервере при успешной подготовке файла к выдаче. Компонент не ограничивается подсчётом кликов по кнопке.

Что сохраняется в событии

Определение уникальности

Компонент формирует закрытый HMAC-хеш из IP-адреса и User-Agent. Сам IP-адрес в открытом виде в таблицу событий не записывается.

По умолчанию повторное скачивание тем же браузером в течение 24 часов считается повторным. Период можно изменить в настройках от 1 до 720 часов.

Фильтры журнала

• поиск по названию расширения, версии, источнику и ClientID;
• фильтр по конкретному расширению;
• фильтр «Уникальные» или «Повторные»;
• сортировка по дате;
• сортировка по названию расширения;
• выбор количества строк на странице.

Рядом с ClientID находится кнопка копирования для дальнейшего поиска и сегментации в Яндекс Метрике.

Интеграция с Яндекс Метрикой

GRIT Downloads может отправлять цель grit_download при нажатии на оформленную кнопку скачивания и сохранять ClientID браузера в серверном событии.

Настройка цели

Параметры цели

При клике в Метрику передаются:

Пример события:

{
	"grit_download": {
		"alias": "grit-ymlfeed-start",
		"version": "0.2.48",
		"page_path": "/tools/grit-yml-feed"
	}
}

Получение ClientID

Контент-плагин вызывает метод Метрики getClientID. Полученный числовой идентификатор добавляется к запросу скачивания и сохраняется в таблице событий.

ClientID не добавляется в параметры reachGoal, поэтому может не отображаться внутри объекта цели в отладчике. Метрика связывает цель с визитом самостоятельно, а компонент хранит тот же идентификатор в своём журнале.

Последовательность при клике

1. Посетитель нажимает кнопку скачивания.
2. Скрипт отправляет цель grit_download.
3. Скрипт запрашивает ClientID.
4. После ответов Метрики запускается обычный переход к файлу.
5. Компонент проверяет карточку и физический файл.
6. Создаётся серверное событие скачивания.
7. Посетителю выдаётся ZIP-архив.

Что анализировать в Метрике

• источник перехода;
• поисковую систему;
• рекламную кампанию;
• UTM-метки;
• страницу входа;
• страницу скачивания;
• устройство и браузер;
• регион посетителя;
• путь до достижения цели;
• конкретное расширение и версию.

Настройки компонента

Основные настройки

Яндекс Метрика

Шорткоды

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

В справке приведены:

• синтаксис шорткода кнопки скачивания;
• синтаксис шорткода текущей версии;
• синтаксис шорткода изменений текущего выпуска;
• синтаксис шорткода истории выпусков;
• описание параметров alias, text и limit;
• пример использования версии внутри HTML-блока;
• пошаговая инструкция по копированию готовых шорткодов;
• правила публикации и обработки шорткодов.

Права доступа

Компонент поддерживает стандартные действия ACL Joomla:

• администрирование компонента;
• доступ к компоненту;
• создание записей;
• редактирование записей;
• изменение состояния публикации;
• удаление записей и сброс статистики.

Безопасность

Проверка пути к файлу

• разрешены только относительные пути;
• запрещена последовательность ..;
• реальный путь должен находиться внутри каталога хранения;
• перед выдачей проверяется существование и доступность файла для чтения;
• неопубликованные карточки не выдаются.

Защита загрузки ZIP

• принимаются только ZIP-файлы;
• проверяется сигнатура архива;
• при наличии ZipArchive проверяется структура архива;
• при наличии Fileinfo проверяется MIME-тип;
• имя очищается от небезопасных символов;
• внутреннее имя содержит дату и случайную последовательность;
• после сохранения вычисляется SHA-256;
• при ошибке новый файл удаляется.

Статистика без открытого IP

Для уникальности используется HMAC-хеш IP-адреса и User-Agent с секретом Joomla. Открытый IP-адрес и полный User-Agent в таблицу событий не записываются.

Ограничение частоты

Перед созданием события компонент проверяет количество недавних запросов технического отпечатка. При превышении лимита выдаётся ответ с кодом 429.

Административные операции

• проверка ACL Joomla;
• CSRF-токен для сброса статистики и переключения версии;
• изменяющие операции выполняются через POST;
• критические изменения выполняются в транзакции базы данных;
• строка карточки блокируется при обновлении счётчиков и переключении версии.

Проверка после установки

1. Откройте настройки и проверьте каталог хранения.
2. Создайте тестовую карточку расширения.
3. Укажите алиас, номер версии и текст в поле «Что изменилось в версии».
4. Загрузите корректный ZIP-файл.
5. Сохраните карточку и убедитесь, что появились размер и SHA-256.
6. Проверьте отображение примечаний в блоке текущего файла и в истории версий.
7. В блоке «Готовые шорткоды» скопируйте все четыре варианта.
8. Вставьте шорткоды в тестовый материал Joomla.
9. Убедитесь, что на сайте появились кнопка, номер версии и блок изменений текущего выпуска.
10. Проверьте, что история содержит выпуск с заполненными примечаниями.
11. Нажмите кнопку и убедитесь, что браузер получил файл с ожидаемым именем.
12. Откройте главную панель GRIT Downloads и проверьте увеличение счётчика.
13. Откройте «События скачивания» и проверьте новую запись.
14. Повторите скачивание и проверьте признак уникальности.
15. Загрузите новую версию с другим текстом изменений.
16. Убедитесь, что предыдущий выпуск сохранился в административной и публичной истории.
17. Обновите материал и проверьте автоматическое изменение версии и текущих примечаний.
18. Назначьте предыдущую версию текущей и снова проверьте автоматическое обновление.
19. При включённой Метрике проверьте цель grit_download.
20. Убедитесь, что в событии сохранился ClientID.

Проверка Метрики в отладчике

При корректной работе отображается событие примерно такого вида:

Reach goal. Counter: 99693350.
Goal id: grit_download.

{
	"grit_download": {
		"alias": "grit-example",
		"version": "x.x.x",
		"page_path": "/tools/example"
	}
}

ClientID может отсутствовать внутри параметров цели. Его следует проверять в разделе «События скачивания» компонента.

Обновление и удаление

Обновление

Новый пакет устанавливается поверх текущей версии через стандартный установщик Joomla.

При обновлении сохраняются:

• карточки расширений;
• алиасы и постоянные ссылки;
• загруженные ZIP-файлы;
• история версий и примечания к выпускам;
• общая и уникальная статистика;
• события скачиваний;
• ClientID Метрики;
• настройки компонента.

Предварительно удалять установленную версию не нужно.

Обновление со старых версий

При обновлении существующие карточки автоматически получают запись текущей версии в истории. Старые события связываются с этой версией, если связь ещё отсутствует.

Удаление

GRIT Downloads установлен как пакет из компонента и контент-плагина. Удалять пакет следует через стандартный раздел управления расширениями Joomla.

Ограничения

• Через административную форму загружаются только ZIP-файлы.
• Компонент не собирает имя, телефон или email посетителя.
• ClientID является идентификатором браузера, а не подтверждённой личностью пользователя.
• Прямая загрузка физического файла в обход компонента не учитывается.
• Компонент не выполняет лицензирование и не создаёт персональные ключи доступа.
• Компонент не является облачным хранилищем и использует файловую систему сайта.
• История версий не заменяет резервное копирование сайта.