Download the PHP package harmim/images without Composer

A tool for working with images

About

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.

Installation

Download the latest release or use Composer:

Usage

For working with images, we need \Harmim\Images\ImageStorage:

Without Nette

In $customConfig, you can specify a custom configuration. See Configuration.

With Nette

You can enable and customise the extension using your NEON config:

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:

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.

The extension installs images macros to Latte. See Macros.

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.

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.

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.

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

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.

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.

Macros

img

Renders the img tag:

or tags for lazy loading with the lazy option:

Examples:

n:img

Renders the src attribute. It can be used, e.g., in the img element.

Examples:

imgLink

Returns a relative path (from the resource root directory) to a given image.

Examples:

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:
• 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.

Author: Dominik Harmim [[email protected]](mailto:[email protected])