Конвертер изображений в WEBP

1.1.0 (24.07.2025)	Добавлена возможность вывода микроразметки schema.org/ImageObject.
1.0.1 (22.07.2025)	Изменение ключа параметра $params['RESPONSIVE'][]['SRC'] на $params['RESPONSIVE'][]['IMAGE'] в методе \Bitrix\Abcwww\Image::getPicture()

Стандартная установка модуля из MarketPlace.
Модуль не имеет ни каких настроек, он состоит из класса с методами для работы с изображениями.
Обязательно прочитайте инструкцию, в ней есть примеры и ответы на большинство вопросов. Оставляйте комментарии если считаете что нужно что то доработать и данная доработка не для какого то частного случая, а будет полезна для большинства программистов использующих модуль.

Для использования методов модуля на странице, требуется его подключение с помощью вставки кодаЕсли хотите что бы модуль был подключен на всех страницах по умолчанию, то подключите его в init.php и дальше можете использовать его методы на любой странице.

Модуль включает в себя следующие методы:
1) Метод getWebp()
mixed \Bitrix\Abcwww\Image::getWebp(
   mixed $image = false,
   array $params = []
);
В качестве успешного результата вернется путь до результирующего изображения относительно корня сайта (относительно папки DOCUMENT_ROOT). При неудаче вернется false.
Данный метод создает новый файл в формате webp, на основе входных параметров, в которых можно задать нужные размеры и качество и помещает его в папку /upload/image_cache/. Имя файла (кроме его расширения) останется таким же как у оригинала.
При следующих вызовах метода с аналогичными параметрами, будет возвращен результат из кэша (из папки /upload/image_cache/)
Метод проверяет дату создания оригинала, если она увеличилась, то он сконвертирует изображение заново. Т.е. вам не нужно очищать папку /upload/image_cache/ при изменении оригинальной картинки, если она была только что создана и залита вместо старой. Результат обновится автоматически.

Параметры метода:
Параметр $image принимается в нескольких форматах
а) Путь до изображения относительно корня сайта (относительно папки DOCUMENT_ROOT)
б) ID файла в базе из таблицы зарегистрированных файлов b_file
в) Массив с данными файла в формате который возвращает метод CFile::GetFileArray(). Например в таком формате возвращается анонсное изображение $arResult['PREVIEW_PICTURE'] в компоненте bitrix:news.list
г) Массив с данными файла в формате который возвращает метод CFile::ResizeImageGet().

Параметр $params - это массив содержащий настройки для конвертации, он необязательный
array(
   int WIDTH,//ограничение изображения по ширине (необязательный)
   int HEIGHT,//ограничение изображения по высоте (необязательный)
   int QUALITY,//качество изображения от 0 до 100 (необязательный, по умолчанию 100)
);
WIDTH и HEIGHT задаются в виде целого числа (без px), это число означает размер в пикселях. Они могут использоваться как вместе, так и по отдельности. Если указан один из этих параметров, то произойдет сравнение с аналогичным размером исходного изображения. И если указанный параметр меньше значения оригинала, то произойдет пропорциональное уменьшение изображения, иначе размеры останутся оригинальными.
Если указаны 2 параметра, то результирующее изображение уменьшится так же пропорционально, до таких размеров, что бы оно поместилось в прямоугольник с размерами WIDTH x HEIGHT. Работает аналогично стилю в CSS background-size: contain;
Если ни один параметр не задан (WIDTH и HEIGHT), то результирующее изображение создастся с оригинальными размерами.

Пример вызова метода:
\Bitrix\Abcwww\Image::getWebp('/img/picture.jpg', [
   'WIDTH' => 300,
   'HEIGHT' => 300,
   'QUALITY' => 90,
]);

Для  удобства можно использовать сокращенные ключи для параметра $params, это первые буквы ключей массива
Пример вызова метода с сокращенными параметрами
\Bitrix\Abcwww\Image::getWebp('/img/picture.jpg', [
   'W' => 300,
   'H' => 300,
   'Q' => 90,
]);

Если будет указан и полный и аналогичный сокращенный параметр, то приоритет будет у сокращенного.
Например
\Bitrix\Abcwww\Image::getWebp('/img/picture.jpg', [
   'W' => 300,
   'WIDTH' => 400,
]);
В этом случае метод будет считать что вы задали ширину 300


