Для получения простой формы для загрузки файлов через ajax можно использовать
доступный через статический прокси интерфейс метод
simpleForm($action, array $hiddenInputs = [], $multiple = true, $serverOnly = false)
.
В метод нужно передать:
$action
- url, по которому должны быть отправлены данные;
$hiddenInputs
- массив скрытых инпутов;
$multiple
- требуется ли одновременная загрузка нескольких
файлов (по умолчанию), если не нужно, то данный параметр нужно определить как false
;
$serverOnly
- должна ли показываться форма для выбора
места загрузки файлоав (сервер, Яндекс.Диск), по умолчанию - нет, если нужно, то
данный параметр надо определить как true
.
Данная форма передаст по пути, соответствующему $action
, данные в скрытых инпутах
и файлы, массив которых будет обозначен именем userfile
.
После обработки переданных данных ответ сервера будет обработан типовым образом с использованием
функции xtables.serverReplyHandle
.
Upload::simpleForm('/some-upload/url', [
'name' => 'value',
'else_name' => 'else_value'
], false, true)
При первичной настройке приложения создается SQL таблица attachments
,
в которую по умолчанию сохраняется информация о загруженных и сохраненных файлах.
Возможно создавать и использовать дополнительные sql таблицы.
Для нормальной работы данного компонента sql таблица должна иметь следующие поля:
id
- первичный ключ с авто инкрементом;
path
- для сохранения пути размещения файла;
size
- для сохранения информации о размере файла;
hash
- для сохранения информации о хэш-сумме файла (для электронной подписи)
по алгоритму SHA512;
gl_group
- для сохранения информации о глобальной группе, к которой отнесен файл;
date
- для сохранения информации о дате сохранения файла;
user_id
- для сохранения информации об идентификаторе пользователя, сохранившего файл;
for_table
- для названия sql таблицы, для которой сохранен файл (с которой он соотносится);
for_id
- для сохранения идентификатора sql таблицы, для которой сохранен файл (с которой он соотносится);
storage
- для сохранения информации о месте хранения файла (поддерживается 'server', 'yadi'
).
thumbnail
- для сохранения информации о наличии миниатюры (1 или 0).
По умолчанию файлы сохраняются в папку /Documents
, расположенную по пути,
соответствующем константе XTABLES_BASE
. При необходимости осуществлять хранение файлов в другой папке,
в том числе находящейся вне веб директории (что особенно актуально при использовании связки APACHE - NGINX,
сервер NGINX сохраняет в кеше картинки и отдает их в нарушение директивы веб сервера APACHE deny from all
),
необходимо в файле настроек /config/config.php
указать абсолютный путь до этой папки,
включая ее название, в параметре server_doc_folder
.
Предусмотрена работа только с одной папкой документов. Если используется расположение папки документов не по умолчанию,
то есть в значении параметра server_doc_folder
, при изменении этого параметра, необходимо
перенести папку со всеми документами по этому расположению, чтобы обеспечить работоспособность ссылок в базе данных.
Ссылки путей документов являются относительными (относительно папки документов). Предусмотрено использование
прямых ссылок к документам (см. далее).
При сохранении открытых файлов внутри папки с веб доступом они помещаются в папку /free-docs
.
Загрузка файлов на сервер или Яндекс.Диск
Для загрузки файлов на сервер нужно создать экземпляр класса Upload
и вызвать метод getForm()
для получения
html формы для загрузки файлов.
Внутри формы будет иметься радио селект для выбора типа хранилища: сервер или Яндекс.Диск (в случае, если логин и пароль от него сохранены
в настройках).
Также будет иметься возможность определения Глобальной группы, которая будет сохранена в БД.
Показ прикрепленных файлов
Для показа прикрепленных файлов нужно создать экземпляр класса Upload
и вызвать метод attached()
для получения
списка загруженных файлов.
Можно воспользоваться тем же экземпляром класса, который был создан для показа формы загрузки.
use xtables\components\Upload\Upload;
$upload = new Upload($params);
$form = $upload->getForm();
$attached = new Upload($this->params);
$attached = $attached->attached();
use xtables\components\Upload\Upload;
$upload = new Upload($params);
$form = $upload->getForm();
$attached = $upload->attached();
Настроечные параметры для получения формы загрузки должны быть составлены в виде ассоциативного массива, которые передаются в конструктор данного компонента.
dir (string)
Название каталога, куда должен быть сохранен файл. Если каталога не существует, он будет создан.
По умолчанию файлы сохраняются в защищенный каталог /Documents
, который находится в
защищенной папке, соответствующей значению константы XTABLES_BASE
, или другом месте согласно
параметру server_doc_folder
.
'dir' => 'somedir'
web_root (boolean)
Нужно определить данный параметр со значением true
, если нужно сохранять файлы
в веб директорию для свободного доступа к ним из интернета.
'web_root' => true
table (string) имя зарезервировано и его передача во входных параметрах блокируется
Название sql таблицы, в которую должна быть сохранена информация о загруженном и сохраненном файле.
Если таблица не указана, то по умолчанию сохранение будет осуществляться в sql таблицу с именем attachments
.
'table' => 'some_table'
for_table (string)
Название sql таблицы, с которой связывается сохраняемый файл.
'for_table' => 'some_table'
for_id (int)
@since version 1.5.7 (int|callable)
Номер id
sql таблицы, с которой связывается сохраняемый файл или, начиная с версии 1.5.7 - callable
.
callable
может использоваться, если необходимо после загрузки файла автоматически
создавать дополнительную карточку (запись в другой таблице), к которой будет привязан загруженный файл.
Например, создается какая-то карточка автоматически и загруженный файл к ней привязывается.
'for_id' => 1111
'for_id' => 'some\classto\GetFrom::func'
thumbnail (string)
Если при сохранении файла-изображения (может использоваться только для изображений в форматах JPG и PNG), необходимо
создавать и сохранять миниатюры, то нужно определить данный параметр со значением размера миниатюры в пикселях через :
.
Миниатюра будет сохранена в каталог thumbnails
в том же каталоге, где будет сохраняться основное изображение,
то есть пути основного изображения и миниатюры будут отличаться лишь наличием дополнительного каталога
thumbnail
.
'thumbnail' => '75:75'
compress (array)
Если при сохранении файла-изображения (может использоваться только для изображений в форматах JPG и PNG), необходимо
сжимать изображение, изменяя его размер или качество, то нужно определить данный параметр. Другие форматы файлов
затронуты не будут.
Могут быть использованы следующие параметры:
max_width
- максимальная ширина в пикселях, при превышении будет уменьшена
до заданной ширины, высота будет изменена с сохранением пропорций изображения;
max_height
- максимальная высота в пикселях, при превышении будет уменьшена
до заданной высоты, ширина будет изменена с сохранением пропорций изображения;
quality
- качество со значением от 0 (худшее) до 100 (исходное качество изображения);
по умолчанию, если параметр не определен, то используется 100 (исходное качество изображения).
'compress' => [
'max_width' => 1000,
'max_height' => 1000,
'quality' => 90
]
path_back (string)
После загрузки файла появляется информационное окно, нажатие кнопки OK, в котором, по умолчанию, приводит
к перезагрузке экрана. Если необходимо подгружать содержимое, например карточки документа, в том же аякс контейнере, то
необходимо определить параметр path_back
с адресом, который будет отдавать ответ для аякс диспетчера.
Если нужно перезагрузить несколько аякс диспетчеров, то нужно воспользоваться параметром
reload_bundles
. В этом случае параметр path_back
можно не использовать.
'path_back' => '/some/url'
reload_bundles (string|array)
Если загрузка формы загрузки файлов будет осуществляться через аякс диспетчер,
то можно после загрузки файла на сервер, не осуществлять перезагрузку страницы.
Для этого можно определить адрес в параметре path_back
(см. выше).
Если нужно обновить несколько аякс диспетчеров, то их css идентификаторы можно указать в данном
параметре. В этом случае параметр path_back
можно не использовать.
'reload_bundles' => '#some-id'
'reload_bundles' => '#some-id,#else-id'
'reload_bundles' => [
'#some-id',
'#else-id'
]
need_hash (boolean)
Нужно включить данный параметр, если необходимо, чтобы при сохранении файла был определен и сохранен в БД его хэш,
что необходимо для использования модуля электронной подписи файла в будущем. Сохранение хэша файла сразу в базе данных
позволяет подписывать любые файлы, независимо от места их хранения (сервер или облачное хранилище).
Создание хэш файла осуществляется по алгоритму SHA512.
'need_hash' => true
reset_cache (string|array)
Название sql таблицы или массив из sql таблиц, у которых должен быть очищен файловый кэш.
'reset_cache' => 'some_table' // ['some_table1', 'some_table2']
user_id (int)
Номер идентификатора пользователя, который будет сохраен в БД, как сохранивший файл.
Если данный параметр не определен, то будет использовать номер из Session::get('ses_id')
'user_id' => 456
show_info (boolean)
Нужно определить данный параметр как false
, если не нужно выводить информационное окно о результатах
сохранения файла, например, для того, чтобы выполнить еще какие-то действия после сохранения, используя JS,
то есть после загрузки страница не будет перезагружена.
По умолчанию, если параметр не определен, либо если он имеет значение true
, информационное
окно выводится.
'show_info' => false // by default true
opened (boolean)
Нужно включить данный параметр со значением true
в случае, если необходимо, чтобы форма
показа прикрепленных файлов оставалась раскрытой при загрузке (по умолчанию сворачивается).
'opened' => true
free_url (boolean)
По умолчанию, все файлы показываются в браузере (становятся доступны для скачивания) в защищенной ссылке, срабатывающей только
после авторизации. Если необходимо показывать в прикрепленных файлах открытые ссылки к файлам (это необходимо
при загрузке файлов в веб директорию), то нужно определить данный параметр со значением true
.
'free_url' => true
attached (array)
Массив с названиями sql таблиц и идентификаторов, в соотнесении с которыми должен быть осуществлен поиск прикрепленных файлов.
'attached' => [
[
'for_table' => 'some_table',
'for_id' => [
$this->params['id']
]
],
[
'for_table' => 'some_table_else',
'for_id' => [
12,
15,
17
]
],
]
Вывод файла на экран браузера или скачивание
Прямой доступ к сохраненным файлам блокируется директивой файла .htaccess
или помещением папки с документами вне каталога с веб доступом (папка должна находиться внутри каталога, соответствующего
константе XTABLES_BASE или настройке server_doc_folder в файле /config/config.php
).
Для показа файлов или обеспечения их скачивания на компьютер пользователя необходимо:
/xtables-upload/showdoc
xtables\components\upload\Upload
и использовать метод
getDoc()
(метод выводит на экран содержимое файла через функцию readfile()
).
Настроечные параметры для показа/скачивания файла должны быть составлены в виде ассоциативного массива, которые передаются в конструктор данного компонента.
storage (string)
Место хранения файла ('server', 'yadi'
). По умолчанию, если параметр не определен,
используется значение 'server'
.
'storage' => 'yadi' // by default 'server'
path (string)
Путь до отображаемого на экране (скачиваемого) файла от каталога хранения документов.
На сервере каталог по умолчанию определен как /Documents
и может быть переопределен
в настроечном файле /config/config.php
в параметре server_doc_folder
.
'path' => '/1015/some-file.pdf'
as_attachment (boolean)
Нужно включить данный параметр, если необходимо, чтобы файл независимо от его типа скачивался на компьютер пользователя.
Если данный параметр не определен или false
, то отображение файла в окне или скачивание определяется браузером.
'as_attachment' => true
direct (boolean)
По умолчанию, используются пути к файлам документов, относительно папки /Documents
, которая может находиться по пути, соответствующем
XTABLES_BASE
или пути, определенному в настройках server_doc_folder
. Для использования
прямого пути относительно базовой директории xTables, соответствующей XTABLES_BASE
, нужно
определить данный параметр как true
.
'direct' => true
Для удаления файла можно воспользоваться роутом /xtables-upload/delete-ajax
.
В качестве параметров методом POST должны быть переданы:
id (int)
Идентификатор удаляемого файла в базе данных.
'id' => 24431
table (sting) имя зарезервировано и его передача во входных параметрах блокируется
Таблица в базе данных, где находится информация о файле. По умолчанию определена как attachments
.
'table' => 24431
storage (sting)
Хранилище файла: server
, yadi
; по умолчанию установлено значение server
.
'storage' => 'yadi' // by default server
path (sting)
Относительный путь к файлу от каталога хранения документов: на сервере каталог по умолчанию
определен как /Documents
и может быть переопределен
в настроечном файле /config/config.php
в параметре server_doc_folder
.
'path' => '/some/path/file.pdf'
Для получения сжатого изображения можно использовать класс
\xtables\components\upload\model\CompressImg
,
входящий в состав компонента Upload.
В конструктор нужно передать массив с параметрами:
- int max_width
- максимальная ширина в пикселях;
- int max_height
- максимальная высота в пикселях;
- int quality
- качество изображения в процентах (значение от 0 до 100), по умолчанию
остается исходное качество.
Нужно использовать следующие методы:
Установка пути нахождения временного файла.
Установка имени файла.
Проверка необходимости сжатия с одновременной инициализацией параметров.
Получение сжатого файла. Данный метод должен вызываться только после проверки
методом isNeedCompress
, что сделано для повышения быстродействия и экономии памяти.
$compress = new CompressImg([
'max_width' => 250,
'max_height' => 250,
'quality' => 80
]);
$compress->setPath('tmp/path')->setName('name.jpg');
if ($compress->isNeedCompress()) {
$compressedFile1 = $compress->getCompressed();
}
$compress->setPath('tmp/path2')->setName('name2.jpg');
if ($compress->isNeedCompress()) {
$compressedFile2 = $compress->getCompressed();
}
Возможные настройки описаны выше.