harmim/images

A tool for working with images.

A tool for working with images

, _(*1)

About

A tool for working with images. It can be used as an extension of the Nette Framework., _(*2)

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., _(*3)

Requires the PHP version 8.2 or newer and PHP extensions fileinfo, gd, and intl., _(*4)

Installation

Download the latest release or use Composer:, _(*5)

composer require harmim/images

Usage

For working with images, we need \Harmim\Images\ImageStorage:, _(*6)

Without Nette

$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., _(*7)

With Nette

You can enable and customise the extension using your NEON config:, _(*8)

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., _(*9)

\Harmim\Images\ImageStorage is now registrated in the DI container. You can get it directly from the container:, _(*10)

/** @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., _(*11)

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., _(*12)

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., _(*13)

Storing Images

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., _(*14)

Both methods return a stored image file name. You can use this file name to delete, resize, or retrieve the image., _(*15)

Images are stored with a unique file name and location., _(*16)

Deleting Images

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., _(*17)

If you pass $excludedTypes, only other types will be deleted; otherwise, all types, the original image, and the compressed image will be deleted., _(*18)

Getting Stored Images' Paths

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., _(*19)

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., _(*20)

If the image does not exist, a placeholder will be returned., _(*21)

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., _(*22)

Macros

img

{img [$image] [image-type] [options]}

Renders the img tag:, _(*23)

<img src="foo.jpg" width="100" height="100" alt="foo">

or tags for lazy loading with the lazy option:, _(*24)

<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:, _(*25)

{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., _(*26)

Examples:, _(*27)

<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., _(*28)

Examples:, _(*29)

{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}

Configuration

• wwwDir: (string) An absolute path to the resource root directory.
  • Default: %wwwDir% in Nette; otherwise, you have to specify this parameter.
• imagesDir: (string) A relative path (from wwwDir) to a directory for storing images.
  • Default: data/images.
• origDir: (string) A relative path (from imagesDir) to a directory for storing original images.
  • Default: orig.
• compressionDir: (string) A relative path (from imagesDir) to a directory for storing compressed images.
  • Default: imgs.
• placeholder: (string) A relative path (from wwwDir) to an image placeholder (when an image is not found).
  • Default: img/noimg.jpg.
• width: (int) An image width.
  • Default: 1024.
• height: (int) An image height.
  • Default: 1024.
• compression: (int) A compression quality. See \Nette\Utils\Image::save.
  • Default: 85.
• transform: (\Harmim\Images\Resize|list<\Harmim\Images\Resize>) See Transform-Options.
  • Default: \Harmim\Images\Resize::OrSmaller.
• allowedImgTagAttrs: (list<string>) img attributes you can use in the {img} Latte macro, other attributes are ignored.
  • Default: [alt, height, width, class, hidden, id, style, title, data].
• lazy: (bool) Render the {img} Latte macro as a lazy image (with the data-src attribute, lazy class, and normal img tag in the noscript tag).
  • Default: false.
• types: (array<string, mixed>) A configuration for image types overriding the default configuration.
  • Default: [].
  • Example:

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.
  • Default: null.
• orig: (?bool) When set to true, the original image will be returned.
  • Default: null.
• compressed: (?bool) When set to true, the original compressed image will be returned.
  • Default: null.

Transform-Options

License

This tool is licensed under the MIT license., _(*30)

Author: Dominik Harmim harmim6@gmail.com" title="See online harmim6@gmail.com">harmim6@gmail.com, _(*31)