Функции изображений Albireo CMS

convertToWebp createImageText hIMG hIMG_src hThumb parseImageSize

Функция convertToWebp

Функция convertToWebp предназначена для пакетной (массовой) конвертации изображений из указанного каталога в современный формат WebP. Она автоматически находит все подходящие файлы, вызывает для каждого из них функцию-хелпер hThumb для выполнения конвертации и возвращает массив URL-адресов полученных WebP-изображений.

Сигнатура

function convertToWebp(string $dir, string $mask = '*.{jpg,png,webp}', int $quality = 85): array

Аргументы

string $dir: URL-адрес каталога на сайте, содержащего изображения для конвертации. Этот URL будет преобразован в реальный путь на сервере.
string $mask (необязательный): Маска для поиска файлов в формате, который понимает функция PHP glob(). По умолчанию '*.{jpg,png,webp}', что означает поиск всех файлов с расширениями jpg, png или webp.
int $quality (необязательный): Качество сжатия для итоговых WebP-файлов. Значение от 0 до 100. По умолчанию 85.

Результат

Возвращает индексированный массив (array), содержащий URL-адреса сконвертированных (или уже существовавших) WebP-изображений.

Примеры использования

Пример 1: Базовая конвертация каталога

Предположим, в каталоге /uploads/my-gallery/ лежат файлы photo1.jpg и photo2.png.

$galleryUrl = SITE_URL . 'uploads/my-gallery/';
$webpVersions = convertToWebp($galleryUrl);

// $webpVersions будет содержать примерно такой массив:
// [
//     'https://mysite.com/uploads/my-gallery/photo1.webp',
//     'https://mysite.com/uploads/my-gallery/photo2.webp'
// ]
print_r($webpVersions);

Пример 2: Практическое применение для создания тега <picture>

Функцию можно использовать для подготовки WebP-версий, чтобы затем отобразить их с фолбэком на оригинальный формат.

$originalImage = UPLOADS_URL . 'my-gallery/photo1.jpg';

// Получаем URL webp-версии. Так как файл один, массив будет содержать один элемент.
$webpUrlArray = convertToWebp(UPLOADS_URL . 'my-gallery/', 'photo1.jpg');
$webpUrl = $webpUrlArray[0] ?? '';

if ($webpUrl) {
    echo '<picture>';
    echo '  <source srcset="' . $webpUrl . '" type="image/webp">';
    echo '  <source srcset="' . $originalImage . '" type="image/jpeg">';
    echo '  <img src="' . $originalImage . '" alt="Описание">';
    echo '</picture>';
}

Примечания

Права доступа: Веб-сервер должен иметь права на запись в каталог, где находятся исходные изображения, так как WebP-версии будут создаваться рядом с ними.
Кеширование: Благодаря механизму кеширования в hThumb, конвертация будет выполнена только один раз. При последующих вызовах функция будет просто возвращать пути к уже существующим файлам.
Именование: Используется опция keepName: true, что означает, что файл image.jpg будет сконвертирован в image.webp, а не в файл с размерами в имени.

Функция createImageText

Функция createImageText предназначена для динамической генерации изображений путем наложения текста на существующее фоновое изображение. Это полезно для создания Open Graph изображений, баннеров, персонализированных открыток и т.п. Функция работает исключительно с форматом WebP.

Сигнатура

function createImageText(string $result, string $src, string $text, int $sizeText, string $colorText, string $colorShadow, string $ttfFont, int $quality = 85, bool $textAlign = true, bool $action = true): string|false

Аргументы

Рекомендуется использовать именованные аргументы для вызова этой функции.

string $result: Полный путь на сервере для сохранения итогового WebP-файла. Если путь начинается с //, он будет заменен на значение константы UPLOADS_DIR.
string $src: Путь к исходному фоновому изображению. Должен быть в формате WebP. Поддерживает сокращение //.
string $text: Текст для наложения. Для переноса строки используется специальная последовательность //.
int $sizeText: Размер шрифта в пунктах (pt).
string $colorText / $colorShadow: Цвет текста и его тени в шестнадцатеричном формате (HEX) без символа #. Например, 'FFFFFF'.
string $ttfFont: Путь к файлу шрифта в формате TrueType (.ttf). Поддерживает сокращение //.
int $quality (необязательный): Качество сжатия для итогового WebP-файла (от 0 до 100). По умолчанию 85.
bool $textAlign (необязательный): Если true (по умолчанию), функция попытается выровнять строки многострочного текста по правому краю путем добавления пробелов слева. Это не является истинным центрированием.
bool $action (необязательный): Флаг-переключатель. Если true (по умолчанию), изображение будет создано. Если false, функция не будет выполнять никаких действий и просто вернет предполагаемый путь к файлу $result.

