1////////////////////////////////////////////////////////////////// 2// phpThumb() by James Heinrich <info@silisoftware.com> // 3// available at http://phpthumb.sourceforge.net // 4// and/or https://github.com/JamesHeinrich/phpThumb // 5////////////////////////////////////////////////////////////////// 6/// // 7// Frequently Asked Questions (FAQ) about phpThumb() // 8// /// 9////////////////////////////////////////////////////////////////// 10 11 12Q: My question isn't answered here, how do I get support? 13A: Please visit http://support.silisoftware.com for any 14 questions, suggestions, bugs, etc. 15 16 17Q: I think I found a bug, what's the first thing I should do? 18A: Please make sure you're using the latest version: 19 https://github.com/JamesHeinrich/phpThumb 20 There's a good chance I may have already fixed the bug, so 21 please make sure you can reproduce it with the latest version 22 before reporting the bug. 23 24 25Q: phpThumb doesn't work as expected, and it may be a server 26 configuration issue -- how do I check? 27A: Please run /demo/demo.check.php to find out how your server 28 matches up with the recommended configuration and for 29 suggestions on what to change for improved performance. 30 31 32Q: What is the GPL? Can I use this for commercial sites? 33A: See the GPL FAQ: http://www.gnu.org/licenses/gpl-faq.html 34 In general, if you just want to call phpThumb.php in the 35 standard <img src="phpThumb.php?src=pic.jpg&w=100"> manner 36 then there is no problem, you're free to do this no matter 37 if you site is commercial or not, or what license your code 38 is released under. 39 If you're calling phpThumb() as an object then you will 40 probably run into license issues, so consult the above FAQ 41 and the GPL itself. 42 No matter if you use phpThumb() commercially or not, no 43 payment is required. However, donations are always welcome 44 and can be made at http://phpthumb.sourceforge.net 45 46 47Q: Some images generate thumbnails, but some fail (the original 48 non-resized image is output instead). 49A: Your PHP installation does not have a high enough memory_limit 50 and ImageMagick is not installed on the server. The PHP memory 51 required is 5 times the number of pixels in the image. 52 For example: 53 640x480x5 = 1.5MB 54 1600x1200x5 = 9.2MB 55 You can adjust the PHP memory limit in php.ini (if you have 56 permission on your server to do so), or (better yet) install 57 ImageMagick on the server and that will bypass the memory limit 58 issue. If you can't do either of the above, you can resize the 59 images manually (with your favourite image editor) to a size 60 that your memory_limit setting can handle, and/or you can 61 re-save the images with an image editor that can embed an EXIF 62 thumbnail (Photoshop for example) which phpThumb can use as an 63 image source (lower image quality, but perhaps better than 64 nothing). 65 66 67Q: Is there are way to determine the new height and width of the 68 generated thumbnail (so I can put it in the <img> width/height)? 69A: The problem is that phpThumb.php returns an image -- there is no 70 way to pass on any additional info such as width/height. 71 However, you can do something like this: 72 require_once('phpthumb.functions.php'); 73 $pic = 'picture.jpg'; 74 list($source_w, $source_h) = GetImageSize($pic); 75 $max_w = 375; 76 $max_h = 400; 77 list($newW, $newH) = phpthumb_functions::ProportionalResize( 78 $source_w, $source_h, $max_w, $max_h); 79 $url = 'phpThumb.php?src='.$pic.'&w='.$max_w.'&h='.$max_h; 80 echo "<img src=\"$url\" width=\"$newW\" height=\"$newH\">'; 81 82 83Q: I'm getting is this error message: 84 Failed: RenderToFile(<filename>) failed because 85 !is_resource($this->gdimg_output) 86A: You missed the call to GenerateThumbnail() before 87 RenderToFile() or OutputThumbnail. 88 See /demo/phpThumb.demo.object.php for an example. 89 90 91Q: I'm trying to save a phpThumb-generated image in Internet 92 Explorer and it saves in BMP format, why? 93A: This is not phpThumb's fault, it is an IE issue: 94 http://support.microsoft.com/default.aspx?scid=kb;en-us;810978 95 http://support.microsoft.com/default.aspx?scid=kb;en-us;260650 96 97 98Q: PNG images with transparent areas show up with gray background 99 in the areas that are supposed to be transparent. 100A: Internet Explorer has had a broken PNG alpha-channel display 101 implementation for a decade, so it may never get fixed. Other 102 major browsers generally handle alpha-transparent PNGs fine. 103 See http://www.silisoftware.com/png_transparency/ 104 For an alpha-channel PNG display in IE hack, see this page: 105 http://www.koivi.com/ie-png-transparency/ 106 107 108Q: I'm getting "<filename> does not exist" when I know the 109 file does exist 110A: Check that these two values are present and properly 111 configured in phpThumb.config.php (introduced in v1.6.0): 112 $PHPTHUMB_CONFIG['allow_src_above_docroot'] (default=false) 113 $PHPTHUMB_CONFIG['allow_src_above_phpthumb'] (default=true) 114 If your images are outside DOCUMENT_ROOT (this includes if 115 you have an image upload form, most likely the images will 116 get uploaded to "/tmp/<file>" or similar) then you will have 117 to configure 'allow_src_above_docroot' to true. 118 Make sure whatever user the webserver is running as has read 119 permission to the file/directory you're reading from 120 121 122Q: Should I use phpThumb.php, or use phpThumb() as an object? 123A: phpThumb.php is easier to use (less coding) for basic uses. 124 phpThumb.php handles all caching; your own object will need 125 to have its own caching code. If you just want to display a 126 thumbnailed version of an existing image, use phpThumb.php 127 If you want to render one (or more) thumbnails to static 128 files (during upload, for example), that's an appropriate 129 use for the object mode. Also, phpThumb.config.php is only 130 used by phpThumb.php, so if you instantiate your own object 131 you need to manually set all configuration options because 132 phpThumb.config.php has NO effect. So, to repeat: 133 **always use phpThumb.php unless you NEED to have an object** 134 135 136Q: The first time I go to a page which contains thumbnails I 137 don't actually see the thumbnail, I just get a browser image 138 placeholder (or no image). As soon as I hit refresh, all the 139 thumbnail images pop into place really fast. 140A: You can try and see if it works better with 141 $PHPTHUMB_CONFIG['cache_force_passthru'] = false; 142 but typically the default setting works better. 143 Note: There were some maybe-undefined variables prior to 144 v1.7.9 that contributed to this behavior. If you notice 145 this happening in v1.7.9 or newer please email me at 146 info@silisoftware.com 147 148 149Q: Are there any front-end GUI interfaces to phpThumb()? 150A: See /demo/readme.demo.txt 151 152 153Q: Are there / have there been any security issues in phpThumb? 154A: http://secunia.com/product/5199/ 155 156 157Q: Why can't Flash work with images output from phpThumb()? 158A: Flash doesn't like progressive JPEG. Set: 159 $PHPTHUMB_CONFIG['output_interlace'] = false; 160 161 162Q: Image quality is not very good - why? 163A: If you're using GD v1.x, no way around it. Upgrade to GD v2.x 164 165 166Q: Image quality is very bad, very pixelated -- why? 167A: You may be trying to resize images larger than the available 168 PHP memory, so phpThumb is simply extracting and using the 169 EXIF thumbnail as the image source, which is usually about 170 160x120 (so if you resize it to 640x480 it will look very bad). 171 To calculate the required size for memory_limit in php.ini, 172 calculate the number of pixels in the image and multiply by 5: 173 For example, 1600x1200 = 1600 * 1200 * 5 = 9600000 = 10M 174 Easy solution: install ImageMagick 175 176 177Q: Can I save the generated thumbnail to a file? 178A: Yes, there are several ways to do so; the best way is to call 179 phpThumb as an object and call RenderToFile() to save the 180 thumbnail to whatever filename you want. 181 See /demo/phpThumb.demo.object.php for an example. 182 The other way is to use the 'file' parameter (see 183 /docs/phpthumb.readme.txt) but this parameter is deprecated 184 and does not work in phpThumb v1.7.5 and newer. 185 186 187Q: "Off-server thumbnailing is not allowed" -- how do I enable it? 188A: By default, phpThumb() only makes thumbnails for the same 189 domain that it is running on. To allow it to make thumbnails 190 for a limited number of other domains, add them 191 (in phpThumb.config.php) like this: 192 $PHPTHUMB_CONFIG['nohotlink_valid_domains'] = array( 193 @$_SERVER['HTTP_HOST'], 'example.com', 'www.example.com', 194 'subdomain.example.net', 'example.org'); 195 To disable off-server thumbnail blocking, just set: 196 $PHPTHUMB_CONFIG['nohotlink_enabled'] = false; 197 198 199Q: Is it possible to set the parameters (like w/h/fltr[]) in 200 the config, so that they can't be changed over the URL? 201A: Take a look at $PHPTHUMB_DEFAULTS at the bottom of 202 phpThumb.config.php You'll want to set 203 $PHPTHUMB_DEFAULTS_GETSTRINGOVERRIDE = false 204 possibly also 205 $PHPTHUMB_DEFAULTS_DISABLEGETPARAMS = true 206 You may also want to investigate 207 $PHPTHUMB_CONFIG['high_security_enabled'] = true 208 (see the example at the bottom of phpThumb.config.php 209 for how to call images in HighSecurity mode) 210 211 212Q: Is there a way to use phpThumb() object to create thumbnails 213 without the parameters in the URL showing the location of 214 the image etc? 215A: There is a demo in /demo/phpThumb.demo.object.php. You could 216 modify this into your own file, but there still remains the 217 problem of passing parameters to the file, whether it's 218 phpThumb.php or your own instantiation of a phpThumb() object. 219 I would suggest is putting as many of the common parameters 220 into phpThumb.config.php as possible under $PHPTHUMB_DEFAULTS, 221 so you then don't have to pass them for each image. If you 222 don't want people modifying the parameters, turn on 223 $PHPTHUMB_CONFIG['high_security_enabled'] and set a password 224 (you'll need to generate the <img> tags with phpThumbURL() 225 provided at the bottom of phpThumb.config.php). If you don't 226 want people accessing your source images at all, you can 227 place them outside DOCUMENT_ROOT on your server (as long as 228 phpThumb/PHP has read access to the directory). The other 229 option is to put your source images in a MySQL database 230 and set $PHPTHUMB_CONFIG['mysql_query'] and related 231 parameters in phpThumb.config.php to pull your source images 232 from the database. That way it's impossible to retrieve the 233 images except through phpThumb.php, and if high_security is 234 enabled, then nobody can modify the parameters to view 235 anything except what you want to show. So, yes, it's possible 236 to use your own object, but it's probably better to use 237 phpThumb.php if possible -- one notable issue is that 238 phpThumb.php handles all the caching, so you're on your own 239 to deal with that if you create your own object. 240 241 242Q: How do I write the output thumbnail back to a database instead 243 of outputting to the browser or a file? 244A: See /demo/phpThumb.demo.object.php Basically you need to call 245 $this->GenerateThumbnail() then $this->RenderOutput() and then 246 the output raw image data is found in $this->outputImageData 247 248 249Q: phpThumb runs slowly, as if the images aren't cached, when I use HTTP source 250 images (not on my server). How can I make it go faster? 251A: $PHPTHUMB_CONFIG['cache_source_filemtime_ignore_remote'] = true; 252 // if true, remote source images will not be checked for modification date and 253 // cached image will be used if available, even if source image is changed or removed 254 255 256Q: What does the "cache_default_only_suffix" configuration option do? 257A: Cache files are normally created with big ugly names like 258 "phpThumb_cache_www.example.com_src1a482c2c760463795ff18faf073b389f_par3e099041c2f4a73041a7f5d7e7fc481a_dat1119952152.jpeg" 259 but if cache_default_only_suffix is enabled, cache filenames are simplified to 260 "pic_thumb.jpg" (for example). The problem is that only one version of that 261 thumbnail is possible, and you can never call it again with a different size, 262 or different filters, etc. Generally you don't want that enabled, but it's 263 there because some people asked for it. 264 265 266Q: Why is the visual size of rotated images smaller than the unrotated images? 267A: phpThumb fits the rotated image into the 'w' and 'h' dimensions. 268 Try not specifying a 'w' parameter: phpThumb.php?src=file.png&ra=15 269 That should leave the image the apparent same size as the unrotated image 270 (in actual fact the canvas size is enlarged to fit the rotated image in it). 271 272 273Q: phpThumb.demo.check.php says Safe Mode is off for Master but on for Local, 274 and I checked php.ini and it's already set off. How do I disable safe mode? 275A: Your PHP was probably installed as an Apache module. If so, you have to set 276 php_admin_value safe_mode "Off" 277 in your domain settings (usually between <VirtualHost> tags in httpd.conf). 278 Then you have to restart Apache. 279 280 281Q: How can I purge cached files when I delete the source image? 282A: You can either let phpThumb's built-in cache purging features (see phpThumb.config.php) 283 take effect, or you can manually walk through your source images to delete and find 284 the matching cache files and delete them: 285 if ($dh = opendir($sourcedir)) { 286 while ($file = readddir($dh)) { 287 if ($file == $WhatIwantToDelete) { 288 $md5 = md5_file($sourcedir.'/'.$file); 289 unlink($phpthumb_cache_dir.'/phpThumb_cache_www.example.com_src'.$md5.'*.*'); 290 } 291 } 292 closedir($dh); 293 } 294 295 296Q: Is it safe to delete cache files? 297A: Yes, it is safe to delete any cache files and/or directories. phpThumb will 298 automatically re-create them as needed. Also, take a look at the "cache_max*" 299 settings in phpThumb.config.php for automatic cache purging. 300 301 302Q: How can I find the filename that phpThumb.php will use to 303 cache a particular image? 304A: It's not easily possible to get the cache filename. You can 305 see the method used to calculate it in SetCacheFilename() 306 in phpthumb.class.php (around line 2991-3090). If you need 307 to know where an image will be rendered to, it may be 308 easier and better to call phpThumb as an object and handle 309 your own caching. See /demo/phpThumb.demo.object.simple.php 310 for an example. 311 312 313Q: Can I make thumbnails from a PDF? 314A: Yes, as long as you have both ImageMagick and GhostScript 315 installed. The AFPL version of GhostScript seems to work 316 better than the GNU version (at least for me it does). 317 http://www.imagemagick.org 318 http://www.cs.wisc.edu/~ghost/ 319 You may want to use the "sfn" (Source Frame Number) 320 parameter of phpThumb to specify which page to thumbnail. 321 322 323Q: Can I make a thumbnail of a webpage? 324A: Possibly, but it's not easy. Theoretically, if you have 325 html2ps, GhostScript and ImageMagick all installed it should 326 be possible, but I have not tested that. Other projects that 327 attempt to generate thumbnails from webpages include: 328 http://www.boutell.com/webthumb/ 329 330 331Q: When I resize an animated GIF the new "smaller" version is 332 actually a larger file size -- why? 333A: Animated GIFs use a variety of temporal and spatial compression 334 techniques. The source GIF is probably very well optimized, but 335 when each frame is resized some of the desirable compression 336 properties could be negatively affected (the number of colours 337 can increase; dithered areas compress very poorly compared to 338 solid areas of colour). ImageMagick may also not produce the 339 most filesize-optimized animated GIF possible. 340 341 342Q: Can I use source images from (same or another) server that uses 343 a script with parameters to display images? For example: 344 http://sourceforge.net/sflogo.php?group_id=106407&type=5 345 (displays a PNG image, 210x62) 346A: Yes, you should be able to use phpThumb like that no problem. 347 If the source image is on a different server you need to set 348 $PHPTHUMB_CONFIG['nohotlink_valid_domains'] to contain the source 349 domain(s) [eg: sourceforge.net] if it's a small list of possible 350 source domains, or make sure $PHPTHUMB_CONFIG['nohotlink_enabled'] 351 is set to false to allow creating source images from any domain/IP. 352 You will also need to properly encode the image source (using PHP 353 function rawurlencode): 354 /phpThumb.php?src=http%3A%2F%2Fsourceforge.net%2Fsflogo.php%3Fgroup_id%3D106407%26type%3D5&w=100 355 356 357Q: phpThumb is the best software in the world, how can I donate? 358A: There's a handy "Support this project" button at the top of 359 http://phpthumb.sourceforge.net which will take you through 360 the process (and give SourceForge a ~5% cut), or if you prefer 361 you can send PayPal donations directly to info@silisoftware.com 362 363 364Q: What is the proper name for this script/program/library? 365A: The official name is "phpThumb()" but it may be written 366 as simply "phpThumb" in short form (or where parentheses 367 are not permitted), or "phpthumb" in case-insensitive 368 environments. The following is a non-exhaustive sample of 369 unacceptable forms: PHPthumb; phpThumbs; phpthump; 370 phpthumbnailer; phpThumbnail; PHP Thumb; Phpthumb; etc. 371 372 373
