4.0.0 2017-05-18 16:01 UTC


Build Status Donate

Simple to use tool for managing uploaded images.

BC break!

Be careful, version 3.0 was completely rewritten.

If you are using just latte templates and uploading images, it should be enough just to move basePath and baseUrl configuration under the storage section.


$ composer require carrooi/images-manager
$ composer update


	images: Carrooi\ImagesManager\DI\ImagesManagerExtension
    	basePath: %appDir%/../www/uploads


On your website you can have many different types of images. For example users' images, articles' images and so on. But you also want to keep them separate and this is where namespaces came from.

Namespace is actually just a directory in chosen path (in our example %appDir%/../www/uploads)

This means that users' images will be saved here: %appDir%/../www/uploads/user.

Only thing you need to do is create this directory.

Saving images

There is automatically registered "manager" service for handling all images operations, so lets include it and than use it (presenter will be enough for this example)

use Nette\Application\UI\Presenter;
use Nette\Application\UI\Form;

class ImagesPresenter extends Presenter

	/** @var \Carrooi\ImagesManager\ImagesManager @inject */
	public $imagesManager;
	 * @return \Nette\Application\UI\Form
	protected function createComponentForm()
		$form = new Form;
		$form->addUpload('image', 'Image')
		$form->addSubmit('save', 'Upload');
		$form->onSuccess[] = [$this, 'uploadImage'];
		return $form;
	 * @param \Nette\Application\UI\Form $form
	 * @param mixed $values
	public function uploadImage(Form $form, $values)
		if ($values->image->isOk()) {
			$image = $values->image->toImage();
			$namespace = 'users';
			$name = 'david.jpg';
			$this->imagesManager->upload($image, $namespace, $name);
			// @todo: show flash message and redirect
		} else {
			// @todo: show error


As you can see, isn't really simple, just call upload with desired image, namespace and final name. That's it :-)

But be careful, if there is already image with name david.jpg in users namespace, it will be removed with all its thumbnails as well.

Latte templates

This step also couldn't be easier, because there are some Latte macros prepared for you.

The nice thing about this package is that you don't need to worry about browsers cache. Increasing version number is automatically appended to all URLs, so browser will always try to load new images when you change it.

original image:

<img n:src="users, 'david.jpg'">

thumbnail with width:

<img n:src="users, 'david.jpg', 150">

thumbnail with width and height:

<img n:src="users, 'david.jpg', '150x150'">

thumbnail with different resize method (default is fit):

<img n:src="users, 'david.jpg', 150, 'shrinkOnly|stretch'">

You can even use names without files' extensions and images-manager will try to find it for you:

<img n:src="users, david, 100">

Found files' extensions are cached, so if you change some image in other way than with ImagesManager, you'll have to delete the cache yourself.

Other Latte macros


<strong>Image path:</strong> <i>{image users, 'david.jpg', '50x50'}</i>

is-image (with alias isImage):

<img n:is-image="users, 'david.jpg'" n:src="users, 'david.jpg', 50">

is-not-image (with alias isNotImage):

<div n:is-not-image="users, 'david.jpg'" class="alert alert-danger">
	Upload your image now!

Default images

Maybe you will want some default image. Users are again great example, because it is quite usual to have some default avatar. Default name of default image is default.jpg and it needs to be in desired namespace directory.

	default: default.png

Dummy images

When even default image does not exists, you can show some dummy image (like cute cats). This is possible because of lorempixel service.

	enabled: true
    category: cats
    fallbackSize: [800, 600]
    chance: 100
  • fallbackSize: image resolution used when no size is given in latte template
  • chance: percentage chance that instead of no image, you'll see cute cat

Entities, DTOs and so on instead of string names

With default setup, you have to use string names like david.jpg. But for users it would be better to use eg. their entities directly. You just have to configure custom namespace setup with own name resolver.

use Carrooi\ImagesManager\INameResolver;
use App\Model\Entities\User;

class UserEntityNameResolver implements INameResolver

	 * @param \App\Model\Entities\User $user
	 * @return string
	public function translateName($user)
		if (!$user instanceof User) {
			throw new \Exception;		// todo: better exception
		return $user->getId();		// just like with string names

	 * @param \App\Model\Entities\User $user
	 * @return string
	public function getDefaultName($user)
		if (!$user instanceof User) {
			throw new \Exception;		// todo: better exception
		return $user->getGender()->getName();



			nameResolver: App\Images\UserEntityNameResolver

Quality of images

Quality of jpg and png images can be customized. This can be done either globally for all image namespaces or for each image namespace separately.

	quality: 90
        	quality: 100


If you are using specific sizes of images many time, it will be a good idea to create preset from such size. You can save all your images' sizes into configuration under some names and than use these names.

This is really good when you'll need to change some size in a future, you'll have to change it only in configuration.


				small: 10x20(shrinkOnly, stretch)
				medium: 40x50(fit)
				large: 400x500


<img n:src="users, 'david.jpg', small">

which is same as:

<img n:src="users, 'david.jpg', 10x20, 'shrinkOnly|stretch'">