Download the PHP package karelwintersky/arris.php-file-upload without Composer
On this page you can find all versions of the php package karelwintersky/arris.php-file-upload. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download karelwintersky/arris.php-file-upload
More information about karelwintersky/arris.php-file-upload
Files in karelwintersky/arris.php-file-upload
Package arris.php-file-upload
Short Description Powerful PHP8 file upload library with validation, conversion, and fluent interface
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package arris.php-file-upload
FileUpload - PHP8 File Upload Library
Библиотека для загрузки файлов с валидацией, конвертацией изображений и Fluent Interface.
Требования
- PHP 8.2+
- ext-fileinfo
- ext-gd (опционально, для конверсии изображений)
Установка
Быстрый старт
Два этапа загрузки
1. uploaded() — проверка первичной загрузки
Проверяет is_uploaded_file(), выполняет полную валидацию (MIME, размер, кастомные валидаторы).
Возвращает FileUploadResult с stage=uploaded. На этапе uploaded уже доступны size и mimeType.
2. process() — конверсия, сохранение
Если uploaded() уже вызван и прошёл успешно — process() пропускает валидацию (флаг validated).
Если вызван напрямую — выполняет валидацию сам.
Конфигурация
Дефолтный конфиг (один раз при бутстрапе)
Опция через applyOption()
Fluent-конфигурация на инстансе
Генератор имени файла (filenameGenerator)
Генератор решает, какое имя (без пути) получит сохраняемый файл внутри targetPath.
Устанавливается тремя способами: в setDefaultConfig(...), через
applyOption('filenameGenerator', ...) или fluent setFilenameGenerator(callable).
Текущая сигнатура (breaking change от 2026-09-18): генератор принимает один
аргумент — FileUploadResult стадии uploaded (дескриптор исходного файла)
и возвращает строку — имя файла с расширением:
Что доступно внутри генератора
Все метаданные уже вычислены библиотекой на стадии uploaded(), генератору не
нужно читать файл повторно:
| Поле | Что это | Типичное применение |
|---|---|---|
$source->mimeType |
Реальный MIME по содержимому файла (mime_content_type(tmp_name)), а не $_FILES[*]['type'] — тот приходит от браузера и ему доверять нельзя |
Расширение по содержимому |
$source->tmpName |
Временный путь загруженного файла ($_FILES[*]['tmp_name']) |
Анализ, копирование |
$source->relativePath |
Путь, как его прислал клиент ($_FILES[*]['full_path']); для одиночной загрузки совпадает с originalName |
Расширение из клиентского пути, сохранение подкаталогов |
$source->originalName |
Исходное имя файла на клиенте | Фолбэк для расширения/радикса |
$source->width / $source->height |
Геометрия изображения (только image/*) | Суффикс размера |
$source->size |
Размер в байтах | Суффикс размера |
Типовой сценарий: расширение по реальному содержимому
Классическая ошибка — брать расширение из originalName: пользователь может
загрузить .jpg под именем .png, и файл сохранится с неверным расширением
(файл на диске ↔ запись в БД разойдутся). Правильно — определять расширение по
реальному MIME с фолбэком на имя, если формат не распознан:
Хорошо показал себя следующий генератор:
Порядок вызова внутри process()
ensureUploadedResult()готовит дескриптор: берёт уже кэшированный результатuploaded(); если вызывался толькоvalidate()— собирает дескриптор из провалидированного файла; иначе — запускаетuploaded().- Генератор вызывается до
move_uploaded_file()и до конверсии. - Если генератор не установлен — дефолт: исходное имя, а при коллизии имени в
targetPath—name_1.ext,name_2.ext, ...
Примечания
- Генератор возвращает только имя файла, без
targetPath. - При заданной конверсии (
targetMimeType) библиотека сама подменит расширение черезchangeExtension()(напримерimage/jpeg→.jpg) — возвращать итоговое расширение целевого формата в генераторе не требуется. - Возвращённое значение не проходит санитизацию: для безопасного имени (без
/,.., спецсимволов) нормализуйте его внутри генератора. - MIME-детект выполняется один раз на экземпляр и кэшируется (
detectMimeType()); повторныеmime_content_type()в генераторе избыточны — используйте готовый$source->mimeType.
Валидация
Встроенные валидаторы
Кастомные валидаторы
Функции-коллбэки, которые принимают массив файла и возвращают:
true— валидация пройденаfalse— валидация не пройдена, в ошибки запишется дефолтное сообщение "Ошибка валидации файла"- строка — валидация не пройдена, в ошибки запишется указанная строка
Порядок и collect-all
Валидация выполняется в следующем порядке:
- Прекондишины (fail-fast): файл не задан → не загружен через HTTP → PHP upload-ошибка
- Встроенные валидаторы: MIME-тип → минимальный размер → максимальный размер
- Кастомные валидаторы: все по порядку
Встроенные и кастомные валидаторы работают в режиме collect-all: все проверки выполняются, все ошибки собираются. Пользователь видит все проблемы сразу, а не только первую попавшуюся.
Конверсия изображений
Конвертирует изображение из одного формата в другой при перемещении в storage.
Для этого нужно указать целевой mime-тип и качество. Третий параметр $force заставляет применить конвертер даже если целевой mime-тип совпадает с исходным — это позволяет приводить загруженные фотографии к общему стандарту (пережатие).
Принудительная конвертация ($force)
Кастомный конвертер
Поддерживаемые форматы
| Формат | Источник | Цель |
|---|---|---|
| JPEG | yes | yes |
| PNG | yes | yes |
| GIF | yes | yes |
| WebP | yes | yes |
| BMP | yes | — |
Система ошибок
Коды ошибок
Каждая ошибка имеет код FileUploadErrorCode (backed enum). Доступны через getErrorStack():
Трансляция сообщений
getErrors() возвращает массив человекочитаемых строк (через FileUploadErrorMessages):
Кастомизация сообщений
Параметры в шаблонах: {mime_type}, {message} — подставляются из params.
Локализация (i18n)
Встроенные locales: ru (по умолчанию) и en.
Обработка ошибок
Тихий режим (по умолчанию)
Режим исключений
Множественная загрузка
FileUploadResult
Объект возвращаемый uploaded() и process().
| Поле | Тип | Описание |
|---|---|---|
isSuccess |
bool |
Успешность операции |
stage |
string\|null |
'uploaded' или 'processed' |
originalName |
string\|null |
Оригинальное имя файла |
savedName |
string\|null |
Имя файла в storage |
path |
string\|null |
Путь к каталогу storage |
fullPath |
string\|null |
Полный путь к файлу |
mimeType |
string\|null |
MIME-тип |
size |
int\|null |
Размер в байтах |
lastError |
string\|null |
Последняя ошибка |
errors |
array |
Массив ошибок |
radix |
string\|null |
Имя файла без расширения |
extension |
string\|null |
Расширение без точки |
width |
int\|null |
Ширина (image/*) |
height |
int\|null |
Высота (image/*) |
tmpName |
string\|null |
Временный путь (tmp_name) исходного файла; заполнен на стадии uploaded |
relativePath |
string\|null |
Путь, как его передал клиент ($_FILES[*]['full_path']); для обычной загрузки = originalName |
Доступные опции
| Опция | Тип | Описание |
|---|---|---|
targetPath |
string |
Каталог для сохранения |
allowedMimeTypes |
array |
Разрешённые MIME-типы |
maxFileSize |
int |
Максимальный размер (байты) |
minFileSize |
int |
Минимальный размер (байты) |
filenameGenerator |
callable |
Генератор имени файла fn(FileUploadResult $source): string |
throwExceptions |
bool |
Бросать FileUploadException вместо возврата ошибки |
validators |
array |
Массив callable-валидаторов |
targetMimeType |
string |
Целевой MIME-тип для конверсии |
targetImageQuality |
int |
Качество конверсии (0-100) |
locale |
string |
Локаль для сообщений ошибок ('ru' или 'en') |
Вспомогательные классы
Все вспомогательные классы находятся в неймспейсе Arris\Toolkit\FileUpload\*.
ImageConvertor
Конвертирует изображения между форматами (GD). Fluent API:
Поддерживаемые конверсии: JPEG, PNG, GIF, WebP, BMP → JPEG/PNG/GIF/WebP.
MediaProbe
Обёртка над ffprobe для получения метаданных медиафайлов:
Возвращает MediaProbeResult (readonly value object) или null при ошибке.
Helper
Статический хелпер для работы с размерами файлов и лимитами загрузки:
Лицензия
MIT License
All versions of arris.php-file-upload with dependencies
ext-fileinfo Version *
ext-gd Version *