Результат

Возвращает строку (string) с полным путем к созданному файлу в случае успеха, или false в случае ошибки (например, если не найден исходный файл или шрифт).

Примеры использования

Пример 1: Генерация Open Graph изображения для статьи

// Данные статьи
$postTitle = "Как использовать PHP для генерации изображений";
$ogImageFile = UPLOADS_DIR . 'ogp/' . 'post-123.webp';

// Создаем изображение, только если его еще нет
if (!file_exists($ogImageFile)) {
    createImageText(
        result: $ogImageFile,
        src: '//backgrounds/og-template.webp',
        text: $postTitle,
        sizeText: 55,
        colorText: 'FFFFFF',
        colorShadow: '1a1a1a',
        ttfFont: '//fonts/Inter-Bold.ttf',
        quality: 90
    );
}

Пример 2: Использование многострочного текста

createImageText(
    result: '//banners/promo.webp',
    src: '//backgrounds/blue.webp',
    text: "Большая распродажа!//Скидки до 50%",
    sizeText: 80,
    colorText: 'FFFF00',
    colorShadow: '000000',
    ttfFont: '//fonts/Impact.ttf'
);

Примечания

Ограничение формата: Функция работает только с WebP как для исходного, так и для итогового изображения.
Зависимости: Требуется наличие PHP-расширения GD с поддержкой FreeType.
Права доступа: Веб-сервер должен иметь права на запись в каталог, указанный в параметре $result.
Шрифты: Для корректной работы необходимо указать путь к существующему .ttf файлу шрифта.

Функция hIMG

Функция-хелпер hIMG предназначена для удобного и гибкого формирования HTML-тега <img>. Она поддерживает множество сокращений и плейсхолдеров, что позволяет писать более чистый и короткий код в шаблонах.

Сигнатура

function hIMG(string $src, array $attr = [], ?string $link = null, string $linkClass = '', string $linkAdd = ''): string

Аргументы

string $src

Путь к изображению. Может использовать специальные плейсхолдеры, которые разрешаются с помощью функции hIMG_src():

@UPLOADS_URL@image.jpg — использует значение PHP-константы UPLOADS_URL.
[images-dir]image.jpg — использует значение из метаданных страницы getPageData('images-dir').
//image.jpg — сокращение для @UPLOADS_URL@image.jpg.

array $attr (необязательный)

Ассоциативный массив атрибутов для тега <img>. Поддерживает следующие особенности:

Сокращения: 'w' преобразуется в width, а 'h' — в height.
Объединенные ключи: Ключ вида 'alt/title' создаст оба атрибута (alt="..." и title="...") с одинаковым значением.
Авто-размеры: Если в массиве присутствует элемент 'auto', функция попытается определить реальные размеры изображения из файла и подставить их в width и height.
Булевы атрибуты: Элемент без ключа, например 'async', будет добавлен как async="async".

string|null $link (необязательный)

Если параметр задан, тег <img> будет обернут в ссылку <a>.

Если $link = '' (пустая строка), ссылка будет вести на само изображение ($src).
Если $link содержит URL, ссылка будет вести на этот URL.
Если $link = null (по умолчанию), ссылка не создается.

string $linkClass (необязательный)

CSS-класс для ссылки, если она создается.

string $linkAdd (необязательный)

Строка с дополнительными атрибутами для ссылки (например, 'target="_blank"').

Результат

Возвращает готовую HTML-строку (string) с тегом <img>, возможно, обернутым в тег <a>.

Примеры использования

Пример 1: Базовое использование с сокращениями

echo hIMG('//images/my-photo.jpg', [
    'w' => 200, 
    'h' => 150, 
    'alt/title' => 'Моя фотография',
    'class' => 'user-avatar'
]);

// Результат:
// <img src=".../uploads/images/my-photo.jpg" width="200" height="150" alt="Моя фотография" title="Моя фотография" class="user-avatar">

Пример 2: Автоматическое определение размеров

Функция сама определит размеры файла real-image.png на сервере.

// Предполагается, что UPLOADS_URL и UPLOADS_DIR указывают на соответствующие пути
echo hIMG('@UPLOADS_URL@real-image.png', ['auto', 'alt' => 'Картинка в реальном размере']);

// Результат (если размеры файла 800x600):
// <img src=".../uploads/real-image.png" width="800" height="600" alt="Картинка в реальном размере">

Пример 3: Создание превью-ссылки на полное изображение

