README

Задачи компонента:

автоматически создавать уменьшенные копии исходного изображения требуемых размеров
при повторном обращении, отдавать изображения вэб-сервером, без запуска скриптов

Внимание! Для работы должно быть установлено расширение ImageMagick.

Установка

composer require m00nk/dynimage

Настройка приложения

'componemts' => [
	...
	'dynimage' => [
		'class' => 'm00nk\dynimage\DynImageComponent',
	],
	...
	'urlManager' => [
		...
		'rules' => [
			...
			'assets/dynimg/<filepath:.+>' => 'dynimage/get-image'
		]
	],
	...
],

'controllerMap' => [
	...
	'dynimage' => [
		'class' => 'm00nk\dynimage\controllers\ProcessController'
	],
	...
]

Компонент имеет несколько параметров:

cachePath - путь относительно корня сайта к папке кэша изображений. По-умолчанию '/assets/dynimg'. Эта папка должна быть доступна из броузера.
sizes - массив допустимых размеров изображений (ширина). Используется только при автоматическом определении ширины.
jpegQuality - уровень качества для JPEG-файлов

Пример задания параметров через конфигурацию:

'componemts' => [
	...
	'dynimage' => [
		'class' => 'm00nk\dynimage\DynImageComponent',
		'jpegQuality' => 60,
		'sizes' => [50, 200, 800, 1400],
		'cachePath' => '/uploads/images/cache',
		'engineClass' => \Imagine\Gmagick\Imagine::class, // меняем графический движок
	],
	...
	'urlManager' => [
		...
		'rules' => [
			...
			'uploads/images/cache/<filepath:.+>' => 'dynimage/get-image'
		]
	],
	...
]
	...

Обратите внимание, что при смене папки кэша, нужно менять и правило в UrlManager, чтобы компонент мог правильно перехватывать запросы к несуществующим файлам.

Все необходимые для работы папки (включая папку кэша) компонент создает автоматически.

Принцип работы

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

Использование

Есть два варианта использования:

создание изображений с заранее известными размерами
создание изображений с автоматическим вычислением ширины

Cоздание изображений с заранее известными размерами

Компонент позволяет получить URL изображения, используя заранее известные параметры результирующего изображения. Для этого используется метод DynImageComponent::getUrl:

echo Html::img(
	Yii::$app->dynimage->getUrl(
		// путь к исходному изображению относительно корня сайта
		'/uploads/images/my-photo.png',
		 
		 // ширина результирующего изображения
		 320,
			 
		 // высота будет вычислена автоматически с сохранением пропорций
		 null,
			 
		 // на выходе получим JPEG-файл
		 'jpg'
	),
	['class' => 'css-avatar']
);

Код выше вставит на страницу HTML-тег вида

<img src="/assets/dynimag/uploads/images/my-photo.png=320x0x70.jpg" class="css-avatar" />

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

Cоздание изображений с автоматическим вычислением ширины

Если необходимо, чтобы изображения создавались с автоматически вычисляемой шириной, нужно использовать метод DynImageComponent::img:

echo Yii::$app->dynimage->img(
	// путь к исходному изображению относительно корня сайта
	'/uploads/images/my-photo.png',
		 
	 // на выходе получим JPEG-файл
	 'jpg',
	 
	 // качество берем из настроек компонента
	 null,
	 
	['class' => 'css-avatar']
);

Код выше создаст псевдо-тег <img-dyn ... /> с необходимыми параметрами и загрузит JavaScript, который сразу после загрузки страницы просканирует все такие теги и заменит их соответствующими HTML-тегами . Для каждого такого тега будет вычислена ширина, исходя из ширины контейнера.

Замечания по работе

При автоматическом вычислении ширины компонент создает изображения с шириной, округленной в большую сторону.

Например:

в настройках указаны размеры [50, 400, 1200], компонент создаст изображения шириной:

50 точек для всех контейнеров <= 50 точек
400 точек для всех контейнеров > 50 и <= 400 точек
1200 точек для всех контейнеров > 400 точек

Особенности nginx

Вэб-сервер nginx работает немного отлично от Apache, в частности при использовании настроек кэширования вида

location ~* \.(?:jpe?g|png|gif|webp|wbmp|xbm)$ {
    expires 7d;
    add_header Pragma public;
    add_header Cache-Control "public";
    gzip_vary on;
}

при отсутствии требуемого файла nginx не будет запускать приложение! Поэтому, при использовании nginx, нужно отключить кэширование файлов изображений в папке кэша, заданной в параметрах компонента.

m00nk / yii2-dynimage

Maintainers

Details