Class for generating image and file previews. More...

Inheritance diagram for ImgPreview:

Public Member Functions
	__construct ($name=false, $parent=null)
	getClone ()
	modify ($options, $clone=null)
	Sets options on preview object.
	__clone ()
	__get ($name)
	__set ($name, $value)
	getPreview ($path, array $options=array())
	Returns image/file preview, generating it if necessary.
	generatePreview ($path, $destination, array $options=array())
	Generates file preview, and saves it in specified place.
	buildResultObject ($path, $options)
	Builds ImgPreviewResult object.
	getPreviewSignature ()
	buildUrl ($path)
	buildPath ($path, $absolute=true)
	preparePreviewInfo ($img)
	Calculates preview information.
	getIcon ($ext)
	Returns absolute path to icon for specified file/extension.
	getIconUrl ($ext)
	getPreviewImage ($path, $width=false, $height=false, $minWidth=false, $minHeight=false, $maxWidth=false, $maxHeight=false, $crop=null, $zoom=null)
Static Public Member Functions
static	instance ($name=self::ID_MAIN, $basedOn=self::ID_MAIN)
static	instanceName ($instanceOrName)
	Returns name of the instance, or the name if it's not an instance.
static	setInstance ($ip)
static	resetInstances ()
static	getInstances ()
static	gotInstance ($name)
static	waitForFile ($file, $timeout)
	Waits for file to show up.
static	handleMissingPreview ($previewFile, $previewUrl, $bootstrap=false, $handleHeaders=true, $timeout=10)
	Should be called in missing thumbs handler.
static	resumePreviewCreationFromOrder ($orderFile)
	Resumes previously ordered preview.
static	getPreviewThumb ($file, $type, $width=false, $height=false, $minWidth=false, $minHeight=false, $maxWidth=false, $maxHeight=false, $crop=null, $zoom=null)
static	getPreviewThumbSrc ($file, $type, $width=false, $height=false, $minWidth=false, $minHeight=false, $maxWidth=false, $maxHeight=false, $crop=null, $zoom=null, $icon=false)
static	getPreviewThumbSrcEx ($file, $data)
Data Fields
const	ID_MAIN = 'main'
const	TYPE_AUTO = "auto"
	Select best type available.
const	TYPE_PREVIEW = "preview"
	Select best type available for preview, but don't return icons, regardless of iconsPath.
const	TYPE_NONE = false
const	TYPE_ICON = "icon"
const	TYPE_PNG = "png"
const	TYPE_JPG = "jpg"
const	TYPE_GIF = "gif"
const	EXT_DIR = "dir"
const	EXT_URL = "url"
const	OPT_RECREATE = "recreate"
const	OPT_PREVIEW_FILE = "previewFile"
const	METHOD_GD = "GD"
const	METHOD_IMAGEMAGICK = "IM"
const	ERROR_TRIGGER = "trigger"
const	ERROR_THROW = "throw"
const	ERROR_NONE = false
	$name = false
	Name of the instance.
	$width
	$height
	$minWidth
	$minHeight
	$maxWidth
	$maxHeight
	$crop = false
	Should image be cropped?
	$zoom = 1
	Zoom in of previews.
	$quality = 75
	Quality to use for previews, from 0 - 100.
	$alignX = 0.5
	Percentage alignment of cropped images - 0 - left, 0.5 - middle, 1 - right.
	$alignY = 0.5
	Percentage alignment of cropped images - 0 - top, 0.5 - middle, 1 - bottom.
	$rootPath = null
	Server's absolute path.
	$previewsPath = null
	Absolute path to previews storage.
	$webPath = "/"
	Url to use, to access rootPath.
	$downloadDir = "download"
	$backgroundScript = 'imgprev.php/'
	$downloadDirSpread = 2
	How many characters from file signature should be used to spread files into subdirectories Positive values will make subdirectories, negative will be stored on first level.
	$previewDirSpread = 1
	How many characters from file signature should be used to spread files into subdirectories Positive values will make subdirectories, negative will be stored on first level.
	$pathReplace = false
	Array of pattern => replacement values.
