Obscura

Download the code from GitHub : Current version 1.0.2

Obscura, the PHP thumbnail library

When it comes to working with images in today’s web applications, there is surely no more common a task than ‘thumbnailing’ – the practice of creating reduced-size versions of images to make them more appropriate for display. This can be achieved through the use of high-end desktop solutions like Adobe’s Photoshop or the GIMP, but in high volume scenarios where speed is essential this manual approach fails to scale. It is simply impractical for administrators to resize images as and when they are uploaded by the users of their apps.

Thankfully there are many ways that thumbnailing can be automated, usually involving the leveraging of command-line utilities such as ImageMagick or GD. The PHP language has bindings for these tools, allowing developers to create and manipulate images through code alone. Its GD bindings in particular are very straightforward; complex transformations can be achieved in a few lines of code:

<?php
header("Content-type: image/png");
$string = $_GET['text'];
$im     = imagecreatefrompng("images/button1.png");
$orange = imagecolorallocate($im, 220, 210, 60);
$px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
imagestring($im, 3, $px, 9, $string, $orange);
imagepng($im);imagedestroy($im);

(example of dynamically layering text onto a PNG image, courtesy of php.net)

The downside though, is that the developer needs to know in advance what type of image they’re working with, which often leads to a lot of boilerplate code.

I like using the GD library with PHP mostly because it’s simple to install and configure, and has a small memory footprint; I’ve found ImageMagick to be not quite as slick, and far more complicated. What ImageMagick has in its favour, though, is an object-oriented API that makes working with it in today’s modern unit-tested web apps very advantageous. The GD API lacks this capability, so developers wishing to type-hint their code to regulate its use, or mock their code to aid unit testing, need to first wrap the API in an object oriented interface. These were our requirements, so we looked to see if there were any freely available libraries that provided just that. What we found, however, tended to be either unmaintained or released under oppressive licenses that were incompatible with our software – so we decided to produce our own.

Obscura is an object oriented wrapper for PHP’s GD image library. At its core is a set of classes that decorate the common GD functions, providing a layer of abstraction that makes it trivial to work with different image types like JPEGs or PNGs. Additional classes allow a developer to configure and create thumbnails through an elegant fluid interface. Let’s take a look at some of the features Obscura provides.

Image type abstraction

Obscura employs the decorator pattern so images can be treated the same regardless of the image type. Whether the image is a JPEG, GIF or PNG the library decorates it with an instance of an ImageDecorator, allowing developers to work with a consistent API. Support for additional image types is planned for the future. Decorators allow the developer quick access to image properties such as

• Width
• Height
• Image type
• MIME type
• Orientation (Landscape, Portrait, Square)

Which are all useful when deciding how to display it. The important thing to note is that we don’t have to concern ourselves with checking the image type before loading it into PHP anymore – the library does all that for us.

Resizing images

The main aim of the library is to assist with image resizing though, and this is achieved through the use of a ThumbnailFactory; the factory uses a configuration object to decide how to resize the image. The configuration object features a fluid interface to make using it a breeze. Obscura supports some of the most common requirements when creating thumbnails:

• Resize by width and / or height
• Aspect ratio locking so the thumbnail is proportional to the original image
• ‘Constrain to size’ functionality so thumbnails never exceed a certain size

Here’s a quick example, in which we resize an image so it is 100 pixels wide. We lock the aspect ratio so that the height of the new image is proportional to the new width, ensuring the thumbnail is not distorted:

<?php
 
use BoxUKObscuraThumbnailFactory;
use BoxUKObscuraThumbnailFactoryConfig;
use BoxUKObscuraImageDecoratorFactory;
 
// Create a thumbnail factory
$factory = new ThumbnailFactory( new Factory() );
$factory->setOutputDirectory(__DIR__);
$config = new Config();
 
// Resize foo.jpg to 100 pixel width, maintaining aspect ratio. Save as bar.jpg.
$config->setInputFilename('foo.jpg')
    ->setWidth(100)
    ->setAspectRatioLock(true)
    ->setOutputFilename('bar.jpg');
 
$factory->createThumbnail($config);

Lots more examples of resizing can be found on Obscura’s github page.

Mounting an image onto a background

Another commonly used feature is the ability to mount an image or thumbnail on a background to provide either a consistent aspect ratio or size for the resulting image, or possibly as a decoration.

Obscura’s config parameter allows the specification of mounting frames, their sizes and color. It supports the setting of:

• Width
• Height
• Color
• Transparency

This example config will take the foo.jpg image and provide a version of it centered within a white mount of 600 x 400 pixels.

$config->setInputFilename('foo.jpg')
    ->setMountEnabled(true)
    ->setMountWidth(600)
    ->setMountHeight(400)
    ->setMountColor('#FFFFFF');

The mount color parameter can also take an RGBA value, allowing the creation of semi- or fully- transparent mounts.

<?php
 
$config->setInputFilename('foo.jpg')
    ->setMountEnabled(true)
    ->setMountWidth(400)
    ->setMountHeight(400)
    ->setMountColor(rgba(0,0,0,255);

This example config will take the foo.jpg and provide a 400px square thumbnail with foo.jpg aspect ratio constrained within it.

Conclusion

We hope that Obscura fills a need for developers looking for a permissively licensed PHP-based thumbnailer. We have more features planned for the library over the coming months, which are listed in the project’s roadmap.

Grab the code from the github repository and take it for a spin!

At Box UK we have a strong team of bespoke software consultants with more than two decades of bespoke software development experience. If you’re interested in finding out more about how we can help you, contact us on +44 (0)20 7439 1900 or email info@boxuk.com.