A tool for working with images.
A tool for working with images. It can be used as an extension of the
Nette Framework.
There is Image storage
for storing images easily and/or deleting them from
the storage. There are also several ways how to resize and/or process images.
Then, you can get a stored image path directly, or you can use prepared
Latte macros to generate HTML tags.
See Usage.
Requires the PHP version 8.2
or newer and PHP extensions fileinfo
, gd
,
and intl
.
Download the latest release or use
Composer:
composer require harmim/images
For working with images, we need \Harmim\Images\ImageStorage
:
$customConfig = [
'wwwDir' => __DIR__ . DIRECTORY_SEPARATOR . 'www',
'compression' => 90,
'placeholder' => 'images/foo.png',
'types' => [
'img-small' => [
'width' => 50,
'height' => 50,
'transform' => \Harmim\Images\Resize::Exact,
...
],
...
],
...
];
$imageStorage = $customConfig + \Harmim\Images\Config\Config::Defaults;
In $customConfig
, you can specify a custom configuration.
See Configuration.
You can enable and customise the extension using your NEON config:
extensions:
images: \Harmim\Images\DI\ImagesExtension
images:
compression: 90
placeholder: images/foo.png
types:
img-small:
width: 50
height: 50
transform: ::constant(\Harmim\Images\Resize::Exact)
...
...
...
In the images
section, you can specify a custom configuration.
See Configuration.
\Harmim\Images\ImageStorage
is now registrated in the DI container. You can
get it directly from the container:
/** @var \Nette\DI\Container $container */
$imageStorage = $container->getService('images.imageStorage');
// or
$imageStorage = $container->getByType(\Harmim\Images\ImageStorage::class);
Of course, you can inject \Harmim\Images\ImageStorage
through a constructor,
inject method, inject annotation, or any other way.
If you want to use \Harmim\Images\ImageStorage
in a presenter or control
where inject methods are called, you can use trait\Harmim\Images\TImageStorage
. In your presenters, controls, and theire
templates, there will be variable $imageStorage
.
abstract class BasePresenter extends \Nette\Application\UI\Presenter
{
use \Harmim\Images\TImageStorage;
}
abstract class BaseControl extends \Nette\Application\UI\Control
{
use \Harmim\Images\TImageStorage;
}
The extension installs images macros to Latte. See Macros.
You can store an image using method\Harmim\Images\ImageStorage::saveImage(string $name, string $path): string
or\Harmim\Images\ImageStorage::saveUpload(\Nette\Http\FileUpload $file): string
.
An original image will be stored; then, it will be compresed.
Both methods return a stored image file name. You can use this file name to
delete, resize, or retrieve the image.
Images are stored with a unique file name and location.
Using method\Harmim\Images\ImageStorage::deleteImage(string $fileName, array $excludedTypes = []): void
,
you can delete an image by $fileName
which should be a file name returned by\Harmim\Images\ImageStorage::saveImage
or\Harmim\Images\ImageStorage::saveUpload
.
If you pass $excludedTypes
, only other types will be deleted; otherwise, all
types, the original image, and the compressed image will be deleted.
You can get a stored image path using method\Harmim\Images\ImageStorage::getImageLink(string $fileName, ?string $type = null, array $options = []): ?string
or Macros. You can pass a specific type defined in an inital
configuration, or you can pass specific options. See
Configuration. $fileName
should be a file name returned by\Harmim\Images\ImageStorage::saveImage
or\Harmim\Images\ImageStorage::saveUpload
.
If you try to get an image of a size or a type for a first time, this image is
not yet created, so it will be created now. Next time, you will get a resized
image.
If the image does not exist, a placeholder will be returned.
In case you need to get an original/compressed image, in the configuration,
you can use orig/compressed
, respectively. For example, ['orig' => true]
.
It is also possible to use these options in macros.
img
{img [$image] [image-type] [options]}
Renders the img
tag:
<img src="foo.jpg" width="100" height="100" alt="foo">
or tags for lazy loading with the lazy
option:
<img class="lazy" data-src="foo.jpg" width="100" height="100" alt="foo">
<noscript><img src="foo.jpg" width="100" height="100" alt="foo"></noscript>
Examples:
{img alt => 'foo'} {* returns a path to a placeholder *}
{* '$image' is a file name *}
{img $image alt => 'foo'}
{img $image width => 200, height => 200, alt => 'foo'}
{* 'img-small' is an image type defined in the configuration *}
{img $image img-small alt => 'foo'}
{img $image img-small compression => 90, alt => 'foo', class => 'bar'}
{img $image img-small lazy => true, alt => 'foo'}
{img $image img-small lazy => true, width => 500, height => 650, alt => 'foo'}
n:img
<img n:img="[$image] [image-type] [options]" alt="foo">
Renders the src
attribute. It can be used, e.g., in the img
element.
Examples:
<img n:img alt="foo"> {* renders a path to a placeholder *}
{* '$image' is a file name *}
<img n:img="$image" alt="foo">
<img n:img="$image width => 200, height => 200" width="200" height="200"
alt="foo">
{* 'img-small' is an image type defined in the configuration *}
<img n:img="$image img-small" alt="foo">
<img n:img="$image img-small compression => 90" alt="foo" class="bar">
imgLink
{imgLink [$image] [image-type] [options]}
Returns a relative path (from the resource root directory) to a given image.
Examples:
{imgLink} {* returns a path to a placeholder *}
{* '$image' is a file name *}
{imgLink $image}
{imgLink $image width => 200, height => 200}
{* 'img-small' is an image type defined in the configuration *}
{imgLink $image img-small}
{imgLink $image img-small compression => 90}
<div class="image-box" data-src="{imgLink $image img-small}}"></div>
wwwDir
: (string
) An absolute path to the resource root directory.%wwwDir%
in Nette; otherwise, you have to specify this parameter.imagesDir
: (string
) A relative path (from wwwDir
) to a directory fordata/images
.origDir
: (string
) A relative path (from imagesDir
) to a directory fororig
.compressionDir
: (string
) A relative path (from imagesDir
) to aimgs
.placeholder
: (string
) A relative path (from wwwDir
) to an imageimg/noimg.jpg
.width
: (int
) An image width.1024
.height
: (int
) An image height.1024
.compression
: (int
) A compression quality. See \Nette\Utils\Image::save
.85
.transform
: (\Harmim\Images\Resize|list<\Harmim\Images\Resize>
) See\Harmim\Images\Resize::OrSmaller
.allowedImgTagAttrs
: (list<string>
) img
attributes you can use in the{img}
Latte macro, other attributes are ignored.[alt, height, width, class, hidden, id, style, title, data]
.lazy
: (bool
) Render the {img}
Latte macro as a lazy image (with thedata-src
attribute, lazy
class, and normal img
tag in the noscript
false
.types
: (array<string, mixed>
) A configuration for image types overriding[]
.
types:
img-small:
width: 50
height: 50
img-gallery:
lazy: true
transform:
- ::constant(\Harmim\Images\Resize::Stretch)
- ::constant(\Harmim\Images\Resize::Cover)
destDir
: (?string
) A directory where to find images.null
.orig
: (?bool
) When set to true
, the original image will be returned.null
.compressed
: (?bool
) When set to true
, the original compressed imagenull
.Option | Description |
---|---|
\Harmim\Images\Resize::ShrinkOnly |
Only shrinking (prevents a small image from being stretched). |
\Harmim\Images\Resize::Stretch |
Do not keep the aspect ratio. |
\Harmim\Images\Resize::OrSmaller |
The resulting dimensions will be smaller or equal to the required dimensions. |
\Harmim\Images\Resize::OrBigger |
Fills (and possibly exceeds in one dimension) the target area. |
\Harmim\Images\Resize::Cover |
Fills the target area and cuts off what goes beyond. |
\Harmim\Images\Resize::Exact |
Placees a not stretched image to the exact blank area. |
This tool is licensed under the
MIT license.
Author: Dominik Harmim [harmim6@gmail.com](mailto:harmim6@gmail.com)