const	PATH_FORMAT_SEO = '%2$.64s_%1$.8s.%3$s'
	$pathFormat = '%1$.10s_%2$.32s.%3$s'
	Preview path format.
	$pathRemoteFormat = '%1$.14s_%2$.32s.%3$s'
	Downloaded files path format.
	$chmod = null
	chmod to apply to directories and files
	$type = self::TYPE_AUTO
	Default type of previews.
	$iconsPath = "icons/"
	Absolute or relative path to icon files.
	$iconSize
	Icon size (same width & height).
	$iconExtension = ".png"
	$iconUnknown = "unknown"
	$defaultPreview = false
	Absolute or relative path to the image that should be used if no image could be generated.
	$defaultExtension = false
	Default extension if file (or url) has no extension.
	$extensionMap
	Maps extensions to preview types or other extension.
	$allowRemote = true
	Allow downloading of remote files.
	$allowBackground = false
	$allowReuseSameSize = true
	$allowMaxImageSize = 3000000
	maximum safe image size to handle by PHP.
	$allowSubfolders = 2
	Use subfolders when organizing previews 1 - only one subfolder /ID_spread/FILE.jpg 2 - two subfolders /ID/spread/FILE.jpg.
	$allowWait = 0
	How long to wait for images being prepared.
	$allowLeaveFailed = true
	If TRUE, failed previews and downloads will be left as empty files.
	$allowRebuildFailed = false
	If TRUE, failed previews will be rebuilded.
	$previewCreationTimeout = 60
	Temporary files this old will be removed.
	$previewMethod = self::METHOD_GD
	$previewSignature = null
	$errorHandling = self::ERROR_TRIGGER
	$im_command = 'convert'
	ImageMagick convert command to use.
Static Public Attributes
static	$orderSuffix = '.order.tmp'
static	$tempSuffix = '.tmp'
Protected Member Functions
	copySettingsFrom ($parent)
	triggerError ($img, $message, $type=E_USER_NOTICE)
	doMakeDirs ($path, $forceMake=false, $depth=0)
	doChangeMode ($path)
	mapExtension (ImgPreviewResult $img)
	Maps the file's extension to previewType using extensionMap.
	parsePath (ImgPreviewResult $img, &$fileDir, &$fileName, &$pathIsRemote, array &$options)
	Parses image's path and sets basic variables.
	preparePathInfo ($img, array $options=array())
	Fills file information in $result object.
	handleIfSameSize ($img, $allowReuse=true)
	Waits for preview to finish.
	waitForPreview ($img, $timeout)
	Waits for preview to finish.
	resumePreviewCreation ($img)
	Dispatches preview for background creation.
	createPreviewInBackground ($img)
	Dispatches preview for background creation.
	createPreview ($img)
	Builds actual preview.
	createPreview_IM ($img, $filename)
	Builds preview using ImageMagick command line.
	createPreview_GD ($img, $filename)
	Builds actual preview using GD2 library.
Static Protected Attributes
static	$instances = array()
static	$fieldMap

Detailed Description

Class for generating image and file previews.

Supports GD2 and ImageMagick. Works in background, and can generate previews only when they are requested by the browser.

Usage: First, configure some predefined instances.

 // main instance, set some global defaults
 $ip = ImgPreview::instance();
 $ip->previewMethod = ImgPreview::METHOD_IMAGEMAGICK;
 $ip->rootPath = dirname(__FILE__) . '/';
 $ip->previewsPath = $ip->rootPath . 'previews/';
 
 // any new instance will be based on the main one (by copying all settings)
 $ip = ImgPreview::instance('thumb');
 $ip->width = 300;
 $ip->height = 200;

Now use them...

 // using predefined instance
 echo ImgPreview::instance('thumb')->getPreview('file.jpg')->getHtmlImg();
 
 // using modified instance (changes arent applied to named instances!)
 echo ImgPreview::instance('thumb')->modify(array('width' => 100))->getPreview('file.jpg')->getHtmlImg();
 
 // using temporary instances based on main instance
 $ip = new ImgPreview(false, ImgPreview::instance());
 $ip->width = 100;
 echo $ip->getPreview('file.jpg')->getHtmlImg();
 
 // using cloned instances
 $ip = ImgPreview::instance()->getClone();
 $ip->width = 100;
 echo $ip->getPreview('file.jpg')->getHtmlImg();

Constructor & Destructor Documentation

ImgPreview::__construct	(	$	name = `false`,
		$	parent = `null`
	)

Parameters:

ImgPreview $parent - imgPreview object to copy settings from

Reimplemented in KWebImagePreview.

Member Function Documentation

ImgPreview::__clone ( )

ImgPreview::__get ( $ name )

