Image conversion on the fly using PHP

About

CImage is a PHP class enabling resizing of images through scaling, cropping and filtering effects -- using PHP GD. The script img.php uses CImage to enable server-side image processing utilizing caching and optimization of the processed images.

Server-side image processing is a most useful tool for any web developer, img.php has an easy to use interface and its powerful when you integrate it with your website. Using it might decrease the time and effort for managing images and it might improve your workflow for creating content for websites.

This software is free and open source, licensed according MIT.

Documentation

Read full documentation at: <strike>http://dbwebb.se/opensource/cimage</strike>

New website is being setup at cimage.se, to improve documentation (work is ongoing).

Requirements

CImage and img.php supports GIF (with transparency), JPEG and PNG (8bit transparent, 24bit semi transparent) images. It requires PHP 5.3 and PHP GD. You optionally need the EXIF extension to support auto-rotation of JPEG-images.

Version v0.7.x will be the last version to support PHP 5.3. Coming version will require newer version of PHP.

Installation

There are several ways of installing. You either install the whole project which uses the autoloader to include the various files, or you install the all-included bundle that -- for convenience -- contains all code in one script.

Install source from GitHub

The sourcode is available on GitHub. Clone, fork or download as zip.

Latest stable version is v0.7.18 released 2016-08-09.

I prefer cloning like this. Do switch to the latest stable version.

git clone git://github.com/mosbth/cimage.git
cd cimage
git checkout v0.7.18

Make the cache-directory writable by the webserver.

chmod 777 cache

Install all-included bundle

There are some all-included bundles of img.php that can be downloaded and used without dependency to the rest of the sourcecode.

| Scriptname | Description | |------------|-------------| | imgd.php | Development mode with verbose error reporting and option &verbose enabled. | | imgp.php | Production mode logs all errors to file, giving server error 500 for bad usage, option &verbose disabled. | | imgs.php | Strict mode logs few errors to file, giving server error 500 for bad usage, option &verbose disabled. |

Dowload the version of your choice like this.

wget https://raw.githubusercontent.com/mosbth/cimage/v0.7.18/webroot/imgp.php

Open up the file in your editor and edit the array $config. Ensure that the paths to the image directory and the cache directory matches your environment, or create an own config-file for the script.

Install from Packagist

You can install the package mos/cimage from Packagist using composer.

Use cases

Lets take some use cases to let you know when and how img.php might be useful.

Make a thumbnail

Lets say you have a larger image and you want to make a smaller thumbnail of it with a size of 80x80 pixels. You simply take the image and add constraints on width, height and you use the resize strategy crop-to-fit to crops out the parts of the image that does not fit.

To produce such a thumbnail, create a link like this:

img.php?src=kodim04.png&width=80&height=80&crop-to-fit

Slightly complexer use case

Perhaps you got an image from a friend. The image was taken with the iPhone and thus rotated.

The original image is looking like this one, scaled down to a width of 250 pixels.

So, you need to rotate it and crop off some parts to make it intresting.

To show it off, I'll auto-rotate the image based on its EXIF-information, I will crop it to a thumbnail of 100x100 pixels and add a filter to make it greyscale finishing up with a sharpen effect. Just for the show I'll rotate the image 25 degrees - do not ask me why.

Lets call this the URL-Photoshopper. This is how the magic looks like.

img.php?src=issue36/me-270.jpg&w=100&h=100&cf&aro &rb=-25&a=8,30,30,38&f=grayscale&convolve=sharpen-alt

For myself, I use img.php to put up all images on my website, it gives me the power of affecting the resulting images - without opening up a photo-editing application.

Get going quickly

Check out the test page

Try it out by pointing your browser to the test file webroot/test/test.php. It will show some example images and you can review how they are created.

Process your first image

Try it yourself by opening up an image in your browser. Start with

webroot/img.php?src=kodim04.png

and try to resize it to a thumbnail by adding the options

&width=100&height=100&crop-to-fit

What does "processing the image" involves?

Add &verbose to the link to get a verbose output of what is happens during image processing. This is useful for developers and those who seek a deeper understanding on how it works behind the scene.

Check your system

Open up webroot/check_system.php if you are uncertain that your system has the right extensions loaded.

How does it work?

Review the settings in webroot/img_config.php and check out webroot/img.php on how it uses CImage.

The programatic flow, just to get you oriented in the environment, is.

Start in img.php.
img.php reads configuration details from img_config.php (if the config-file is available).
img.php reads and processes incoming $_GET arguments to prepare using CImage.
img.php uses CImage.
CImage processes, caches and outputs the image according to how its used.

Read on to learn more on how to use img.php.

Basic usage

Select the source

Open an image through img.php by using its src attribute.

img.php?src=kodim13.png

It looks like this.

All images are stored in a directory structure and you access them as:

?src=dir1/dir2/image.png

Resize using constraints on width and height

Create a thumbnail of the image by applying constraints on width and height, or one of them.

| &width=150 | &height=150 | &w=150&h=150 | |---------------------|---------------------|---------------------| | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=150 alt=''> | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&h=150 alt=''> | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=150&h=150 alt=''> |

By setting width, height or both, the image gets resized to be not larger than the defined dimensions and keeping its original aspect ratio.

Think of the constraints as a imaginary box where the image should fit. With width=150 and height=150 the box would have the dimension of 150x150px. A landscape image would fit in that box and its width would be 150px and its height depending on the aspect ratio, but for sure less than 150px. A portrait image would fit with a height of 150px and the width depending on the aspect ratio, but surely less than 150px.

Resize to fit a certain dimension

Creating a thumbnail with a certain dimension of width and height, usually involves stretching or cropping the image to fit in the selected dimensions. Here is how you create a image that has the exact dimensions of 300x150 pixels, by either stretching, cropping or fill to fit.

| What | The image | |---------------------|---------------------| | Original. The original image resized with a max width and max height.<br>?w=300&h=150 | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=300&h=150 alt=''> | | Stretch. Stretch the image so that the resulting image has the defined width and height.<br>?w=300&h=150&stretch | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=300&h=150&stretch alt=''> | | Crop to fit. Keep the aspect ratio and crop out the parts of the image that does not fit.<br>?w=300&h=150&crop-to-fit | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=300&h=150&crop-to-fit alt=''> | | Fill to fit. Keep the aspect ratio and fill then blank space with a background color.<br>?w=300&h=150&fill-to-fit=006600 | <img src=https://cimage.se/cimage/imgd.php?src=example/kodim13.png&w=300&h=150&fill-to-fit=006600 alt=''> |

Learn to crop your images, creative cropping can make wonde

Cimage

Install / Use

README