Поле «Файлы»

Тип files входит в включённый плагин базовых полей dharmashopfield/basic. Подходит для публичных инструкций, паспортов, сертификатов, прайс-листов и других вложений товара или категории. Это обычные публичные файлы каталога, не закрытые документы заказа.

Настройка

На вкладке «Основное» выберите расположение файлов: карточки в столбик (по умолчанию) или в колонки. Для сетки доступно 2–6 колонок на широком экране; на среднем — до двух, на телефоне — одна. Вывод остаётся в отдельном переопределяемом fields/files.php; настройки передаются в field.file_settings как files_layout=list/grid и files_columns.

1. «Поля → Создать»: выбрать «Файлы», назначение (товар/категория), группу и применимость.
2. На вкладке «Основное»: предел одного файла (10 МБ), допустимые расширения, максимальное количество (10; от 1 до 100), текст ссылки (подпись с резервом на имя или всегда имя), показ размера/формата и открытие в новой вкладке (включены).
3. На вкладке «Отображение»: включение в список, полную страницу и отдельно интро товара. Интро по умолчанию выключено. Для всех типов есть переключатели заголовка отдельно в списке и на полной странице (по умолчанию включены); интро наследует настройку полной страницы. Если заголовок выключен, значение занимает всю ширину, название остаётся доступно скринридеру. Название группы и вкладки сохраняется. Варианты «картинки/через запятую» для файлов скрыты. Фильтр/вариативность недоступны.
4. В редакторе товара/категории: перетаскивание или выбор нескольких файлов; отдельная подпись у каждого, стрелки/перетаскивание для порядка, удаление из списка. Можно выбрать локальный файл штатным медиа-менеджером Joomla. Доступные ему форматы определяются также его настройками.

Поддерживаемые форматы перечислены в настройке; список можно сократить. Размер загрузки ограничен минимумом предела поля, PHP и «Медиа» Joomla. Фактический предел показан в загрузчике. Обязательность, количество, размер, расширение и MIME повторно проверяются сервером перед сохранением.

«Имя файла при загрузке» (files_naming=original/clean): по умолчанию сохраняются кириллица, пробелы и одиночные точки, а также регистр расширения. Режим clean заменяет пробелы/спецсимволы и внутренние точки дефисами, расширение приводит к нижнему регистру. Оба режима заменяют недопустимые разделители пути/URL, убирают повторные точки и ограничивают имя 255 байтами без разрыва UTF-8. Ссылки кодируются по сегментам (FileStorage::urlPath), в БД/форме/на диске хранится исходный относительный путь. Файлы, выбранные с сервера, не переименовываются. Старые вложения массово не меняются; их прежнее имя до загрузки восстановить автоматически невозможно.

Независимые экземпляры загрузчика

Общий media/js/gallery.js работает в двух режимах: обычная галерея и data-kind="files". Список, шаблон, очередь, прогресс, обработчики paste/drop, состояние и сортировка находятся в замыкании конкретного корня. data-name содержит полный путь формы; native Media получает имя из хеша полного ID контрола. Служебное пустое значение позволяет очистить список при сохранении.

Основная галерея: jform[gallery], строки field_id=0, собственный endpoint изображений. Поля: jform[custom_fields][f_<ID>], field_id>0, отдельные запросы media.uploadFile и media.selectFile (POST + CSRF + ACL). Настройки запроса загрузки читаются из определения на сервере. Отдельная будущая галерея может использовать свои ID/имена формы и тот же интерфейс; тип дополнительной галереи этим изменением ещё не создаётся.

Сохранение FieldValues заменяет только строки нужного владельца/поля и variant_id IS NULL; GalleryRepository по-прежнему управляет только field_id=0 и обложкой. Переноса/изменения имеющихся фото нет.

Хранение

• Товары: существующая #__dharmashop_field_media; добавлены nullable filename (255), bytes (bigint unsigned), mime (127). title — подпись, ordering — порядок. Основная галерея оставляет новые столбцы NULL.
• Категории: #__dharmashop_category_field_media с category_id и индексом (category_id,field_id,ordering).
• При обновлении пакета FileStorage::upgrade() добавляет недостающее без переустановки и изменения сохранённых строк. При первой установке схема включена в install SQL; uninstall удаляет обе media-таблицы.
• Новые файлы: images/dharmashop/files/products/<алиас-товара>-<ID>/<алиас-поля>-<ID>/<номер-загрузки>/<имя>.<ext>; для категорий — categories. Пример: products/apple-iphone-16-pro-1/dokumentatsiya-9/1/Инструкция.pdf. Алиас и ID сохранённой записи читаются сервером по первичному ключу, назначение и алиас поля — из определения. До первого сохранения используется название из формы и суффикс -new вместо ID. Названия папок нормализуются и ограничиваются 80 байтами; имя самого файла остаётся согласно настройке.
• Числовая папка создаётся эксклюзивно, повторная/параллельная загрузка получает следующий свободный номер. Имя самого файла не получает префикс. Пустые папки номеров сохраняются, чтобы удалённый URL не был повторно использован для другого документа. При переименовании записи или поля существующие файлы не перемещаются, адреса остаются стабильными. Принадлежность определяется связями в БД, а не названием папки.
• Оба прежних формата с годом, двумя уровнями хеша и случайным кодом (в папке или префиксе имени) продолжают читаться без массового переименования. Для старого префикса отображаемое имя вычисляется без кода. Размер и MIME берутся с диска, а не из скрытых полей формы.
• Прямые внешние URL, выход за images, недопустимые расширения и MIME отклоняются; Office/OpenDocument дополнительно сверяются по ZIP-контейнеру без распаковки. В управляемой папке запрещены обработчики и листинг Apache. Создание папок не следует symlink.
• Файлы не конвертируются в WebP и не ресайзятся, даже если это JPG/PNG: инвентарь/миграция изображений пропускают media-строки с MIME. Исходник скачивается в сохранённом виде.
• Убранные связи удаляются при сохранении; после фиксации транзакции ImageCleaner удаляет только управляемые файлы без других ссылок магазина, включая media категорий. Файлы из чужих папок images остаются. Загрузка с последующей отменой формы оставляет несвязанный файл, как существующая галерея; автоматическая уборка таких файлов не добавлялась.

Витрина и переопределение

EntityFields читает файлы одним дополнительным пакетным запросом только при наличии загружаемых определений files; запросов и stat/finfo на каждый товар/файл нет. DTO значения: text,url,path,filename,caption,bytes,mime,extension,image='',html=false; DTO поля дополнен file_settings. Флаги отображения и доступа, применимость категорий и группы общие с другими типами.

Вывод: layouts/components/dharmashop/fields/files.php. Переопределение:

templates/<шаблон>/html/layouts/components/dharmashop/fields/files.php

В displayData['field'] доступны значения и настройки. Макет не выполняет SQL и использует Bootstrap. Группы файлов включаются в существующие вкладки товара; при включённом show_intro — также в краткие характеристики.