ImgPreview::__set	(	$	name,
		$	value
	)

ImgPreview::buildPath	(	$	path,
		$	absolute = `true`
	)

ImgPreview::buildResultObject	(	$	path,
		$	options
	)

Builds ImgPreviewResult object.

Returns:: ImgPreviewResult

ImgPreview::buildUrl ( $ path )

ImgPreview::copySettingsFrom ( $ parent ) [protected]

ImgPreview::createPreview ( $ img ) [protected]

Builds actual preview.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - something went wrong

ImgPreview::createPreview_GD	(	$	img,
		$	filename
	)		`[protected]`

Builds actual preview using GD2 library.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - something went wrong

ImgPreview::createPreview_IM	(	$	img,
		$	filename
	)		`[protected]`

Builds preview using ImageMagick command line.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - something went wrong

ImgPreview::createPreviewInBackground ( $ img ) [protected]

Dispatches preview for background creation.

Preview will use dynamic urls.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - can't use background creation

ImgPreview::doChangeMode ( $ path ) [protected]

ImgPreview::doMakeDirs	(	$	path,
		$	forceMake = `false`,
		$	depth = `0`
	)		`[protected]`

ImgPreview::generatePreview	(	$	path,
		$	destination,
		array $	options = `array()`
	)

Generates file preview, and saves it in specified place.

Use getPreview() for standard, automatic and cached behaviour.

Warning:: This function won't generate the preview if $destination already exists, unless OPT_RECREATE is passed in options.

Parameters:

$path	Path to the file. Relative to $this->rootPath, absolute (but within rootPath), or any php supported URL for download
$destination	Absolute or relative path to save the preview into
$options	array of special options

Returns:: ImgPreviewResult

ImgPreview::getClone ( )

Returns:: ImgPreview

ImgPreview::getIcon ( $ ext )

Returns absolute path to icon for specified file/extension.

ImgPreview::getIconUrl ( $ ext )

static ImgPreview::getInstances ( ) [static]

ImgPreview::getPreview	(	$	path,
		array $	options = `array()`
	)

Returns image/file preview, generating it if necessary.

Parameters:

$path	Path to the file. Relative to $this->rootPath, absolute (but within rootPath), or any php supported URL for download
$options	array of special options

Returns:: ImgPreviewResult

ImgPreview::getPreviewImage	(	$	path,
		$	width = `false`,
		$	height = `false`,
		$	minWidth = `false`,
		$	minHeight = `false`,
		$	maxWidth = `false`,
		$	maxHeight = `false`,
		$	crop = `null`,
		$	zoom = `null`
	)

Deprecated:

See also:: set()

Returns:: ImgPreviewResult

ImgPreview::getPreviewSignature ( )

static ImgPreview::getPreviewThumb	(	$	file,
		$	type,
		$	width = `false`,
		$	height = `false`,
		$	minWidth = `false`,
		$	minHeight = `false`,
		$	maxWidth = `false`,
		$	maxHeight = `false`,
		$	crop = `null`,
		$	zoom = `null`
	)		`[static]`

Deprecated:

See also:: modify()

static ImgPreview::getPreviewThumbSrc	(	$	file,
		$	type,
		$	width = `false`,
		$	height = `false`,
		$	minWidth = `false`,
		$	minHeight = `false`,
		$	maxWidth = `false`,
		$	maxHeight = `false`,
		$	crop = `null`,
		$	zoom = `null`,
		$	icon = `false`
	)		`[static]`

Deprecated:

See also:: modify()

static ImgPreview::getPreviewThumbSrcEx	(	$	file,
		$	data
	)		`[static]`

Deprecated:

See also:: modify()

static ImgPreview::gotInstance ( $ name ) [static]

ImgPreview::handleIfSameSize	(	$	img,
		$	allowReuse = `true`
	)		`[protected]`

Waits for preview to finish.

Parameters:

ImgPreviewResult $img

Returns:: boolean - TRUE - if file is same size as preview FALSE - otherwise

static ImgPreview::handleMissingPreview	(	$	previewFile,
		$	previewUrl,
		$	bootstrap = `false`,
		$	handleHeaders = `true`,
		$	timeout = `10`
	)		`[static]`

Should be called in missing thumbs handler.

Operation:

if previewFile exists, redirects directly to the file
if previewFile.temp exists, waits for previewFile
- if timeout occurs, 408 timeout is returned
- if it's ready, redirects directly to the file
if previewFile.order exists, bootstraps the environment, resumes creation from order, and redirects directly to the file (or returns 500 if resume have failed)
otherwise returns 404

