Statistics
1585
7
2
95d
Badges
Dependencies

Images manager

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.

Installation

$ composer require carrooi/images-manager
$ composer update

config.neon:

extensions:
	images: Carrooi\ImagesManager\DI\ImagesManagerExtension
    
images:
	storage:
    	basePath: %appDir%/../www/uploads
        baseUrl: http://www.site.com/uploads

Namespaces

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')
			->addRule(Form::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

image:

<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!
</div>

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.

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

dummy:
	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();
	}

}

configuration:

images:
	namespaces:
		user:
			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.

images:
	quality: 90
    namespaces:
    	user:
        	quality: 100

Presets

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.

configuration:

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

template:

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

which is same as:

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

    • Allow dash in images names

    For the details you can have a look at the diff.

  • 2.1.3

    • Optimize exceptions
    • Throw an exception when uploading image with unknown name (eg. without file extension)
    • Remove old image before reuploading even with different extension #6

    For the details you can have a look at the diff.

  • 2.1.2

    • Fix isImage and isNotImage latte macros for missing images

    For the details you can have a look at the diff.

  • 2.1.1

    • Fix url macros when using with custom objects
    • Use CachedImagesStorage by default (replaces MemoryImagesStorage)

    For the details you can have a look at the diff.

  • 2.1.0

    • Optimized caching
    • Refactored loading of default images
    • Storing loaded random default image #3

    For the details you can have a look at the diff.

  • 2.0.3

    • Using only forward slashes at urls #4

    For the details you can have a look at the diff.

  • 2.0.2

    • Names of namespaces configured in DI can now contain any character

    For the details you can have a look at the diff.

  • 2.0.1

    • Fixed error with loading images without extension and they don't exists

    For the details you can have a look at the diff.

  • 2.0.0

    • Optimized tests
    • Optimized dependencies of all classes
    • Removed dependency on whole nette/nette and requiring only needed packages
    • Require nette >= 2.2 (bc break)
    • Latte macros src and image can return absolute urls
    • Returning dummy images for thumbnails if no default image is found (uses satyr.io)
    • Change base namespace from DK to Carrooi (bc break)
    • Package and repository moved under Carrooi organization
    • Packageist package renamed from sakren/nette-images-manager to carrooi/images-manager (bc break)

    For the details you can have a look at the diff.

  • 1.1.0

    • Optimizations
    • Upload method now uses quality from namespace configuration
    • Added name resolvers
    • Images can be loaded without their files' extensions
    • Added caching (now using just in searching for files' extensions)
    • Little bit better readme

    For the details you can have a look at the diff.

Is this addon outdated? Did you find an issue? Please report it.

Componette Componette admin@componette.com