Current File : /home/dordingu/www/ragnars/misc/phpThumb/docs/phpthumb.faq.txt
//////////////////////////////////////////////////////////////
/// phpThumb() by James Heinrich <info@silisoftware.com> //
// available at http://phpthumb.sourceforge.net ///
//////////////////////////////////////////////////////////////
/// //
// Frequently Asked Questions (FAQ) about phpThumb() //
// ///
//////////////////////////////////////////////////////////////
Q: My question isn't answered here, how do I get support?
A: Please visit http://support.silisoftware.com for any
questions, suggestions, bugs, etc.
Q: I think I found a bug, what's the first thing I should do?
A: Please make sure you're using the latest version. There's
a good chance I may have already fixed the bug, so please
make sure you can reproduce it with the latest version
before reporting the bug.
Q: phpThumb doesn't work as expected, and it may be a server
configuration issue -- how do I check?
A: Please run /demo/demo.check.php to find out how your server
matches up with the recommended configuration and for
suggestions on what to change for improved performance.
Q: What is the GPL? Can I use this for commercial sites?
A: See the GPL FAQ: http://www.gnu.org/licenses/gpl-faq.html
In general, if you just want to call phpThumb.php in the
standard <img src="phpThumb.php?src=pic.jpg&w=100"> manner
then there is no problem, you're free to do this no matter
if you site is commercial or not, or what license your code
is released under.
If you're calling phpThumb() as an object then you will
probably run into license issues, so consult the above FAQ
and the GPL itself.
No matter if you use phpThumb() commercially or not, no
payment is required. However, donations are always welcome
and can be made at http://phpthumb.sourceforge.net
Q: Some images generate thumbnails, but some fail (the original
non-resized image is output instead).
A: Your PHP installation does not have a high enough memory_limit
and ImageMagick is not installed on the server. The PHP memory
required is 5 times the number of pixels in the image.
For example:
640x480x5 = 1.5MB
1600x1200x5 = 9.2MB
You can adjust the PHP memory limit in php.ini (if you have
permission on your server to do so), or (better yet) install
ImageMagick on the server and that will bypass the memory limit
issue. If you can't do either of the above, you can resize the
images manually (with your favourite image editor) to a size
that your memory_limit setting can handle, and/or you can
re-save the images with an image editor that can embed an EXIF
thumbnail (Photoshop for example) which phpThumb can use as an
image source (lower image quality, but perhaps better than
nothing).
Q: Is there are way to determine the new height and width of the
generated thumbnail (so I can put it in the <img> width/height)?
A: The problem is that phpThumb.php returns an image -- there is no
way to pass on any additional info such as width/height.
However, you can do something like this:
require_once('phpthumb.functions.php');
$pic = 'picture.jpg';
list($source_w, $source_h) = GetImageSize($pic);
$max_w = 375;
$max_h = 400;
list($newW, $newH) = phpthumb_functions::ProportionalResize(
$source_w, $source_h, $max_w, $max_h);
$url = 'phpThumb.php?src='.$pic.'&w='.$max_w.'&h='.$max_h;
echo "<img src=\"$url\" width=\"$newW\" height=\"$newH\">';
Q: I'm getting is this error message:
Failed: RenderToFile(<filename>) failed because
!is_resource($this->gdimg_output)
A: You missed the call to GenerateThumbnail() before
RenderToFile() or OutputThumbnail.
See /demo/phpThumb.demo.object.php for an example.
Q: I'm trying to save a phpThumb-generated image in Internet
Explorer and it saves in BMP format, why?
A: This is not phpThumb's fault, it is an IE issue:
http://support.microsoft.com/default.aspx?scid=kb;en-us;810978
http://support.microsoft.com/default.aspx?scid=kb;en-us;260650
Q: PNG images with transparent areas show up with gray background
in the areas that are supposed to be transparent.
A: Internet Explorer has had a broken PNG alpha-channel display
implementation for a decade, so it may never get fixed. Other
major browsers generally handle alpha-transparent PNGs fine.
See http://www.silisoftware.com/png_transparency/
For an alpha-channel PNG display in IE hack, see this page:
http://www.koivi.com/ie-png-transparency/
Q: I'm getting "<filename> does not exist" when I know the
file does exist
A: Check that these two values are present and properly
configured in phpThumb.config.php (introduced in v1.6.0):
$PHPTHUMB_CONFIG['allow_src_above_docroot'] (default=false)
$PHPTHUMB_CONFIG['allow_src_above_phpthumb'] (default=true)
If your images are outside DOCUMENT_ROOT (this includes if
you have an image upload form, most likely the images will
get uploaded to "/tmp/<file>" or similar) then you will have
to configure 'allow_src_above_docroot' to true.
Make sure whatever user the webserver is running as has read
permission to the file/directory you're reading from
Q: Should I use phpThumb.php, or use phpThumb() as an object?
A: phpThumb.php is easier to use (less coding) for basic uses.
phpThumb.php handles all caching; your own object will need
to have its own caching code. If you just want to display a
thumbnailed version of an existing image, use phpThumb.php
If you want to render one (or more) thumbnails to static
files (during upload, for example), that's an appropriate
use for the object mode. Also, phpThumb.config.php is only
used by phpThumb.php, so if you instantiate your own object
you need to manually set all configuration options because
phpThumb.config.php has NO effect. So, to repeat:
**always use phpThumb.php unless you NEED to have an object**
Q: The first time I go to a page which contains thumbnails I
don't actually see the thumbnail, I just get a browser image
placeholder (or no image). As soon as I hit refresh, all the
thumbnail images pop into place really fast.
A: You can try and see if it works better with
$PHPTHUMB_CONFIG['cache_force_passthru'] = false;
but typically the default setting works better.
Note: There were some maybe-undefined variables prior to
v1.7.9 that contributed to this behavior. If you notice
this happening in v1.7.9 or newer please email me at
info@silisoftware.com
Q: Are there any front-end GUI interfaces to phpThumb()?
A: See /demo/readme.demo.txt
Q: Are there / have there been any security issues in phpThumb?
A: http://secunia.com/product/5199/
Q: Why can't Flash work with images output from phpThumb()?
A: Flash doesn't like progressive JPEG. Set:
$PHPTHUMB_CONFIG['output_interlace'] = false;
Q: Image quality is not very good - why?
A: If you're using GD v1.x, no way around it. Upgrade to GD v2.x
Q: Image quality is very bad, very pixelated -- why?
A: You may be trying to resize images larger than the available
PHP memory, so phpThumb is simply extracting and using the
EXIF thumbnail as the image source, which is usually about
160x120 (so if you resize it to 640x480 it will look very bad).
To calculate the required size for memory_limit in php.ini,
calculate the number of pixels in the image and multiply by 5:
For example, 1600x1200 = 1600 * 1200 * 5 = 9600000 = 10M
Easy solution: install ImageMagick
Q: Can I save the generated thumbnail to a file?
A: Yes, there are several ways to do so; the best way is to call
phpThumb as an object and call RenderToFile() to save the
thumbnail to whatever filename you want.
See /demo/phpThumb.demo.object.php for an example.
The other way is to use the 'file' parameter (see
/docs/phpthumb.readme.txt) but this parameter is deprecated
and does not work in phpThumb v1.7.5 and newer.
Q: "Off-server thumbnailing is not allowed" -- how do I enable it?
A: By default, phpThumb() only makes thumbnails for the same
domain that it is running on. To allow it to make thumbnails
for a limited number of other domains, add them
(in phpThumb.config.php) like this:
$PHPTHUMB_CONFIG['nohotlink_valid_domains'] = array(
@$_SERVER['HTTP_HOST'], 'example.com', 'www.example.com',
'subdomain.example.net', 'example.org');
To disable off-server thumbnail blocking, just set:
$PHPTHUMB_CONFIG['nohotlink_enabled'] = false;
Q: Is it possible to set the parameters (like w/h/fltr[]) in
the config, so that they can't be changed over the URL?
A: Take a look at $PHPTHUMB_DEFAULTS at the bottom of
phpThumb.config.php You'll want to set
$PHPTHUMB_DEFAULTS_GETSTRINGOVERRIDE = false
possibly also
$PHPTHUMB_DEFAULTS_DISABLEGETPARAMS = true
You may also want to investigate
$PHPTHUMB_CONFIG['high_security_enabled'] = true
(see the example at the bottom of phpThumb.config.php
for how to call images in HighSecurity mode)
Q: Is there a way to use phpThumb() object to create thumbnails
without the parameters in the URL showing the location of
the image etc?
A: There is a demo in /demo/phpThumb.demo.object.php. You could
modify this into your own file, but there still remains the
problem of passing parameters to the file, whether it's
phpThumb.php or your own instantiation of a phpThumb() object.
I would suggest is putting as many of the common parameters
into phpThumb.config.php as possible under $PHPTHUMB_DEFAULTS,
so you then don't have to pass them for each image. If you
don't want people modifying the parameters, turn on
$PHPTHUMB_CONFIG['high_security_enabled'] and set a password
(you'll need to generate the <img> tags with phpThumbURL()
provided at the bottom of phpThumb.config.php). If you don't
want people accessing your source images at all, you can
place them outside DOCUMENT_ROOT on your server (as long as
phpThumb/PHP has read access to the directory). The other
option is to put your source images in a MySQL database
and set $PHPTHUMB_CONFIG['mysql_query'] and related
parameters in phpThumb.config.php to pull your source images
from the database. That way it's impossible to retrieve the
images except through phpThumb.php, and if high_security is
enabled, then nobody can modify the parameters to view
anything except what you want to show. So, yes, it's possible
to use your own object, but it's probably better to use
phpThumb.php if possible -- one notable issue is that
phpThumb.php handles all the caching, so you're on your own
to deal with that if you create your own object.
Q: How do I write the output thumbnail back to a database instead
of outputting to the browser or a file?
A: See /demo/phpThumb.demo.object.php Basically you need to call
$this->GenerateThumbnail() then $this->RenderOutput() and then
the output raw image data is found in $this->outputImageData
Q: phpThumb runs slowly, as if the images aren't cached, when I use HTTP source
images (not on my server). How can I make it go faster?
A: $PHPTHUMB_CONFIG['cache_source_filemtime_ignore_remote'] = true;
// if true, remote source images will not be checked for modification date and
// cached image will be used if available, even if source image is changed or removed
Q: What does the "cache_default_only_suffix" configuration option do?
A: Cache files are normally created with big ugly names like
"phpThumb_cache_www.example.com_src1a482c2c760463795ff18faf073b389f_par3e099041c2f4a73041a7f5d7e7fc481a_dat1119952152.jpeg"
but if cache_default_only_suffix is enabled, cache filenames are simplified to
"pic_thumb.jpg" (for example). The problem is that only one version of that
thumbnail is possible, and you can never call it again with a different size,
or different filters, etc. Generally you don't want that enabled, but it's
there because some people asked for it.
Q: Why is the visual size of rotated images smaller than the unrotated images?
A: phpThumb fits the rotated image into the 'w' and 'h' dimensions.
Try not specifying a 'w' parameter: phpThumb.php?src=file.png&ra=15
That should leave the image the apparent same size as the unrotated image
(in actual fact the canvas size is enlarged to fit the rotated image in it).
Q: phpThumb.demo.check.php says Safe Mode is off for Master but on for Local,
and I checked php.ini and it's already set off. How do I disable safe mode?
A: Your PHP was probably installed as an Apache module. If so, you have to set
php_admin_value safe_mode "Off"
in your domain settings (usually between <VirtualHost> tags in httpd.conf).
Then you have to restart Apache.
Q: How can I purge cached files when I delete the source image?
A: You can either let phpThumb's built-in cache purging features (see phpThumb.config.php)
take effect, or you can manually walk through your source images to delete and find
the matching cache files and delete them:
if ($dh = opendir($sourcedir)) {
while ($file = readddir($dh)) {
if ($file == $WhatIwantToDelete) {
$md5 = md5_file($sourcedir.'/'.$file);
unlink($phpthumb_cache_dir.'/phpThumb_cache_www.example.com_src'.$md5.'*.*');
}
}
closedir($dh);
}
Q: Is it safe to delete cache files?
A: Yes, it is safe to delete any cache files and/or directories. phpThumb will
automatically re-create them as needed. Also, take a look at the "cache_max*"
settings in phpThumb.config.php for automatic cache purging.
Q: How can I find the filename that phpThumb.php will use to
cache a particular image?
A: It's not easily possible to get the cache filename. You can
see the method used to calculate it in SetCacheFilename()
in phpthumb.class.php (around line 2991-3090). If you need
to know where an image will be rendered to, it may be
easier and better to call phpThumb as an object and handle
your own caching. See /demo/phpThumb.demo.object.simple.php
for an example.
Q: Can I make thumbnails from a PDF?
A: Yes, as long as you have both ImageMagick and GhostScript
installed. The AFPL version of GhostScript seems to work
better than the GNU version (at least for me it does).
http://www.imagemagick.org
http://www.cs.wisc.edu/~ghost/
You may want to use the "sfn" (Source Frame Number)
parameter of phpThumb to specify which page to thumbnail.
Q: Can I make a thumbnail of a webpage?
A: Possibly, but it's not easy. Theoretically, if you have
html2ps, GhostScript and ImageMagick all installed it should
be possible, but I have not tested that. Other projects that
attempt to generate thumbnails from webpages include:
http://www.boutell.com/webthumb/
Q: When I resize an animated GIF the new "smaller" version is
actually a larger file size -- why?
A: Animated GIFs use a variety of temporal and spatial compression
techniques. The source GIF is probably very well optimized, but
when each frame is resized some of the desirable compression
properties could be negatively affected (the number of colours
can increase; dithered areas compress very poorly compared to
solid areas of colour). ImageMagick may also not produce the
most filesize-optimized animated GIF possible.
Q: Can I use source images from (same or another) server that uses
a script with parameters to display images? For example:
http://sourceforge.net/sflogo.php?group_id=106407&type=5
(displays a PNG image, 210x62)
A: Yes, you should be able to use phpThumb like that no problem.
If the source image is on a different server you need to set
$PHPTHUMB_CONFIG['nohotlink_valid_domains'] to contain the source
domain(s) [eg: sourceforge.net] if it's a small list of possible
source domains, or make sure $PHPTHUMB_CONFIG['nohotlink_enabled']
is set to false to allow creating source images from any domain/IP.
You will also need to properly encode the image source (using PHP
function rawurlencode):
/phpThumb.php?src=http%3A%2F%2Fsourceforge.net%2Fsflogo.php%3Fgroup_id%3D106407%26type%3D5&w=100
Q: phpThumb is the best software in the world, how can I donate?
A: There's a handy "Support this project" button at the top of
http://phpthumb.sourceforge.net which will take you through
the process (and give SourceForge a ~5% cut), or if you prefer
you can send PayPal donations directly to info@silisoftware.com
Q: What is the proper name for this script/program/library?
A: The official name is "phpThumb()" but it may be written
as simply "phpThumb" in short form (or where parentheses
are not permitted), or "phpthumb" in case-insensitive
environments. The following is a non-exhaustive sample of
unacceptable forms: PHPthumb; phpThumbs; phpthump;
phpthumbnailer; phpThumbnail; PHP Thumb; Phpthumb; etc.
Mini Shell