Parameters:

$previewFile	relative or absolute path to the requested previewFile
$previewUrl	url to redirect to if preview is found
$bootstrap	file to require, or function to run to bootstrap the environment
$handlHeaders	if TRUE, will handle setting of headers

Returns:: preview Url to redirect to, or HTTP error code number

static ImgPreview::instance	(	$	name = `self::ID_MAIN`,
		$	basedOn = `self::ID_MAIN`
	)		`[static]`

Returns:: ImgPreview

Parameters:

$name

Name of new instance, or:

FALSE if it's temporary,
'' or TRUE for default instance (same as self::ID_MAIN)
ImgPreview object - will be returned intact. Can be used to pass instance name/or preview object by the same variable

Reimplemented in KWebImagePreview.

static ImgPreview::instanceName ( $ instanceOrName ) [static]

Returns name of the instance, or the name if it's not an instance.

ImgPreview::mapExtension ( ImgPreviewResult $ img ) [protected]

Maps the file's extension to previewType using extensionMap.

ImgPreview::modify	(	$	options,
		$	clone = `null`
	)

Sets options on preview object.

If it is a named instance, it will create a clone of it.

Parameters:

$options	Hashmap of options to change
$clone	TRUE to always clone instance, FALSE to modify original, NULL to clone only named objects. Defaults to NULL

Warning:: Unless you pass $clone as FALSE, You should always use returned object!

 echo ImgPreview::instance()->modify(array('width'=>100, 'height'=>100))->getPreview($path)->buildImgHtml();

Returns:: ImgPreview

ImgPreview::parsePath	(	ImgPreviewResult $	img,
		&$	fileDir,
		&$	fileName,
		&$	pathIsRemote,
		array &$	options
	)		`[protected]`

Parses image's path and sets basic variables.

ImgPreview::preparePathInfo	(	$	img,
		array $	options = `array()`
	)		`[protected]`

Fills file information in $result object.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE when path is not previewable. If Preview should be generated, $img->sourceFile will containt path to the file to generate it from. If $img->path != $img->sourceFile, than $img->path should be first downloaded to $img->sourceFile

ImgPreview::preparePreviewInfo ( $ img )

Calculates preview information.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - something went wrong

static ImgPreview::resetInstances ( ) [static]

ImgPreview::resumePreviewCreation ( $ img ) [protected]

Dispatches preview for background creation.

Preview will use dynamic urls.

Parameters:

ImgPreviewResult $img

Returns:: boolean - FALSE - can't use background creation

static ImgPreview::resumePreviewCreationFromOrder ( $ orderFile ) [static]

Resumes previously ordered preview.

Calling function should first ensure, that there is nothing being currently generated!

Returns:: ImgPreviewResult

static ImgPreview::setInstance ( $ ip ) [static]

Parameters:

$ip	ImgPreview

ImgPreview::triggerError	(	$	img,
		$	message,
		$	type = `E_USER_NOTICE`
	)		`[protected]`

Parameters:

ImgPreviewResult $img

static ImgPreview::waitForFile	(	$	file,
		$	timeout
	)		`[static]`

Waits for file to show up.

Parameters:

ImgPreviewResult	$img
	$timeout	how long to wait (in seconds)

Returns:: boolean - TRUE - if file is ready, FALSE if timeout has been reached

ImgPreview::waitForPreview	(	$	img,
		$	timeout
	)		`[protected]`

Waits for preview to finish.

Parameters:

ImgPreviewResult	$img
	$timeout	how long to wait (in seconds)

Returns:: boolean - TRUE - if file is ready ($img->isReady() will be true), or timeout has been reached ($img->isReady() will be false) FALSE - there is nothing to wait for...

Field Documentation

ImgPreview::$alignX = 0.5

Percentage alignment of cropped images - 0 - left, 0.5 - middle, 1 - right.

ImgPreview::$alignY = 0.5

Percentage alignment of cropped images - 0 - top, 0.5 - middle, 1 - bottom.

ImgPreview::$allowBackground = false

ImgPreview::$allowLeaveFailed = true

If TRUE, failed previews and downloads will be left as empty files.

ImgPreview::$allowMaxImageSize = 3000000

maximum safe image size to handle by PHP.

Imagemagick doesn't have a limit