2) Метод getArWebp()
mixed \Bitrix\Abcwww\Image::getArWebp(
   mixed $image = false,
   array $params = []
);
Параметры такие же как и у getWebp(), принцип работы тот же, только в качестве успешного результата вернется массив:
array(
   string 'CONTENT_TYPE',//тип изображения mime 'image/webp'
   string 'SRC',//путь до результирующего изображения относительно корня сайта (относительно папки DOCUMENT_ROOT)
   string 'DESCRIPTION',//описание изображения, если в качестве параметра $image будет указан ID изображения из таблицы b_file, либо массив аналогичный CFile::GetFileArray()
)


3) Метод getResize()
mixed \Bitrix\Abcwww\Image::getResize(
   mixed $image = false,
   array $params = []
);
Метод работает аналогично методу getWebp() с аналогичными параметрами, разница в том что в качестве результата вернется путь до изображения в формате оригинала (без конвертации в формат webp)
Если не задан параметр $params или $params['WIDTH'] и $params['HEIGHT'] больше размеров оригинала, а $params['QUALITY'] не задан или равен 100, то в папке /upload/image_cache/ не будет создан новый файл, а просто вернется путь до оригинального изображения. Это удобная замена стандартному методу CFile::GetPath() но более гибкая.


4) Метод getArResize()
mixed \Bitrix\Abcwww\Image::getArResize(
   mixed $image = false,
   array $params = []
);
Параметры такие же как и у getResize(), принцип работы тот же, только в качестве успешного результата вернется массив:
array(
   string 'CONTENT_TYPE',//тип изображения mime, например 'image/jpeg' или 'image/png' (тип оригинального изображения)
   string 'SRC',//путь до результирующего изображения относительно корня сайта (относительно папки DOCUMENT_ROOT)
   string 'DESCRIPTION',//описание изображения, если в качестве параметра $image будет указан ID изображения из таблицы b_file, либо массив аналогичный CFile::GetFileArray()
)


5) Метод getPicture()
string \Bitrix\Abcwww\Image::getPicture(
   mixed $image = false,
   array $params = []
);
В качестве результата вернется HTML-код тега picture с вложенными в него тегами source и img. Метод удобен для вывода изображений на странице с учетом адаптивной верстки и плотности экрана. Для совместимости со всеми браузерами, в теге picture будут лежать ресурсы как в формате webp, так и в формате оригинального изображения, на тот случай, что бы браузер выбрал сам нужный ресурс, формат которого он поддерживает.

Параметр $image аналогичный параметру $image метода getWebp()
Параметр $params - это массив содержащий настройки для конвертации (необязательный)
array(
   int WIDTH,//аналогичный параметру $params['WIDTH'] метода getWebp() (необязательный)
   int HEIGHT,//аналогичный параметру $params['HEIGHT'] метода getWebp() (необязательный)
   int QUALITY,//аналогичный параметру $params['QUALITY'] метода getWebp() (необязательный)
   array DENSITY,//массив плотностей экрана для разных устройств на которых будет просматриваться страница (необязательный)
   array ATTRIBUTES,//массив атрибутов для тега img (необязательный)
   array RESPONSIVE,//параметры для адаптивной верстки (необязательный)
   array SCHEMA,//вывод микроразметки schema.org/ImageObject (необязательный)
)
Все ключи массива $params аналогично методу getWebp() имеют сокращенные аналоги ключей
array(
   int W,//аналогичный параметру $params['WIDTH'] метода getWebp()
   int H,//аналогичный параметру $params['HEIGHT'] метода getWebp()
   int Q,//аналогичный параметру $params['QUALITY'] метода getWebp()
   array D,//массив плотностей экрана для разных устройств на которых будет просматриваться страница
   array A,//массив атрибутов для тега img
   array R,//параметры для адаптивной верстки
   array S,//вывод микроразметки schema.org/ImageObject
)