$thumbSrc = '//gallery/thumbs/photo-01.jpg';
$fullSrc = hIMG_src('//gallery/full/photo-01.jpg'); // Получаем полный путь заранее

echo hIMG($thumbSrc, ['w' => 150, 'alt' => 'Превью'], $fullSrc, 'lightbox');

// Результат:
// <a href=".../uploads/gallery/full/photo-01.jpg" class="lightbox"><img src=".../uploads/gallery/thumbs/photo-01.jpg" width="150" alt="Превью"></a>

Примечания

Безопасность: Все значения атрибутов автоматически экранируются с помощью htmlspecialchars() для предотвращения XSS-атак.

Функция hIMG_src

Функция hIMG_src является вспомогательным инструментом для преобразования сокращенных и абстрактных путей к файлам (чаще всего изображениям) в полные, рабочие URL-адреса. Она распознает специальные плейсхолдеры, которые заменяются на значения из констант PHP или метаданных текущей страницы. Обычно используется внутри других функций, таких как hIMG() и hThumb().

Сигнатура

function hIMG_src(string $src): string

Аргументы

string $src

Входная строка с путем. Может быть одного из следующих форматов:

Обычный URL: https://example.com/image.jpg — останется без изменений.
Путь с плейсхолдером константы: @UPLOADS_URL@image.jpg — @UPLOADS_URL@ будет заменено на значение константы UPLOADS_URL.
Путь с плейсхолдером данных страницы: [gallery_dir]image.jpg — [gallery_dir] будет заменено на значение, полученное из getPageData('gallery_dir').
Сокращенный путь: //image.jpg — префикс // будет заменен на @UPLOADS_URL@, который затем будет обработан как плейсхолдер константы.

Результат

Возвращает итоговую строку (string) с полным URL-адресом или путем к файлу.

Примеры использования

Пример 1: Использование PHP-константы (...)

Удобно для указания путей к ресурсам шаблона или системным каталогам.

// Где-то в конфигурации определена константа
define('THEME_URL', '/assets/themes/default/');

$iconPath = hIMG_src('@THEME_URL@icons/home.svg');

// $iconPath будет '/assets/themes/default/icons/home.svg'
echo $iconPath;

Пример 2: Использование данных страницы ([...])

Полезно, когда путь к файлам зависит от текущей страницы или записи (например, галерея изображений для конкретного поста).

// Предположим, для текущей страницы getPageData('images-dir') вернет '/uploads/posts/123/'
$imagePath = hIMG_src('[images-dir]header.jpg');

// $imagePath будет '/uploads/posts/123/header.jpg'
echo $imagePath;

