---

Получение простой формы для загрузки файлов

@since version 1.6.7

simpleForm(string $action, array $hiddenInputs = [], bool $multiple = true, bool $serverOnly = false): string

Для получения простой формы для загрузки файлов через ajax можно использовать доступный через статический прокси интерфейс метод
simpleForm($action, array $hiddenInputs = [], $multiple = true, $serverOnly = false).
В метод нужно передать:

• string $action - url, по которому должны быть отправлены данные;
• array $hiddenInputs - массив скрытых инпутов;
• boolean $multiple - требуется ли одновременная загрузка нескольких файлов (по умолчанию), если не нужно, то данный параметр нужно определить как false;
• boolean $serverOnly - должна ли показываться форма для выбора места загрузки файлоав (сервер, Яндекс.Диск), по умолчанию - нет, если нужно, то данный параметр надо определить как true.

Данная форма передаст по пути, соответствующему $action, данные в скрытых инпутах и файлы, массив которых будет обозначен именем userfile.

После обработки переданных данных ответ сервера будет обработан типовым образом с использованием функции xtables.serverReplyHandle.

Upload::simpleForm('/some-upload/url', [
    'name' => 'value',
    'else_name' => 'else_value'
], false, true)

Компонент Upload может использоваться для:

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

---

Загрузка файлов на сервер или Яндекс.Диск

Для загрузки файлов на сервер нужно создать экземпляр класса 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.

'for_id' => 1111

'for_id' => 'some\classto\GetFrom::func'
    

thumbnail (string)

Если при сохранении файла-изображения (может использоваться только для изображений в форматах JPG и PNG), необходимо создавать и сохранять миниатюры, то нужно определить данный параметр со значением размера миниатюры в пикселях через :. Миниатюра будет сохранена в каталог thumbnails в том же каталоге, где будет сохраняться основное изображение, то есть пути основного изображения и миниатюры будут отличаться лишь наличием дополнительного каталога thumbnail.

'thumbnail' => '75:75'
    

compress (array)

Если при сохранении файла-изображения (может использоваться только для изображений в форматах JPG и PNG), необходимо сжимать изображение, изменяя его размер или качество, то нужно определить данный параметр. Другие форматы файлов затронуты не будут.
Могут быть использованы следующие параметры:

• int max_width - максимальная ширина в пикселях, при превышении будет уменьшена до заданной ширины, высота будет изменена с сохранением пропорций изображения;
• int max_height - максимальная высота в пикселях, при превышении будет уменьшена до заданной высоты, ширина будет изменена с сохранением пропорций изображения;
• int 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'
    

---

CompressImg

Для получения сжатого изображения можно использовать класс \xtables\components\upload\model\CompressImg, входящий в состав компонента Upload. В конструктор нужно передать массив с параметрами:
- int max_width - максимальная ширина в пикселях;
- int max_height - максимальная высота в пикселях;
- int quality - качество изображения в процентах (значение от 0 до 100), по умолчанию остается исходное качество.

Нужно использовать следующие методы:

setPath(string $path): CompressImg

Установка пути нахождения временного файла.

setName(string $name): CompressImg

Установка имени файла.

isNeedCompress(): bool

Проверка необходимости сжатия с одновременной инициализацией параметров.

getCompressed(): string

Получение сжатого файла. Данный метод должен вызываться только после проверки методом 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();
}

---

Возможные настройки описаны выше.