1 //////////////////////////////////////////////////////////////
2 /// phpThumb() by James Heinrich <info@silisoftware.com> //
3 // available at http://phpthumb.sourceforge.net ///
4 //////////////////////////////////////////////////////////////
6 // Frequently Asked Questions (FAQ) about phpThumb() //
8 //////////////////////////////////////////////////////////////
11 Q: My question isn't answered here and I can't find any
12 forums, how do I get support?
13 A: Please email me directly at info@silisoftware.com with
14 any questions, suggestions, donations, etc.
17 Q: I think I found a bug, what's the first thing I should do?
18 A: Please make sure you're using the latest version. There's
19 a good chance I may have already fixed the bug, so please
20 make sure you can reproduce it with the latest version
21 before reporting the bug.
24 Q: phpThumb doesn't work as expected, and it may be a server
25 configuration issue -- how do I check?
26 A: Please run /demo/demo.check.php to find out how your server
27 matches up with the recommended configuration and for
28 suggestions on what to change for improved performance.
31 Q: What is the GPL? Can I use this for commercial sites?
32 A: See the GPL FAQ: http://www.gnu.org/licenses/gpl-faq.html
33 In general, if you just want to call phpThumb.php in the
34 standard <img src="phpThumb.php?src=pic.jpg&w=100"> manner
35 then there is no problem, you're free to do this no matter
36 if you site is commercial or not, or what license your code
38 If you're calling phpThumb() as an object then you will
39 probably run into license issues, so consult the above FAQ
41 No matter if you use phpThumb() commercially or not, no
42 payment is required. However, donations are always welcome
43 and can be made at http://phpthumb.sourceforge.net
46 Q: Some images generate thumbnails, but some fail (the original
47 non-resized image is output instead).
48 A: Your PHP installation does not have a high enough memory_limit
49 and ImageMagick is not installed on the server. The PHP memory
50 required is 5 times the number of pixels in the image.
54 You can adjust the PHP memory limit in php.ini (if you have
55 permission on your server to do so), or (better yet) install
56 ImageMagick on the server and that will bypass the memory limit
57 issue. If you can't do either of the above, you can resize the
58 images manually (with your favourite image editor) to a size
59 that your memory_limit setting can handle, and/or you can
60 re-save the images with an image editor that can embed an EXIF
61 thumbnail (Photoshop for example) which phpThumb can use as an
62 image source (lower image quality, but perhaps better than
66 Q: I'm getting is this error message:
\r
67 Failed: RenderToFile(<filename>) failed because
\r
68 !is_resource($this->gdimg_output)
\r
69 A: You missed the call to GenerateThumbnail() before
70 RenderToFile() or OutputThumbnail.
71 See /demo/phpThumb.demo.object.php for an example.
74 Q: I'm trying to save a phpThumb-generated image in Internet
75 Explorer and it saves in BMP format, why?
76 A: This is not phpThumb's fault, it is an IE issue:
77 http://support.microsoft.com/default.aspx?scid=kb;en-us;810978
\r
78 http://support.microsoft.com/default.aspx?scid=kb;en-us;260650
\r
81 Q: PNG images with transparent areas show up with gray background
82 in the areas that are supposed to be transparent.
83 A: Internet Explorer has had a broken PNG alpha-channel display
84 implementation for a decade, so it may never get fixed. Other
85 major browsers generally handle alpha-transparent PNGs fine.
86 See http://www.silisoftware.com/png_transparency/
87 For an alpha-channel PNG display in IE hack, see this page:
88 http://www.koivi.com/ie-png-transparency/
91 Q: I'm getting "<filename> does not exist" when I know the
93 A: Check that these two values are present and properly
94 configured in phpThumb.config.php (introduced in v1.6.0):
95 $PHPTHUMB_CONFIG['allow_src_above_docroot'] (default=false)
96 $PHPTHUMB_CONFIG['allow_src_above_phpthumb'] (default=true)
97 If your images are outside DOCUMENT_ROOT then you will have
98 to configure 'allow_src_above_docroot' to true.
99 Make sure whatever user the webserver is running as has read
100 permission to the file/directory you're reading from
\r
103 Q: Should I use phpThumb.php, or use phpThumb() as an object?
104 A: phpThumb.php is easier to use (less coding) for basic uses.
105 phpThumb.php handles all caching; your own object will need
106 to have its own caching code. If you just want to display a
107 thumbnailed version of an existing image, use phpThumb.php
108 If you want to render one (or more) thumbnails to static
109 files (during upload, for example), that's an appropriate
110 use for the object mode. Also, phpThumb.config.php is only
111 used by phpThumb.php, so if you instantiate your own object
112 you need to manually set all configuration options because
113 phpThumb.config.php has NO effect. So, to repeat:
114 **always use phpThumb.php unless you NEED to have an object**
117 Q: The first time I go to a page which contains thumbnails I
118 don't actually see the thumbnail, I just get a browser image
119 placeholder (or no image). As soon as I hit refresh, all the
120 thumbnail images pop into place really fast.
121 A: You can try and see if it works better with
\r
122 $PHPTHUMB_CONFIG['cache_force_passthru'] = false;
\r
123 but typically the default setting works better.
124 This is something of an unresolved issue on some servers,
125 where for whatever reason I haven't (yet?) been able to
126 figure out a setting that always works the first time. If the
127 above config setting doesn't help, you might be stuck with
128 having to manually or automagically pre-cache thumbnails as
129 they're created. Please email info@silisoftware.com if you
130 have a better solution...
133 Q: Are there any front-end GUI interfaces to phpThumb()?
134 A: See /demo/readme.demo.txt
137 Q: Are there / have there been any security issues in phpThumb?
138 A: http://secunia.com/product/5199/
141 Q: Why can't Flash work with images output from phpThumb()?
142 A: Flash doesn't like progressive JPEG. Set:
143 $PHPTHUMB_CONFIG['output_interlace'] = false;
146 Q: Image quality is not very good - why?
147 A: If you're using GD v1.x, no way around it. Upgrade to GD v2.x
150 Q: Image quality is very bad, very pixelated -- why?
151 A: You may be trying to resize images larger than the available
152 PHP memory, so phpThumb is simply extracting and using the
153 EXIF thumbnail as the image source, which is usually about
154 160x120 (so if you resize it to 640x480 it will look very bad).
155 To calculate the required size for memory_limit in php.ini,
156 calculate the number of pixels in the image and multiply by 5:
157 For example, 1600x1200 = 1600 * 1200 * 5 = 9600000 = 10M
158 Easy solution: install ImageMagick
161 Q: Can I save the generated thumbnail to a file?
162 A: Yes, there are several ways to do so; the best way is to call
163 phpThumb as an object and call RenderToFile() to save the
164 thumbnail to whatever filename you want.
165 See /demo/phpThumb.demo.object.php for an example.
166 The other way is to use the 'file' parameter (see
167 /docs/phpthumb.readme.txt) but this parameter is deprecated
168 and may not exist in future versions of phpThumb().
\r
171 Q: "Off-server thumbnailing is not allowed" -- how do I enable it?
172 A: By default, phpThumb() only makes thumbnails for the same
173 domain that it is running on. To allow it to make thumbnails
174 for a limited number of other domains, add them
175 (in phpThumb.config.php) like this:
176 $PHPTHUMB_CONFIG['nohotlink_valid_domains'] = array(
177 @$_SERVER['HTTP_HOST'], 'example.com', 'www.example.com',
178 'subdomain.example.net', 'example.org');
179 To disable off-server thumbnail blocking, just set:
180 $PHPTHUMB_CONFIG['nohotlink_enabled'] = false;
183 Q: Is it possible to set the parameters (like w/h/fltr[]) in
184 the config, so that they can't be changed over the URL?
\r
185 A: Take a look at $PHPTHUMB_DEFAULTS at the bottom of
186 phpThumb.config.php You'll want to set
187 $PHPTHUMB_DEFAULTS_GETSTRINGOVERRIDE = false
\r
189 $PHPTHUMB_DEFAULTS_DISABLEGETPARAMS = true
\r
190 You may also want to investigate
191 $PHPTHUMB_CONFIG['high_security_enabled'] = true
192 (see the example at the bottom of phpThumb.config.php
193 for how to call images in HighSecurity mode)
196 Q: Is there a way to use phpThumb() object to create thumbnails
197 without the parameters in the URL showing the location of
199 A: There is a demo in /demo/phpThumb.demo.object.php. You could
200 modify this into your own file, but there still remains the
201 problem of passing parameters to the file, whether it's
202 phpThumb.php or your own instantiation of a phpThumb() object.
203 I would suggest is putting as many of the common parameters
204 into phpThumb.config.php as possible under $PHPTHUMB_DEFAULTS,
205 so you then don't have to pass them for each image. If you
206 don't want people modifying the parameters, turn on
207 $PHPTHUMB_CONFIG['high_security_enabled'] and set a password
208 (you'll need to generate the <img> tags with phpThumbURL()
209 provided at the bottom of phpThumb.config.php). If you don't
210 want people accessing your source images at all, you can
211 place them outside DOCUMENT_ROOT on your server (as long as
212 phpThumb/PHP has read access to the directory). The other
213 option is to put your source images in a MySQL database
214 and set $PHPTHUMB_CONFIG['mysql_query'] and related
215 parameters in phpThumb.config.php to pull your source images
216 from the database. That way it's impossible to retrieve the
217 images except through phpThumb.php, and if high_security is
218 enabled, then nobody can modify the parameters to view
219 anything except what you want to show. So, yes, it's possible
220 to use your own object, but it's probably better to use
221 phpThumb.php if possible -- one notable issue is that
222 phpThumb.php handles all the caching, so you're on your own
223 to deal with that if you create your own object.
226 Q: How do I write the output thumbnail back to a database instead
227 of outputting to the browser or a file?
228 A: See /demo/phpThumb.demo.object.php Basically you need to call
229 $this->GenerateThumbnail() then $this->RenderOutput() and then
230 the output raw image data is found in $this->outputImageData
233 Q: phpThumb runs slowly, as if the images aren't cached, when I use HTTP source
234 images (not on my server). How can I make it go faster?
235 A: $PHPTHUMB_CONFIG['cache_source_filemtime_ignore_remote'] = true;
236 // if true, remote source images will not be checked for modification date and
237 // cached image will be used if available, even if source image is changed or removed
\r
240 Q: What does the "cache_default_only_suffix" configuration option do?
241 A: Cache files are normally created with big ugly names like
242 "phpThumb_cache_www.example.com_src1a482c2c760463795ff18faf073b389f_par3e099041c2f4a73041a7f5d7e7fc481a_dat1119952152.jpeg"
243 but if cache_default_only_suffix is enabled, cache filenames are simplified to
244 "pic_thumb.jpg" (for example). The problem is that only one version of that
245 thumbnail is possible, and you can never call it again with a different size,
246 or different filters, etc. Generally you don't want that enabled, but it's
247 there because some people asked for it.
250 Q: Why is the visual size of rotated images smaller than the unrotated images?
251 A: phpThumb fits the rotated image into the 'w' and 'h' dimensions.
252 Try not specifying a 'w' parameter: phpThumb.php?src=file.png&ra=15
\r
253 That should leave the image the apparent same size as the unrotated image
254 (in actual fact the canvas size is enlarged to fit the rotated image in it).
\r
257 Q: How can I purge cached files when I delete the source image?
258 A: You can either let phpThumb's built-in cache purging features (see phpThumb.config.php)
259 take effect, or you can manually walk through your source images to delete and find
260 the matching cache files and delete them:
261 if ($dh = opendir($sourcedir)) {
262 while ($file = readddir($dh)) {
263 if ($file == $WhatIwantToDelete) {
264 $md5 = md5_file($sourcedir.'/'.$file);
265 unlink($phpthumb_cache_dir.'/phpThumb_cache_www.example.com_src'.$md5.'*.*');
272 Q: What is the proper name for this script/program/library?
273 A: The official name is "phpThumb()" but it may be written
274 as simply "phpThumb" in short form (or where parentheses
275 are not permitted), or "phpthumb" in case-insensitive
276 environments. The following is a non-exhaustive sample of
277 unacceptable forms: PHPthumb; phpThumbs; phpthump;
278 phpthumbnailer; phpThumbnail; PHP Thumb; Phpthumb; etc.