Пример 3: Использование сокращения для каталога загрузок (//)

Это самый короткий способ указать путь к файлу в основном каталоге загрузок.

// Предположим, константа UPLOADS_URL равна 'https://site.com/uploads/'
$avatarPath = hIMG_src('//avatars/user1.png');

// $avatarPath будет 'https://site.com/uploads/avatars/user1.png'
echo $avatarPath;

Примечания

Функция является вспомогательной и предназначена для использования внутри других функций-хелперов.
Все обратные слэши (\) в пути автоматически заменяются на прямые (/) для унификации.

Функция hThumb

Функция hThumb — это комплексный инструмент для создания и отображения миниатюр изображений. Она автоматизирует процесс генерации уменьшенных копий "на лету", их кеширования (в виде файлов) и вывода готового HTML-кода. Рекомендуется использовать именованные аргументы при вызове для повышения читаемости кода.

Сигнатура

function hThumb(string $src, int $width = 0, ...): string|void

Аргументы

string $src: Путь к исходному (большому) изображению. Поддерживает плейсхолдеры, как и функция hIMG().
int $width / $height: Целевые размеры миниатюры. Если один из параметров равен 0, размеры будут вычислены пропорционально.
string $wh: Альтернативный способ задания размеров в виде строки 'ширина x высота' (например, '800x600'). Имеет приоритет над $width и $height.
string $ext: Формат итоговой миниатюры ('webp', 'jpg', 'png', 'gif'). По умолчанию 'webp'.
array $attr: Массив атрибутов для итогового тега <img>. Передается в функцию hIMG() и поддерживает все её сокращения (w, h, alt/title, auto).
array $link: Если массив не пуст, изображение будет обернуто в ссылку <a>, ведущую на исходное (большое) изображение. Элементы массива станут атрибутами ссылки.
int $quality: Качество сжатия для форматов JPG и WEBP (от 0 до 100). По умолчанию 80.
bool $urlOnly: Если true, функция вернет только URL-адрес созданной миниатюры, а не HTML-код.
bool $keepName: Если true, имя файла миниатюры будет таким же, как у оригинала (изменится только расширение, если оно отличается от исходного). Это отключает добавление размеров в имя файла.
int $method: Метод изменения размера из библиотеки ZebraImage. По умолчанию 6 (ZEBRA_IMAGE_CROP_CENTER), что означает обрезку по центру до точных размеров.
bool $compareSize: Если true (по умолчанию), миниатюра не будет создаваться, если её целевые размеры совпадают с размерами исходного файла. В этом случае будет использован исходный файл.
bool $alert: Если true, будут выводиться сообщения об ошибках (например, если исходный файл не найден).

Результат

Возвращает строку (string) с готовым HTML-кодом тега <img> (возможно, обернутого в <a>). Если $urlOnly = true, возвращает строку с URL-адресом миниатюры. В случае критической ошибки (например, файл не найден) ничего не возвращает (void).

Примеры использования

Пример 1: Создание простой миниатюры

// Создать миниатюру шириной 400px, высота — пропорционально
echo hThumb(
    src: '@UPLOADS_URL@my-photo.jpg',
    width: 400,
    attr: ['alt' => 'Моя фотография', 'class' => 'post-thumbnail']
);

Пример 2: Создание превью-ссылки для галереи (Lightbox)

Создается квадратная миниатюра 150x150, которая является ссылкой на полное изображение.

echo hThumb(
    src: '//gallery/image1.jpg',
    wh: '150x150', // Используем wh для краткости
    method: 6, // Обрезка по центру
    link: ['class' => 'glightbox', 'data-gallery' => 'my-gallery'],
    attr: ['alt' => 'Посмотреть в полном размере']
);

Пример 3: Получение только URL для Open Graph

Для мета-тегов нужен только URL, а не весь HTML. Также можно сменить формат на лету.

$ogImageUrl = hThumb(
    src: '@UPLOADS_URL@default-og-image.png',
    wh: '1200x630',
    ext: 'jpg', // Конвертируем в JPG для лучшей совместимости
    quality: 85,
    urlOnly: true
);

if ($ogImageUrl) {
    echo '<meta property="og:image" content="' . $ogImageUrl . '">';
}

Примечания

Именование файлов: По умолчанию миниатюры сохраняются с суффиксом, содержащим их размеры и слово -thumb (например, my-image@300x200-thumb.webp). Это позволяет кешировать разные размеры одного и того же изображения.
Производительность: Создание изображения — ресурсоемкая операция, но она выполняется только один раз. При последующих запросах функция находит уже созданный файл и мгновенно отдает его.

Функция parseImageSize

Функция parseImageSize предназначена для разбора (парсинга) строки, содержащей размеры изображения, и преобразования её в числовой массив. Она гибко обрабатывает различные разделители между шириной и высотой, такие как 'x', пробел или любой другой нецифровой символ.

Сигнатура

function parseImageSize(string $wh): array

Аргументы

string $wh: Строка с размерами для разбора. Например: '800x600', '1024 x 768', '1920-1080'.

Результат

Возвращает индексированный массив (array) из двух целых чисел [ширина, высота] в случае успешного разбора, или пустой массив [], если входная строка имеет некорректный формат.

Примеры использования

Пример 1: Базовый разбор разных форматов

$size1 = parseImageSize('800x600');     // [800, 600]
$size2 = parseImageSize('1024 x 768');  // [1024, 768]
$size3 = parseImageSize('1920---1080'); // [1920, 1080]

print_r($size1);
print_r($size2);
print_r($size3);

Пример 2: Практическое применение в функции

Функцию можно использовать для получения размеров при обработке изображений.

function resizeImage(string $filePath, string $newSizeStr)
{
    $size = parseImageSize($newSizeStr);

    if (!$size) {
        echo "Ошибка: Некорректный формат размера '{$newSizeStr}'.";
        return;
    }

    list($width, $height) = $size;

    // ... здесь могла бы быть логика изменения размера изображения ...
    echo "Изображение '{$filePath}' будет изменено до {$width}x{$height}.";
}

resizeImage('my_photo.jpg', '300x200');

Пример 3: Обработка пользовательского ввода

При получении данных от пользователя важно проверять результат на корректность.

$userInput = 'неверные данные';
$dimensions = parseImageSize($userInput);

if (empty($dimensions)) {
    echo "Ошибка: введены некорректные данные для размеров изображения.";
} else {
    echo "Ширина: {$dimensions[0]}, Высота: {$dimensions[1]}";
}