$params['SCHEMA'] служит для вывода микроразметки schema.org/ImageObject, он обладает следующей структурой
$params['SCHEMA'] = array(
   string NAME,//Данные для itemprop="name"
   string DESCRIPTION,//Данные для itemprop="description"
);
Если NAME не задан, он возьмется из $params['ATTRIBUTES']['alt']
Если DESCRIPTION не задан, он возьмется из NAME

$params['DENSITY'] если вы хотите выводить изображения с учетом плотности экрана устройства, то задайте массив плотностей, например $params['DENSITY'] = [1.5, 2];
Не рекомендуется в $params['DENSITY'] задавать большое количество вариантов плотностей экрана, учтите что для каждой плотности будет создано отдельное изображение. Рекомендую ограничиться одним значением $params['DENSITY'] = [2]
В массив $params['DENSITY'] не нужно дополнительно добавлять значение 1, для него и так будут созданы изображения по умолчанию.
$params['ATTRIBUTES'] служит для установки нужных атрибутов в тег img, например нужно задать CSS-класс или alt, в качестве ключа массива используйте название атрибута, а в качестве значения его значение
Пример:
<?=\Bitrix\Abcwww\Image::getPicture('/img/picture_desktop.jpg', [
   'A' => [
       'alt' => 'моя картинка',
       'class' => 'my-class',
       'loading' => 'lazy',
   ],
])?>

Если информация о изображении хранится в базе, например это анонсное или детальное изображение элемента инфоблока или свойство тип файл элемента инфоблока и у него в поле с описанием задано значение, то вы можете указать чтобы это описание автоматически подставлялось в атрибут alt тега img. Для этого в качестве $image передавайте ID файла из таблицы b_file или массив аналогичный CFile::GetFileArray(), а в параметре $params['ATTRIBUTES']['alt'] укажите true.
Пример:
<?=\Bitrix\Abcwww\Image::getPicture(127, [
   'A' => [
       'alt' => true,
   ],
])?>

$params['RESPONSIVE'] служит для показа нужных изображений с учетом адаптивной верстки, он обладает следующей структурой
$params['RESPONSIVE'] = array(
   //массив вариантов для @media
   array(
       mixed IMAGE,//аналогичный параметру $image метода getWebp() (необязательный)
       int WIDTH,//аналогичный параметру $params['WIDTH'] метода getWebp() (необязательный)
       int HEIGHT,//аналогичный параметру $params['HEIGHT'] метода getWebp() (необязательный)
       int QUALITY,//аналогичный параметру $params['QUALITY'] метода getWebp() (необязательный)
       array DENSITY,//массив плотностей экрана для разных устройств на которых будет просматриваться страница (необязательный)
       string MEDIA,//строка в формате который задается для тега source в атрибуте media (<source srcset="путь" media="(max-width: 767px)" />) (ОБЯЗАТЕЛЬНЫЙ)
   ),
   ...
   array(
       mixed IMAGE,
       int WIDTH,
       int HEIGHT,
       int QUALITY,
       float DENSITY,
       string MEDIA,
   ),
);
Если нужно для определенного условия @media (например для конкретного разрешения экрана) задать вывод другой картинки, отличной от $image, то укажите ее в $params['RESPONSIVE'][]['IMAGE']. Если изображение не указано, то будет использоваться $image.
Если не указан параметр $params['RESPONSIVE'][]['QUALITY'], то будет использоваться $params['QUALITY']
Учтите что внутри тэга picture сначала будут выводится теги source на основе данных из массива $params['RESPONSIVE'] в том же порядке, что и в массиве $params['RESPONSIVE'], а в самом низу на основе основных параметров $params, поэтому внимательно отнеситесь к этому параметру.
В теге picture условия media работают немного по другому чем в CSS. Если в CSS подходящие условия расположенные ниже по коду перебивают предыдущие, то в picture выбирается самый первый подходящий вариант, а все остальные (что ниже) игнорируются.
Приведу примеры правильного порядка заполнения данных в массиве $params['RESPONSIVE'].
Т.к. в теге picture сперва выводятся source на основе $params['RESPONSIVE'], то в примерах для наглядности перемещу ключ RESPONSIVE в самый верх (порядок основных (верхних) ключей массива $params не влияет на результат).
Если вы отталкиваетесь от широкого экрана в сторону его уменьшения, то задайте параметры в следующем порядке:
<?=\Bitrix\Abcwww\Image::getPicture(
   //Если для разных устройств картинки разные, то в качестве основного изображения $image используется картинка для телефона, а для более широких экранов в RESPONSIVE указываются те что для десктопа
   '/img/picture_mobile.jpg',
   [
       'R' => [
           //Если ширина экрана >= 1024px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'I' => '/img/picture_desktop.jpg',
               'M' => '(min-width: 1024px)',//Если ширина экрана >= 1024px
               'W' => 800,
               'H' => 800,
           ],
           //Если ширина экрана >= 768px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'I' => '/img/picture_desktop.jpg',
               'M' => '(min-width: 768px)',//Если ширина экрана >= 768px
               'W' => 500,
               'H' => 500,
           ],
           //Если ширина экрана >= 400px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'I' => '/img/picture_desktop.jpg',
               'M' => '(min-width: 400px)',//Если ширина экрана >= 400px
               'W' => 300,
               'H' => 300,
           ],
       ],
       //Если не подошел ни один вариант, то выведется изображение с основными параметрами
       'W' => 250,
       'H' => 250,
       'Q' => 90,
       'D' => [2],
       'A' => [
           'alt' => 'моя картинка',
           'class' => 'my-class',
           'loading' => 'lazy',
       ],
   ]
)?>

