index.md

Quickstart

This extension brings you ability to store images in your application and serve them on-demand to your visitors.

Concept

Basic concept of this extensions is to use independent data storage based on Flysystem extension. For example for each module or part of your application. Sou you can have e-shop images storage for e-shop module, or users avatars storage to store users avatars.

Second important think is, all storage services can store files outside of document root folder even on some cloud servers like AWS or own cloud.

Installation

The best way to install ipub/images is using Composer:

$ composer require ipub/images

After that you have to register extension in config.neon.

extensions:
	images: IPub\Images\DI\ImagesExtension

Usage

Basic configuration

At first you have to register your storage services in Flysystem extension.

Providers

This extension come with default presenter provider which is registered automatically. If you want to use this provider, you have to specify at least one route and public web directory:

images:
	routes:
		- "/images[/<namespace .+>]/<size>[-<algorithm>]/<filename>.<extension>"
	wwwDir: path/to/document/root
	presenterProvider: true # Default value is true, if you want to disable set it to false

Required parameters for each route are:

• namespace: it is used for folders and sub-folders
• size: it define output image size
• filename: stripped filename without extension
• extension: filename extension

Routes can be defined with additional params like in Nette:

images:
	routes:
		"/images[/<namespace .+>]/<size>[-<algorithm>]/<filename>.<extension>"  :
			defaultParam : defaultValue
			otherParam : otherValue

Second mandatory parameter is wwwDir. With this parameter you have to specify absolute path to your document root folder where will be saved generated images.

By default all these routes will be prepended before your other routes - assuming you use Nette\Application\Routers\RouteList as your root router. You can disable this by setting prependRoutesToRouter: false. Then it's your responsibility to plug extension router (service images.router) to your routing implementation.

Using in Latte

This extension gives you new latte macro n:src. Now you're ready to use it.

<a n:src="providerName:storageName://products/filename.jpg"><img n:src="providerName:storageName://products/filename.jpg, 200x200, fill" /></a>

output:

<a href="/images/products/original/filename.jpg"><img src="/images/products/200x200-fill/filename.jpg" /></a>

Parameters of this macro are:

• path - full path to the image with storage name and images provider eg.: presenter:eshopStorage://some/namespace/product-image.jpg
• size - image size. It could be only width or width and height eg.: 150 or 50x50
• algorithm - (optional) resize algorithm which is used to convert image

Resizing algorithm

For resizing (third argument) you can use these keywords - fit, fill, exact, stretch, shrink_only. For details see comments above these constants

More

• Read more about images providers
• Read more about images generation