A tool for working with images.
About
A tool for working with images. It can be used as extension to Nette Framework.
There is an Image storage
for easy storing images and/or deleting them from a storage.
There are also several ways to resize and/or process images, then you can get a stored image path directly
or you can use prepared Latte macros to generate finaly HTML tags. See usage.
Requires PHP version 7.1 or newer and PHP extensions gd
and fileinfo
.
Installation
Download a latest package or use a Composer:
composer require harmim/images
Usage
For working with images, we need Harmim\Images\ImageStorage
:
Without Nette
use Harmim\Images\DI\ImagesExtension;
use Harmim\Images\ImageStorage;
$config = ImagesExtension::DEFAULTS;
$config['wwwDir'] = __DIR__ . '/www'; // path to resource root directory
$customConfig = [ // custom configuration
'compression' => 90,
'placeholder' => 'images/foo.png',
'types' => [
'img-small' => [
'width' => 50,
'height' => 50,
'transform' => ImageStorage::RESIZE_EXACT,
...
],
...
],
...
];
$imageStorage = new ImageStorage(array_merge_recursive($config, $customConfig));
In $customConfig
you can specify custom configuration. See configuration.
With Nette
You can enable and customize the extension using your neon config.
extensions:
images: Harmim\Images\DI\ImagesExtension
images: # custom configuration
compression: 90
placeholder: "images/foo.png"
types:
img-small:
width: 50
height: 50
transform: Harmim\Images\ImageStorage::RESIZE_EXACT
...
...
...
In images
section you can specify custom configuration. See configuration.
Harmim\Images\ImageStorage
is now registrated in DI container. You can get it directly from container:
use Harmim\Images\ImageStorage;
/** @var Nette\DI\Container $container */
$imageStorage = $container->getService('images.images');
// or
$imageStorage = $container->getByType(ImageStorage::class);
Of course you can inject Harmim\Images\ImageStorage
through constructor, inject method, inject annotation or
another way.
If you want to use Harmim\Images\ImageStorage
in presenter or control where are called inject methods, then you can
use trait Harmim\Images\TImageStorage
. In your presenters, controls and theire templates will be
variable $imageStorage
.
use Harmim\Images\TImageStorage
use Nette\Application\UI\Control;
use Nette\Application\UI\Presenter;
abstract class BasePresenter extends Presenter
{
use TImageStorage;
}
abstract class BaseControl extends Control
{
use TImageStorage;
}
Extension installs images macros to Latte. See macros.
Storing images
You can store image using method Harmim\Images\ImageStorage::saveImage(string $name, string $path): string
or
using Harmim\Images\ImageStorage::saveUpload(Nette\Http\FileUpload $file): string
.
Original image will be stored, then original image will be compresed and also stored.
Both methods returns stored image file name. You can use this file name to deleting or resizing and getting image.
Images are stored with unique file name and location.
Deleting images
Using method Harmim\Images\ImageStorage::deleteImage($fileName, array $excludedTypes = []): void
,
you can delete image by $fileName
which should be file name returned by Harmim\Images\ImageStorage::saveImage
or Harmim\Images\ImageStorage::saveUpload
, or object implementing Harmim\Images\IImage
.
If you pass $excludedTypes
, only other types will be deleted, otherwise all types, original image and compressed
image will be deleted.
Getting stored images path
You can get stored image path using method
Harmim\Images\ImageStorage::getImageLink($fileName, ?string $type = null, array $options = []): ?string
or using macros. You can pass specific type defined in inital options or pass specific options.
See configuration. $fileName
should be file name returned by Harmim\Images\ImageStorage::saveImage
or Harmim\Images\ImageStorage::saveUpload
, or object implementing Harmim\Images\IImage
.
If you are trying to get image of any size or any type for first time, this image wont be created yet, so it will be created. Next time you'll get resized image.
If the image does not exist, placeholder will be returned.
Macros
img
{img [$image] [image-type] [options]}
Renders img tag:
<img src="foo.jpg" width="100" height="100">
or tags for lazy load with lazy option:
<img class="lazy" data-src="foo.jpg" width="100" height="100">
<noscript><img src="foo.jpg" width="100" height="100"></noscript>
Examples:
{img} {* returns path to placeholder *}
{* $image is file name or object implementing Harmim\Images\IImage *}
{img $image}
{img $image width => 200, height => 200}
{* img-small is image type defined in configuration *}
{img $image img-small}
{img $image img-small compression => 90}
{img $image img-small lazy => TRUE}
{img $image img-small lazy => TRUE, width => 500, height => 650}
n:img
n:img="[$image] [image-type] [options]"
Renders src tag. It can be used in img element.
Examples:
<img n:img=""> {* renders path to placeholder *}
{* $image is file name or object implementing Harmim\Images\IImage *}
<img n:img="$image">
<img n:img="$image width => 200, height => 200">
{* img-small is image type defined in configuration *}
<img n:img="$image img-small">
<img n:img="$image img-small compression => 90">
imgLink
{imgLink [$image] [image-type] [options]}
Returns relative path (from resource root directory) to given image.
Examples:
{imgLink} {* returns path to placeholder *}
{* $image is file name or object implementing Harmim\Images\IImage *}
{imgLink $image}
{imgLink $image width => 200, height => 200}
{* img-small is image type defined in configuration *}
{imgLink $image img-small}
{imgLink $image img-small compression => 90}
Configuration
-
wwwDir: (string) absolute path to resource root directory
- default:
%wwwDir%
in Nette, otherwise you have to specify this parameter
- default:
-
imagesDir: (string) relative path (from
wwwDir
) to directory for storing images- default:
data/images
- default:
-
origDir: (string) relative path (from
imagesDir
) to directory for storing original images- default:
orig
- default:
-
compressionDir: (string) relative path (from
imagesDir
) to directory for storing compressed images- default:
imgs
- default:
-
placeholder: (string) relative path (from
wwwDir
) to image placeholder when image not found- default:
img/noimg.jpg
- default:
-
width: (int) image width
- default:
1024
- default:
-
height: (int) image height
- default:
1024
- default:
-
transform: (string) one of Harmim\Images\ImageStorage
RESIZE_...
constants or more constants separated by|
:Option Description RESIZE_SHRINK_ONLY only shrinking (prevents the small image from being stretched) RESIZE_STRETCH do not keep the aspect ratio RESIZE_FIT the resulting dimensions will be smaller or equal to the required dimensions RESIZE_FILL fills (and possibly exceeds in one dimension) the target area RESIZE_EXACT fills the target area and cuts off what goes beyond RESIZE_FILL_EXACT place not stretched image to exact blank area - default:
RESIZE_FIT
- default:
-
imgTagAttributes: (array) HTML img tags which you can use in
{img}
Latte macro, other tags are ignored- default:
[alt, height, width, class, hidden, id, style, title, data]
- default:
-
types: (array) configuration for image types which overrides default configuration
- default:
[]
- example:
types: img-small: width: 50 height: 50 img-gallery: lazy: true transform: Harmim\Images\ImageStorage::RESIZE_STRETCH
- default:
-
lazy: (bool) render
{img}
Latte macro as lazy img (with data-src, lazy class and normal img tag in noscript tag)- default:
false
- default:
License
This tool is licensed under the MIT license.