//////////////////////////////////////////////////////////////
/// phpThumb() by James Heinrich <hide@address.com> //
// available at http://phpthumb.sourceforge.net ///
//////////////////////////////////////////////////////////////
/// //
// This code is released under the GNU GPL: //
// http://www.gnu.org/copyleft/gpl.html //
// //
// +-----------------------------------------------+ //
// | phpThumb() is free to use according to the | //
// | terms of the GPL. Donations also gratefully | //
// | accepted from happy users :) | //
// | Please see http://phpthumb.sourceforge.net | //
// | | //
// | If you like phpThumb(), please consider | //
// | writing a review at HotScripts.com: | //
// | http://www.hotscripts.com/Detailed/25654.html | //
// | | //
// | If you do use this code somewhere, send me | //
// | an email and tell me how/where you used it. | //
// +-----------------------------------------------+ //
// ///
//////////////////////////////////////////////////////////////
Description:
phpThumb() uses the GD library to create thumbnails from
images (GIF, PNG or JPEG) on the fly. The output size is
configurable (can be larger or smaller than the source),
and the source may be the entire image or only a portion
of the original image. True color and resampling is used
if GD v2.0+ is available, otherwise low-color and simple
resizing is used. Source image can be a physical file on
the server or can be retrieved from a database. GIFs are
supported on all versions of GD even if GD does not have
native GIF support thanks to the GIFutil class by Fabien
Ezber. AntiHotlinking feature prevents other people from
using your server to resize their thumbnails. The cache
feature reduces server load.
Usage:
Call phpThumb() just like you would a normal image.
Examples:
<IMG SRC="phpThumb.php?src=/image.jpg&w=100">
<IMG SRC="phpThumb.php?src=http://example.com/foo.jpg">
See the "demo" link on http://phpthumb.sourceforge.net
for more usage examples). Parameters that can be passed
are listed below under "URL Parameters".
NOTE: It's recommended you use the local image filename
wherever possible (rather than http://) because performance
is much better, less (or no) use of temp files, and the
last-modified check for cached files doesn't work for
remote files.
To access files over a LAN with Windows share names you
must use the network name (or IP) and not a mapped drive
name, for example:
//othercomputer/file.jpg - good
//192.168.2.1/file.jpg - good
z:/file.jpg - won't work
This is a PHP limitation (see www.php.net/file-exists)
Note: you may want to use "/" slashes instead of "\" if
you have magic_quotes_gpc enabled to avoid stripslashes
problems, although either slash should work if
magic_quotes_gpc is disabled
Configuration:
There are some configuration options you may (but are
not required to) change. Most configuration options can
be set when you call phpThumb() - see list below), but
default configuration options (such as cache directory)
are in phpThumb.config.php - this is the only file you
should ever modify.
The amount of memory required for phpThumb depends on
several factors: the dimensions of the source image,
the dimensions of the output image, whether unsharp
masking is applied, whether watermarks are applied, etc.
The auto-detection of memory limits works as a general
"safe" value. You may be able to exceed the auto value
by a small or large amount, depending on whether you
apply watermarks and/or sharpening, and the output size
of your thumbnails. I do not currently have a reliable
formula for calculating such things, but I will attempt
to craft one for future versions of phpThumb(). Until
then, set "max_source_pixels" in phpThumb.config.php to a
value that works well for you (or leave it alone if the
defaults give you no problems).
The configuration options you should maybe modify are:
* cache_directory - thumbnailing is slow and processor-
intensive. Enabling caching will dramatically speed
up future thumbnail serving
* max_source_pixels - This should be auto-detected, but
if auto-detection fails and you get an invalid image
from large source images, set this to about 20% of
your available PHP memory limit.
* imagemagick_path - If the source image is larger than
max_source_pixels allows, but ImageMagick is available
phpThumb() will use it to generate the thumbnail.
Calling as an object (not using phpThumb.php):
To use a database rather than physical files, or to
render output to a file instead of the browser, you
should skip phpThumb.php and instantiate your own
phpThumb() object as follows:
// create new phpThumb() object
require_once('phpthumb.class.php');
$phpThumb = new phpThumb();
// set data
$phpThumb->rawImageData = $binary_image_data;
// or $phpThumb->src = $sourceFilename;
// set parameters (see "URL Parameters" below)
$phpThumb->w = 100;
// set options (see phpThumb.config.php)
// here you must preface each option with "config_"
$phpThumb->config_output_format = 'jpeg';
// Set error handling (optional)
$phpThumb->config_error_die_on_error = false;
// generate & output thumbnail
if ($phpThumb->GenerateThumbnail()) {
$phpThumb->RenderToFile($filename);
// or $phpThumb->OutputThumbnail();
} else {
// do something with debug/error messages
echo 'Failed: '.implode("\n", $phpThumb->debugmessages);
}
If you want to change any of the configuration parameters
(see phpThumb.config.php) you can change them like this:
$phpThumb->config_<variable_name> = <value>
for example:
$phpThumb->config_output_format = 'jpeg';
Note: If you want to loop through and create multiple
thumbnails from different image sources, you should
create and dispose an instance of phpThumb() each time
through the loop and not reuse the object.
URL Parameters:
w = max width of output thumbnail in pixels
h = max height of output thumbnail in pixels
f = output image format ('jpeg', 'png', or 'gif')
q = JPEG compression (1=worst, 95=best, 75=default)
sx = left side of source rectangle (default = 0)
(values 0 < sx < 1 represent percentage)
sy = top side of source rectangle (default = 0)
(values 0 < sy < 1 represent percentage)
sw = width of source rectangle (default = fullwidth)
(values 0 < sw < 1 represent percentage)
sh = height of source rectangle (default = fullheight)
(values 0 < sh < 1 represent percentage)
bw = border width in pixels (set to enable fixed-size
thumbnails with background filled with 'bg' color
bg = background hex color (default = FFFFFF)
bgt = background color is transparent (default = 0)
use with brx/bry, set to 1 for transparency,
set to 256 for IE-compatible 256-color mode
bc = border hex color (default = 000000)
usr = unsharp mask radius (default = 0.5, range 0.5-1)
usa = unsharp mask amount (default = 80, range 50-200)
ust = unsharp mask threshold (default = 3, range 0-10)
wmf = filename of watermark image (default = none)
wmp = % opacity of watermark image (default = 50)
wmm = % margin to watermark image (default = 5)
wma = watermark alignment (default = BR = bottom-right)
one of: BR, BL, TR, TL, C, R, L, T, B, *
B=bottom,T=top,L=left,R=right,C=centre,*=tile
file = if set then thumbnail will be rendered to this
filename, not output and not cached. (Deprecated,
recommended you instantiate your own object instead)
goto = URL to redirect to after rendering image to file
* Must begin with 'http://'
* Requires file parameter set
(Deprecated, recommended you instantiate your own
object instead)
err = custom error image filename instead of showing
error messages (for use on production sites)
xto = EXIF Thumbnail Only - set to only extract EXIF
thumbnail and not do any additional processing
ra = Rotate Angle: angle of rotation in degrees
positive = counterclockwise, negative = clockwise
ar = Auto Rotate: can be 'l' or 'L' for landscape, or
'p' or 'P' for portrait. 'l' and 'P' rotate the
image clockwise, 'L' and 'p' rotate the image
counter-clockwise. If your images get rotated
upside-down, email me a suggestion for how to do
it better :)
aoe = Output Allow Enlarging - override the setting for
$CONFIG['output_allow_enlarging'] (1=on, 0=off)
iar = Ignore Aspect Ratio - disable proportional resizing
and stretch image to fit 'h' & 'w' (which must both
be specified). (1=on, 0=off)
brx,
bry = border radius in pixels (radius of curved corners)
You must specify both 'brx' (horizontal radius)
and 'bry' (vertical radius) as well as 'bw'
(border width). If 'bw' is greater than zero, the
image will be shrunk to fit inside the border with
a margin of background color. If 'bw' is zero, the
corners of the image will be cut off and filled
with background color.
maxb = MAXimum Byte size - auto-set compression (JPEG) or
bit depth (GIF & PNG) to fit thumbnail into 'maxb'
bytes of output image.
down = filename to save image to. If this is set the
browser will prompt to save to this filename rather
than display the image
Additional Object-only configuration variables:
rawImageData = binary data of source image, for example
if the source data is from a database. Set
this value instead of setting 'src'.
General Notes:
* Always use the local image filename wherever possible
rather than a full http:// URL because performance is
much better, less (or no) use of temp files, and the
last-modified check for cached files doesn't work for
remote files.
* Thumbnails will be scaled proportionately to fit in a
box of at most (width * height) pixels
(unless 'iar' is set)
* Thumbnail caching for URL or database sources requires
an absolute directory name for $config_cache_directory
Physical file cached thumbnails will be recreated if
the source file changes, but remote/database files
cannot (modification time isn't readily available)
* If you need a GUI interface for a user to specify crop
settings you can investigate 12cropimage:
http://one-two.net/12cropimage
* Cropping images can be specified with either exact pixel
values for sx/sy/sw/sh parameters, or if those are set
to a value >0 and <1 then these are interpreted as a
percentage of the source image width/height. For example,
to crop 25% off all sides, you would specify parameters:
phpThumb.php?src=pic.jpg&sx=.25&sy=.25&sw=.5&sh=.5
* phpThumb() may have tempfile access issues on servers
where Safe Mode is enabled, specificly when accessing
a file over HTTP, or when a non-bundled version of GD
is in use. Specifying 'config_temp_directory' may help
* Transparent PNG output is buggy with true-color images
and some software (Internet Explorer, Photoshop). Output
can be forced to 256-color mode for compatability by
setting the 'bgt' parameter to '256'
* Properly resolving /~user/ style filenames requires
apache_lookup_uri(), which is missing or broken in
Apache2, or if PHP is not installed as an Apache module.
phpThumb() does try and work around this if it is
unavailble, but you may have to specify a full filename
for "src" if you encounter problems.
* phpThumb() should work with PHP v4.0.6+, but seems to
have a few quirks before v4.1.0
EXIF thumbnail extraction requires PHP v4.2.0+
Image rotation requires PHP v4.3.0+. There have been
reports of problems with PHP older than v4.3.3
* phpThumb() works fine with GD v1.x, but works better
with GD v2.0+ because of the true-color image support
and ImageCopyResampled(). Also, there appears to be a
bug in ImageCopyResized() which is used with GD v1.x
where the bottom and/or right line of pixels is set
to the background color (due to a rounding error?)
NOTE: Please use the bundled version of GD if at all
possible (with PHP v4.3.0+) because the non-bundled
version has bugs which may cause PHP to crash:
* http://bugs.php.net/bug.php?id=21518
* http://bugs.php.net/bug.php?id=24174
phpThumb() has a workaround for the above bug but
there may be other bugs, and the workaround is slow.
Watermarks work MUCH better with GD v2 than GD v1!
Unsharp masking requires GD v2.x
Rounded Image Corners requires GD v2.x