Image_nation – a new CodeIgniter image library for automatic cropping and/or resizing of images

Please allow me to introduce to you another one of my libraries. This one is good for manipulating images. Every site that has images for products/posts/pages use at least two different sizes (if not more…): one for a thumbnail and one for featured images (and maybe one for a slideshow, etc.).

This library will allow you to automatically create the different dimensions of the images right after you upload it. All you have to do is set the width and height of the images you want created and give the library the path to the image that you want processed.

So… let’s start explaining how you can install and use the library.

Step one – copy the files

Go to Github and download my repository (https://github.com/avenirer/CodeIgniter-Image-nation). Now copy the files from the package to the corresponding folder in your application folder:

• Copy config/image_nation.php into your application/config/
• Copy libraries/Image_nation.php into your application/libraries/
• This is not really necessary unless you need an example of using the library, but you can also copy controllers/Imagination.php inside your application/controllers directory.

Step two – do the configuration

Now, go to your configuration file (image_nation.php), which you could have pasted in application/config/ directory and edit the parameters:

$config[‘image_library’] will set the image library that will be used by the image_lib. The possible values are GD, GD2, ImageMagick, NetPBM – more on this you can find at: http://www.codeigniter.com/userguide3/libraries/image_lib.html.

$config[‘source_directory’] is used to tell the library where it can find the files that it will receive. I find this to be a really good idea. Usually, if you use a form to load the images, it is better to keep the original files inside a folder that cannot be viewed by the users. Also, if you find yourself needing to retrieve the original file you will always find it there,

$config[‘parent_directory’] is used to tell the library where will the files be saved. Usually, all sites keep all the images inside a single directory. if you put an empty string as value, the source directory will be used as parent directory. MAKE SURE THE PARENT DIRECTORY IS WRITABLE.

$config[‘size_folders’] for better management I thought it would be better to create “size folders” inside the parent directory (value set to TRUE). For example, if we are creating a 200px by 200px and a 600px by 200px images, we will have them inside the 200×200 and respectively 600×200 directories.

$config[‘default_sizes’] will allow you to set the default sizes that will automatically be processed. For example, if you set the value ‘200×200|400×350|500×200’, the library will create three formats of the same original image: 200px by 200px, 400px by 350px and 500px by 200px.

$config[‘keep_aspect_ratio’] – if we want the images to have the dimensions we’ve mentioned in default_sizes (images will be cropped and then resized), then we must set $config[‘keep_aspect_ratio’] to FALSE. If we only want to resize the images, then we set it to TRUE.

$config[‘default_master_dim’] – $config[‘default_master_dim’] will only work if we do resizing without cropping (that is, if $config[‘keep_aspect_ratio’] is set to TRUE).

$config[‘default_style’] = array(‘vertical’=>’center’,’horizontal’=>’center’); – in here we say what is our preference when the cropping is done. If we want the cropping to be done from the center of the image (where the action is actually happening inside a photo) will will pass an array: ‘vertical’=>’center’,’horizontal’=>’center‘. The possible values for ‘vertical’ key are: ‘top’, ‘middle’ (‘center’ is also accepted) and ‘bottom’. The possible values for ‘horizontal’ key are: ‘left’, ‘center’ and ‘right’.

$config[‘overwrite_images’] = FALSE; – if we are sure that there is no possibility that the overwriting of existing files would affect our application, we can set this one to TRUE, but I think is much better to leave it to FALSE.

$config[‘default_quality’] = ‘70%’; – we can set a default quality for the processed image. Usually should be set to 70%.

Step three – use your Image_nation

Now it’s time to put the library to work. So, in a controller we can use the following:

Load the library

To start using it, we first have to load it:

// first, let's load the library
$this->load->library('image_nation');

Add images

Now we can add images. To do this we will use the library’s source() method.

This method can receive up to two parameters:

1. First parameter is the image file name.

// with source() method you can add images. The library will look for the image inside de default source folder that is set in the configuration file
$this->image_nation->source('source-image-01.jpg');
$this->image_nation->source('source-image-02.jpg');
$this->image_nation->source('source-image-03.jpg');

If you think you repeat yourself, you can also insert a bulk of source images as an array:

// you can also add more than one image in one step by passing them in an array
$this->image_nation->source(array('source-image-01.jpg','source-image-02.jpg','source-image-03.jpg'));

The library will search for the images mentioned in the source() method inside the source directory that you mentioned in the configuration file.

2. The second parameter can be a boolean (TRUE or FALSE). This parameter, if set to FALSE (which is the default, so you are not obliged to pass it) will tell the library that the sources passed to it are relative to the source directory you mentioned in the configuration file.

If, for example, you have a source image which is not inside the source directory, but in another directory, you must pass TRUE as second parameter:

//you can add sources by mentioning full path, if you do this the second parameter must be set to TRUE
$this->image_nation->source(array(FCPATH.'anotherdirectory/source-image-01.jpg', FCPATH.'notsourcedirectory/source-image-02.jpg'),TRUE);

Reset all sizes

If you think you want to reset all the sizes mentioned in the configuration file or those that you added earlier (I will explain about adding another size after this), you can use the clear_sizes() method:

// you can reset the sizes. clear_sizes() method erases all sizes
$this->image_nation->clear_sizes();

Add or modify a size

If you want to add a new size, which is not inside the configuration file, or if you want to modify an already present size, you can use the add_size() method, by passing it an array with the sizes you want to add/modify:

// you can add or modify a size by using add_size() method and passing it an array
$dimensions = array(
  '200x200' => array(
    'master_dim' => 'width',
    'keep_aspect_ratio' => FALSE,
    'style' => array('vertical'=>'center','horizontal'=>'center'),
    'overwrite' => TRUE,
    'quality' => '100%',
    'directory' => 'test',
    'file_name' => 'test_me'
  )
);
$this->image_nation->add_size($dimensions);

Processing the images

Now, once we’ve set our sources and our goal images, we can start doing the processing of the images:

$this->image_nation->process();

You can also choose to process only a few of the sizes mentioned in the configuration file, but you will have to make sure that those sizes are in the configuration file:

//if you've set alot of available dimensions in the configuration file, you can also process only specific dimension(s). ** ATTENTION: IT ONLY WORKS IF THE DIMENSIONS MENTIONED ARE PRESENT IN THE DEFAULT DIMENSIONS **
$this->image_nation->process('400x350|500x200');

Another thing you can to with the process() method is to pass it the sizes you want to process, no matter what the configuration file has as default sizes. Remember the $dimensions array we’ve made earlier. We can pass the array to the process() method, and only that size will be created:

// you can also process only the sizes you want by passing the array with the size parameters
$this->image_nation->process($dimension);

Verify if everything went ok

If you want to verify what images were created and where, instead of $this->image_nation->process();  you could have done an $images = $this->image_nation->process(); . The process() method, after doing its job, will return an array with all the images that were created (image path, image name and eventual errors encountered). So, in a view, you can do a print_r() on your $images and will receive the array.

Also, if you only want to see if errors were encountered, you can use the get_errors() method. This method will return FALSE if no error was encountered or an array with the errors. We can use this method alongside another method: get_processed() – which will return an array with the processed images:

// get_errors() method is returning the eventual errors, or, if there were no errors, will return FALSE
if(!$this->image_nation->get_errors()) {
  echo 'Images were created';
  // get_processed() method returns the processed images' paths
  $processed_images = $this->image_nation->get_processed();
  // don't do this at home... use the views to output
  echo '<pre>';
  print_r($processed_images);
  echo '</pre>';
}

If you encounter any problems, please do let me know (either with a comment below or with a report issue on github).

Photo credits: Thank you very much, Jennalee Auclair, for your great, full of imagination, paint. It stopped my breath: The featured image of this post can be seen in full on Jennalee Auclair personal website http://cargocollective.com/Jennalee and also on Deviant Art: http://jennaleeauclair.deviantart.com/art/Depths-of-Imagination-353057632