ImgPreview::$allowRebuildFailed = false

If TRUE, failed previews will be rebuilded.

ImgPreview::$allowRemote = true

Allow downloading of remote files.

ImgPreview::$allowReuseSameSize = true

ImgPreview::$allowSubfolders = 2

Use subfolders when organizing previews 1 - only one subfolder /ID_spread/FILE.jpg 2 - two subfolders /ID/spread/FILE.jpg.

ImgPreview::$allowWait = 0

How long to wait for images being prepared.

ImgPreview::$backgroundScript = 'imgprev.php/'

ImgPreview::$chmod = null

chmod to apply to directories and files

ImgPreview::$crop = false

Should image be cropped?

ImgPreview::$defaultExtension = false

Default extension if file (or url) has no extension.

ImgPreview::$defaultPreview = false

Absolute or relative path to the image that should be used if no image could be generated.

This image will be handled by subquery, and will be resized...

Warning:: For failed remote files prepared in background, default image won't be used!

ImgPreview::$downloadDir = "download"

ImgPreview::$downloadDirSpread = 2

How many characters from file signature should be used to spread files into subdirectories Positive values will make subdirectories, negative will be stored on first level.

ImgPreview::$errorHandling = self::ERROR_TRIGGER

ImgPreview::$extensionMap

Initial value:

 array(
  'jpg' => self::TYPE_JPG,
  'jpeg' => '.jpg',
  'png' => self::TYPE_PNG,
  'gif' => self::TYPE_GIF,
 )

Maps extensions to preview types or other extension.

To map to extension use ".extension"

ImgPreview::$fieldMap [static, protected]

Initial value:

 array(
  'prevMake' => '',
  'prevSig' => '',
  'prevRebuild' => '',
  'isInset' => '',
  'prevPath' => 'previewsPath',
  'prevWidth' => 'width',
  'prevHeight' => 'height',
  'prevMinWidth' => 'minWidth',
  'prevMinHeight' => 'minHeight',
  'prevMaxWidth' => 'maxWidth',
  'prevMaxHeight' => 'maxHeight',
  'prevQuality' => 'quality',
  'useSubFolders' => 'allowSubfolders',
  'maxSafeImageSize' => 'allowMaxImageSize',
 )

ImgPreview::$height

ImgPreview::$iconExtension = ".png"

ImgPreview::$iconSize

Icon size (same width & height).

If specified, it will be appended to $iconsPath

ImgPreview::$iconsPath = "icons/"

Absolute or relative path to icon files.

ImgPreview::$iconUnknown = "unknown"

ImgPreview::$im_command = 'convert'

ImageMagick convert command to use.

ImgPreview::$instances = array() [static, protected]

ImgPreview::$maxHeight

ImgPreview::$maxWidth

ImgPreview::$minHeight

ImgPreview::$minWidth

ImgPreview::$name = false

Name of the instance.

ImgPreview::$orderSuffix = '.order.tmp' [static]

ImgPreview::$pathFormat = '%1$.10s_%2$.32s.%3$s'

Preview path format.

Formatted with parameters (fileSignature, fileName, extension) Better SEO alternative is: '%2$.64s_%1$.8s.%3$s'

ImgPreview::$pathRemoteFormat = '%1$.14s_%2$.32s.%3$s'

Downloaded files path format.

Formatted with parameters (fileSignature, fileName, extension) Better SEO alternative is: '%2$.64s_%1$.8s.%3$s'

ImgPreview::$pathReplace = false

Array of pattern => replacement values.

Preview paths passed to getPreview will be preg_replaced through this list. This allows to translate paths, strip unwanted information, map specific domains to local files and so on...

ImgPreview::$previewCreationTimeout = 60

Temporary files this old will be removed.

ImgPreview::$previewDirSpread = 1

How many characters from file signature should be used to spread files into subdirectories Positive values will make subdirectories, negative will be stored on first level.

ImgPreview::$previewMethod = self::METHOD_GD

ImgPreview::$previewSignature = null

ImgPreview::$previewsPath = null

Absolute path to previews storage.

ImgPreview::$quality = 75

Quality to use for previews, from 0 - 100.

ImgPreview::$rootPath = null

Server's absolute path.

Absolute paths should be below this level, relative paths will be based on this path. Must be suffixed with '/'

ImgPreview::$tempSuffix = '.tmp' [static]

ImgPreview::$type = self::TYPE_AUTO

Default type of previews.