Getting Started

Assuming you've already installed and configured the library the way you want, you're ready to start working with the library. This page covers the basics of instantiating PHP Thumb objects and working with plugins. We'll get into the actual thumbnailing goodness in the basic usage section.

##Include The Library

First thing we'll need to do to get up and running (obviously) is include the library. This has been simplified by only requiring you to include the thumb lib file in your code:

<?php

require_once 'path/to/ThumbLib.inc.php';

?>

That's it... piece 'o cake.

##Using Plugins

There's really not much to do as far as working with plugins goes. You simply need to drop them into the "thumb_plugins" folder. When you create new PHP Thumb objects, the plugins will automatically get included. The only thing you need to do is make sure they're compatible with whatever implementation of the library you're using (GD or iMagick). As far as the individual plugins' functionality goes, you'll need to refer to their docs for help.

##Working with PHP Thumb Objects

A lot of work has been put into making working with PHP Thumb objects as simple as possible. All objects are created by the PhpThumbFactory, and more often than not, you'll only need to pass the full path to the image you wish to manipulate to it. You can also pass an options array (discussed later) optionally if you wish to change certain behaviors. Another major upgrade to the library (if you've used prior versions) is that most errors are thrown as exceptions, making (hopefully) it easier to write error handling around the library in your own app.

So, let's take a look at how we can get a PHP Thumb object created:

<?php

require_once 'path/to/ThumbLib.inc.php';

$thumb = PhpThumbFactory::create('/path/to/image.jpg');

?>

This will run a few basic checks to make sure the file exists and is readable. If it isn't, an exception will be thrown. It will also make sure that you have the GD or iMagick extension loaded, and throw an exception if it isn't as well. So, let's make the above code a little more robust to handle this situation:

<?php

require_once 'path/to/ThumbLib.inc.php';

try
{
     $thumb = PhpThumbFactory::create('/path/to/image.jpg');
}
catch (Exception $e)
{
     // handle error here however you'd like
}

?>

That's it, you're ready to get manipulating! Head on over to the basic usage page if you want to start getting your hands dirty, or read on for a bit of information about options.

##Options

The options array allows you to customize the behavior of the library a bit. Some of these options are implementation-specific, and are noted as such. So, let's first go over what options are available to us:

Option Name	Description	Default Value	Valid Values
resizeUp	Whether or not to scale an image up to the desired dimensions	false	true / false
jpegQuality	What quality to save jpeg files with (how much compression to use, 100 being none)	100	1-100
correctPermissions	Whether or not the library should attempt to correct file permissions. This will only work if you set up your PHP to allow chmod operations	false	true / false
preserveAlpha	Whether or not to preserve alpha transparency in PNG files	true	true / false
alphaMaskColor	What rgb color should be used for the alpha mask	array(255,255,255)	array([0-255], [0-255], [0-255])
preserveTransparency	Whether or not to preserve transparency in GIF files	true	true / false
transparencyMaskColor	What rgb color should be used for the transparency mask	array(255,255,255)	array([0-255], [0-255], [0-255])

Overriding any of these values is easy. You simply need to pass an associative array with whatever key / value pairs you wish to override, you need not pass all options. You can even pass additional options if you want (perhaps for plugins). So, let's say we want to change the jpeg quality and allow images to resize up. Here's what that code would look like:

<?php

require_once 'path/to/ThumbLib.inc.php';

$options = array('resizeUp' => true, 'jpegQuality' => 80);

try
{
     $thumb = PhpThumbFactory::create('/path/to/image.jpg', $options);
}
catch (Exception $e)
{
     // handle error here however you'd like
}

?>

Note, you'll need to pass the options array to the create method EVERY TIME you call it. Options are not persisted between instances of PHP Thumb objects.