Если вы отталкиваетесь от узкого экрана в сторону его увеличения, то задайте параметры в следующем порядке:
<?=\Bitrix\Abcwww\Image::getPicture(
   //Если для разных устройств картинки разные, то в качестве основного изображения $image используется картинка для десктопа, а для более узких экранов в RESPONSIVE указывается та что для телефона
   '/img/picture_desktop.jpg',
   [
       'R' => [
           //Если ширина экрана <= 399px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'I' => '/img/picture_mobile.jpg',
               'M' => '(max-width: 399px)',//Если ширина экрана <= 399px
               'W' => 250,
               'H' => 250,
               'D' => [2],
           ],
           //Если ширина экрана <= 767px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'M' => '(max-width: 767px)',//Если ширина экрана <= 767px
               'W' => 300,
               'H' => 300,
           ],
           //Если ширина экрана <= 1023px, то браузер остановится на этом варианте и выведет это изображение, остальные проигнорируются
           [
               'M' => '(max-width: 1023px)',//Если ширина экрана <= 1023px
               'W' => 500,
               'H' => 500,
           ],
       ],
       //Если не подошел ни один вариант, то выведется изображение с основными параметрами
       'W' => 800,
       'H' => 800,
       'Q' => 90,
       'A' => [
           'alt' => 'моя картинка',
           'class' => 'my-class',
           'loading' => 'lazy',
       ],
   ]
)?>
Результат обоих вариантов будет аналогичным, просто кому то удобнее отталкиваться от широких экранов, а кому то от узких. Я же рекомендую второй вариант, он снизит нагрузку на браузер для телефонов, т.к. ему не придется пробегаться по всем условиям, потому что условие для телефона будет среди первых.

Не пугайтесь большого куска кода в примере, тут рассмотрены различные возможности генерации тега picture. На практике же, в большинстве случаев будет использоваться такой вариант:
<?=\Bitrix\Abcwww\Image::getPicture('/img/picture.jpg', [
   'R' => [
       [
           'I' => '/img/picture_mobile.jpg',
           'M' => '(max-width: 399px)',
           'W' => 250,
           'D' => [2],
       ],
   ],
   'W' => 800,
   'A' => [
       'alt' => 'моя картинка',
       'class' => 'my-class',
       'loading' => 'lazy',
   ],
])?>

Или такой
<?=\Bitrix\Abcwww\Image::getPicture('/img/picture.jpg', [
   'W' => 800,
   'A' => [
       'alt' => 'моя картинка',
       'class' => 'my-class',
       'loading' => 'lazy',
   ],
])?>

Или даже такой
<?=\Bitrix\Abcwww\Image::getPicture('/img/picture.jpg')?>

Поддержка осуществляется через обращения на почту marketplace@abcwww.ru
При обращении указывайте название модуля и купон, полученный при покупке решения.