{"id":14965662,"url":"https://github.com/harmim/images","last_synced_at":"2025-10-25T12:30:28.515Z","repository":{"id":62514867,"uuid":"53213573","full_name":"harmim/images","owner":"harmim","description":"A tool for working with images.","archived":false,"fork":false,"pushed_at":"2023-07-05T17:13:11.000Z","size":85,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-31T07:11:10.366Z","etag":null,"topics":["extension","gd","images","nette-framework","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harmim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-05T17:25:39.000Z","updated_at":"2023-06-30T23:00:18.000Z","dependencies_parsed_at":"2024-09-14T00:07:54.476Z","dependency_job_id":"9537d381-93c9-4aa1-8bb5-6830cb1fe107","html_url":"https://github.com/harmim/images","commit_stats":{"total_commits":29,"total_committers":2,"mean_commits":14.5,"dds":0.03448275862068961,"last_synced_commit":"eeb234fd228eaef8ba3d8dbca212462c7dbaa69d"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmim%2Fimages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmim%2Fimages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmim%2Fimages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmim%2Fimages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harmim","download_url":"https://codeload.github.com/harmim/images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238137847,"owners_count":19422710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extension","gd","images","nette-framework","php"],"created_at":"2024-09-24T13:35:03.654Z","updated_at":"2025-10-25T12:30:28.203Z","avatar_url":"https://github.com/harmim.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A tool for working with images\n\n[![Build](\nhttps://github.com/harmim/images/actions/workflows/build.yml/badge.svg)](\nhttps://github.com/harmim/images/actions/workflows/build.yml)\n[![Coding Style](\nhttps://github.com/harmim/images/actions/workflows/coding-style.yml/badge.svg)](\nhttps://github.com/harmim/images/actions/workflows/coding-style.yml)\n[![Static Analysis](\nhttps://github.com/harmim/images/actions/workflows/static-analysis.yml/badge.svg)](\nhttps://github.com/harmim/images/actions/workflows/static-analysis.yml)\n[![Tests](\nhttps://github.com/harmim/images/actions/workflows/tests.yml/badge.svg)](\nhttps://github.com/harmim/images/actions/workflows/tests.yml)\n[![Coverage](\nhttps://coveralls.io/repos/github/harmim/images/badge.svg)](\nhttps://coveralls.io/github/harmim/images)\n[![Monthly Downloads](\nhttps://poser.pugx.org/harmim/images/d/monthly)](\nhttps://packagist.org/packages/harmim/images)\n[![Total Downloads](\nhttps://poser.pugx.org/harmim/images/downloads)](\nhttps://packagist.org/packages/harmim/images)\n[![Version](\nhttp://poser.pugx.org/harmim/images/version)](\nhttps://github.com/harmim/images/tags)\n[![PHP Version Require](\nhttp://poser.pugx.org/harmim/images/require/php)](\nhttps://packagist.org/packages/harmim/images)\n[![License](\nhttps://poser.pugx.org/harmim/images/license)](\nhttps://github.com/harmim/images/blob/master/LICENSE.md)\n\n\n## About\n\nA tool for working with images. It can be used as an extension of the\n[Nette Framework](https://nette.org).\n\nThere is `Image storage` for storing images easily and/or deleting them from\nthe storage. There are also several ways how to resize and/or process images.\nThen, you can get a stored image path directly, or you can use prepared\n[Latte](https://latte.nette.org) macros to generate HTML tags.\nSee [Usage](#Usage).\n\n**Requires the PHP version `8.2` or newer and PHP extensions `fileinfo`, `gd`,\nand `intl`.**\n\n\n## Installation\n\nDownload the [latest release](https://github.com/harmim/images/tags) or use\nComposer:\n```bash\ncomposer require harmim/images\n```\n\n\n## Usage\n\nFor working with images, we need `\\Harmim\\Images\\ImageStorage`:\n\n### Without Nette\n\n```php\n$customConfig = [\n\t'wwwDir' =\u003e __DIR__ . DIRECTORY_SEPARATOR . 'www',\n\t'compression' =\u003e 90,\n\t'placeholder' =\u003e 'images/foo.png',\n\t'types' =\u003e [\n\t\t'img-small' =\u003e [\n\t\t\t'width' =\u003e 50,\n\t\t\t'height' =\u003e 50,\n\t\t\t'transform' =\u003e \\Harmim\\Images\\Resize::Exact,\n\t\t\t...\n\t\t],\n\t\t...\n\t],\n\t...\n];\n$imageStorage = $customConfig + \\Harmim\\Images\\Config\\Config::Defaults;\n```\n\nIn `$customConfig`, you can specify a custom configuration.\nSee [Configuration](#Configuration).\n\n### With Nette\n\nYou can enable and customise the extension using your NEON config:\n```neon\nextensions:\n  images: \\Harmim\\Images\\DI\\ImagesExtension\n\nimages:\n  compression: 90\n  placeholder: images/foo.png\n  types:\n    img-small:\n      width: 50\n      height: 50\n      transform: ::constant(\\Harmim\\Images\\Resize::Exact)\n      ...\n    ...\n  ...\n```\n\nIn the `images` section, you can specify a custom configuration.\nSee [Configuration](#Configuration).\n\n`\\Harmim\\Images\\ImageStorage` is now registrated in the DI container. You can\nget it directly from the container:\n```php\n/** @var \\Nette\\DI\\Container $container */\n$imageStorage = $container-\u003egetService('images.imageStorage');\n// or\n$imageStorage = $container-\u003egetByType(\\Harmim\\Images\\ImageStorage::class);\n```\n\nOf course, you can inject `\\Harmim\\Images\\ImageStorage` through a constructor,\ninject method, inject annotation, or any other way.\n\nIf you want to use `\\Harmim\\Images\\ImageStorage` in a presenter or control\nwhere inject methods are called, you can use trait\n`\\Harmim\\Images\\TImageStorage`. In your presenters, controls, and theire\ntemplates, there will be variable `$imageStorage`.\n```php\nabstract class BasePresenter extends \\Nette\\Application\\UI\\Presenter\n{\n\tuse \\Harmim\\Images\\TImageStorage;\n}\n\nabstract class BaseControl extends \\Nette\\Application\\UI\\Control\n{\n\tuse \\Harmim\\Images\\TImageStorage;\n}\n```\n\nThe extension installs images macros to Latte. See [Macros](#Macros).\n\n### Storing Images\n\nYou can store an image using method\n`\\Harmim\\Images\\ImageStorage::saveImage(string $name, string $path): string` or\n`\\Harmim\\Images\\ImageStorage::saveUpload(\\Nette\\Http\\FileUpload $file): string`.\nAn original image will be stored; then, it will be compresed.\n\nBoth methods return a stored image file name. You can use this file name to\ndelete, resize, or retrieve the image.\n\nImages are stored with a unique file name and location.\n\n### Deleting Images\n\nUsing method\n`\\Harmim\\Images\\ImageStorage::deleteImage(string $fileName, array $excludedTypes = []): void`,\nyou can delete an image by `$fileName` which should be a file name returned by\n`\\Harmim\\Images\\ImageStorage::saveImage` or\n`\\Harmim\\Images\\ImageStorage::saveUpload`.\n\nIf you pass `$excludedTypes`, only other types will be deleted; otherwise, all\ntypes, the original image, and the compressed image will be deleted.\n\n### Getting Stored Images' Paths\n\nYou can get a stored image path using method\n`\\Harmim\\Images\\ImageStorage::getImageLink(string $fileName, ?string $type = null, array $options = []): ?string`\nor [Macros](#Macros). You can pass a specific type defined in an inital\nconfiguration, or you can pass specific options. See\n[Configuration](#Configuration). `$fileName` should be a file name returned by\n`\\Harmim\\Images\\ImageStorage::saveImage` or\n`\\Harmim\\Images\\ImageStorage::saveUpload`.\n\nIf you try to get an image of a size or a type for a first time, this image is\nnot yet created, so it will be created now. Next time, you will get a resized\nimage.\n\nIf the image does not exist, a placeholder will be returned.\n\nIn case you need to get an original/compressed image, in the configuration,\nyou can use `orig/compressed`, respectively. For example, `['orig' =\u003e true]`.\nIt is also possible to use these options in macros.\n\n### Macros\n\n#### `img`\n\n```latte\n{img [$image] [image-type] [options]}\n```\nRenders the `img` tag:\n```html\n\u003cimg src=\"foo.jpg\" width=\"100\" height=\"100\" alt=\"foo\"\u003e\n```\nor tags for lazy loading with the `lazy` option:\n```html\n\u003cimg class=\"lazy\" data-src=\"foo.jpg\" width=\"100\" height=\"100\" alt=\"foo\"\u003e\n\u003cnoscript\u003e\u003cimg src=\"foo.jpg\" width=\"100\" height=\"100\" alt=\"foo\"\u003e\u003c/noscript\u003e\n```\n\nExamples:\n```latte\n{img alt =\u003e 'foo'} {* returns a path to a placeholder *}\n\n{* '$image' is a file name *}\n{img $image alt =\u003e 'foo'}\n{img $image width =\u003e 200, height =\u003e 200, alt =\u003e 'foo'}\n\n{* 'img-small' is an image type defined in the configuration *}\n{img $image img-small alt =\u003e 'foo'}\n{img $image img-small compression =\u003e 90, alt =\u003e 'foo', class =\u003e 'bar'}\n\n{img $image img-small lazy =\u003e true, alt =\u003e 'foo'}\n{img $image img-small lazy =\u003e true, width =\u003e 500, height =\u003e 650, alt =\u003e 'foo'}\n```\n\n#### `n:img`\n\n```latte\n\u003cimg n:img=\"[$image] [image-type] [options]\" alt=\"foo\"\u003e\n```\nRenders the `src` attribute. It can be used, e.g., in the `img` element.\n\nExamples:\n```latte\n\u003cimg n:img alt=\"foo\"\u003e {* renders a path to a placeholder *}\n\n{* '$image' is a file name *}\n\u003cimg n:img=\"$image\" alt=\"foo\"\u003e\n\u003cimg n:img=\"$image width =\u003e 200, height =\u003e 200\" width=\"200\" height=\"200\"\n     alt=\"foo\"\u003e\n\n{* 'img-small' is an image type defined in the configuration *}\n\u003cimg n:img=\"$image img-small\" alt=\"foo\"\u003e\n\u003cimg n:img=\"$image img-small compression =\u003e 90\" alt=\"foo\" class=\"bar\"\u003e\n```\n\n#### `imgLink`\n\n```latte\n{imgLink [$image] [image-type] [options]}\n```\nReturns a relative path (from the resource root directory) to a given image.\n\nExamples:\n```latte\n{imgLink} {* returns a path to a placeholder *}\n\n{* '$image' is a file name *}\n{imgLink $image}\n{imgLink $image width =\u003e 200, height =\u003e 200}\n\n{* 'img-small' is an image type defined in the configuration *}\n{imgLink $image img-small}\n{imgLink $image img-small compression =\u003e 90}\n\n\u003cdiv class=\"image-box\" data-src=\"{imgLink $image img-small}}\"\u003e\u003c/div\u003e\n```\n\n\n## Configuration\n\n- `wwwDir`: (`string`) An absolute path to the resource root directory.\n  * Default: `%wwwDir%` in Nette; otherwise, you have to specify this parameter.\n- `imagesDir`: (`string`) A relative path (from `wwwDir`) to a directory for\n  storing images.\n  * Default: `data/images`.\n- `origDir`: (`string`) A relative path (from `imagesDir`) to a directory for\n  storing original images.\n  * Default: `orig`.\n- `compressionDir`: (`string`) A relative path (from `imagesDir`) to a\n  directory for storing compressed images.\n  * Default: `imgs`.\n- `placeholder`: (`string`) A relative path (from `wwwDir`) to an image\n  placeholder (when an image is not found).\n  * Default: `img/noimg.jpg`.\n- `width`: (`int`) An image width.\n  * Default: `1024`.\n- `height`: (`int`) An image height.\n  * Default: `1024`.\n- `compression`: (`int`) A compression quality. See `\\Nette\\Utils\\Image::save`.\n  * Default: `85`.\n- `transform`: (`\\Harmim\\Images\\Resize|list\u003c\\Harmim\\Images\\Resize\u003e`) See\n  [Transform-Options](#Transform-Options).\n  * Default: `\\Harmim\\Images\\Resize::OrSmaller`.\n- `allowedImgTagAttrs`: (`list\u003cstring\u003e`) `img` attributes you can use in the\n  `{img}` Latte macro, other attributes are ignored.\n  * Default: `[alt, height, width, class, hidden, id, style, title, data]`.\n- `lazy`: (`bool`) Render the `{img}` Latte macro as a lazy image (with the\n  `data-src` attribute, `lazy` class, and normal `img` tag in the `noscript`\n  tag).\n  * Default: `false`.\n- `types`: (`array\u003cstring, mixed\u003e`) A configuration for image types overriding\n  the default configuration.\n  * Default: `[]`.\n  * Example:\n```neon\ntypes:\n  img-small:\n    width: 50\n    height: 50\n  img-gallery:\n    lazy: true\n    transform:\n    \t- ::constant(\\Harmim\\Images\\Resize::Stretch)\n    \t- ::constant(\\Harmim\\Images\\Resize::Cover)\n```\n- `destDir`: (`?string`) A directory where to find images.\n  * Default: `null`.\n- `orig`: (`?bool`) When set to `true`, the original image will be returned.\n  * Default: `null`.\n- `compressed`: (`?bool`) When set to `true`, the original compressed image\n  will be returned.\n  * Default: `null`.\n\n### Transform-Options\n\n| Option                              | Description                                                                   |\n|-------------------------------------|-------------------------------------------------------------------------------|\n| `\\Harmim\\Images\\Resize::ShrinkOnly` | Only shrinking (prevents a small image from being stretched).                 |\n| `\\Harmim\\Images\\Resize::Stretch`    | Do not keep the aspect ratio.                                                 |\n| `\\Harmim\\Images\\Resize::OrSmaller`  | The resulting dimensions will be smaller or equal to the required dimensions. |\n| `\\Harmim\\Images\\Resize::OrBigger`   | Fills (and possibly exceeds in one dimension) the target area.                |\n| `\\Harmim\\Images\\Resize::Cover`      | Fills the target area and cuts off what goes beyond.                          |\n| `\\Harmim\\Images\\Resize::Exact`      | Placees a not stretched image to the exact blank area.                        |\n\n\n## License\n\nThis tool is licensed under the\n[MIT license](https://github.com/harmim/images/blob/master/LICENSE.md).\n\n\n---\n\nAuthor: **Dominik Harmim \u003c[harmim6@gmail.com](mailto:harmim6@gmail.com)\u003e**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmim%2Fimages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharmim%2Fimages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmim%2Fimages/lists"}