eZPublish  3.8
eZImageManager Class Reference

Manages image operations using delegates to do the work. More...

Public Member Functions

 alias ($aliasName)
 
 aliasList ()
 
 appendConversionRule ($conversionRule)
 
 appendImageAlias ($alias)
 
 appendImageHandler (&$handler)
 
 appendMIMETypeSetting ($settings)
 
 appendQualityValue ($mimeType, $qualityValue)
 
 appendSupportedFormat ($mimeName)
 
 conversionRules ()
 
 convert ($sourceMimeData, &$destinationMimeData, $aliasName=false, $parameters=array())
 
 createAliasFromINI ($iniGroup)
 
 createFilterDataFromINI ($filterText)
 
 createImageAlias ($aliasName, &$existingAliasList, $parameters=array())
 
 createImageAliasKey ($alias)
 
 eZImageManager ()
 
factoryFor ($factoryName, $iniFile=false)
 
 hasAlias ($aliasName)
 
 hasMIMETypeSetting ($mimeData)
 
instance ()
 
 isFilterAllowed ($filterName, $mimeData)
 
 isFilterSupported ($filterName)
 
 isImageAliasValid ($alias)
 
 isImageTimestampValid ($timestamp)
 
 mimeTypeFilters ($mimeData)
 
 mimeTypeOverride ($mimeData)
 
 mimeTypeSetting ($mimeData)
 
 qualityValue ($mimeType)
 
 readConversionRuleSettingsFromINI ($iniFile=false)
 
 readImageAliasesFromINI ($iniFile=false)
 
 readImageHandlersFromINI ($iniFile=false)
 
 readINISettings ()
 
 readMIMETypeQualitySettingFromINI ($iniFile=false)
 
 readMIMETypeSettingFromINI ($mimeGroup, $iniFile=false)
 
 readMIMETypeSettingsFromINI ($iniFile=false)
 
 readSupportedFormatsFromINI ($iniFile=false)
 
 setSupportedFormats ($mimeList)
 
 temporaryImageDirPath ()
 
 wildcardToRegexp ($wildcard, $separatorCharacter=false)
 

Static Public Member Functions

 analyzeImage (&$mimeData, $parameters=array())
 

Private Attributes

 $DefaultRule
 
 $ImageHandlers
 
 $MIMETypes
 
 $OutputMIME
 
 $OutputMIMEMap
 
 $RuleMap
 
 $Rules
 
 $Types = array()
 

Detailed Description

Manages image operations using delegates to do the work.

The manager allows for transparent conversion of one image format to another. The conversion may be done in one step if the required conversion type is available or it may build a tree of conversion rules which is needed to reach the desired end format.

It's also possible to run operations on images. It's up to each conversion rule to report whether or not the operation is supported, the manager will then distribute the operations on the available rules which can handle them. Examples of operations are scaling and grayscale.

The scale operation is special and is known to the manager directly while the other operations must be recognized by the converter.

In determing what image rules to be used the manager must first know which output types are allowed, this is set with setOutputTypes(). It takes an array of mimetypes which are allowed.

The manager must then be fed conversion rules, these tell which conversion type is used for converting from the source mimetype to the destination mimetype. The rules are set with setRules() which accepts an array of rules and a default rule as paremeter. The default rule is used when no other mimetype match is found. To create a rule you should use the createRule() function, it takes the source and destination mimetype as well as the conversion type name. Optionally it can specified whether the rule can scale or run operations.

The last thing that needs to be done is to specify the mimetypes. The manager uses mimetypes internally to know what type of image it's working on. To go from a filename to a mimetype a set of matches must be setup. The matches are created with createMIMEType() which takes the mimetype, regex filename match and suffix as parameter. The mimetypes are then registered with setMIMETypes().

See www.iana.org for information on MIME types.

Now the manager is ready and you can convert images with convert().

Example:

$img->registerType( "convert", new eZImageShell( '', "convert", array(), array(),
array( eZImageShell::createRule( "-geometry %wx%h>", // Scale rule
"modify/scale" ),
eZImageShell::createRule( "-colorspace GRAY", // Grayscale rule
"colorspace/gray" ) ) ) ); // Register shell program convert
$img->registerType( "gd", new eZImageGD() ); // Register PHP converter GD
$img->setOutputTypes( array( "image/jpeg",
"image/png" ) ); // We only want jpeg and png, gif is not recommended due to licencing issues.
$rules = array( $img->createRule( "image/jpeg", "image/jpeg", "GD", true, false ), // Required for scaling jpeg images
$img->createRule( "image/gif", "image/png", "convert", true, false ) ); // Convert GIF to png
$img->setRules( $rules, $img->createRule( "*", "image/png", "convert", true, false ) ); // Convert all other images to PNG with convert
$mime_rules = array( $img->createMIMEType( "image/jpeg", "\.jpe?g$", "jpg" ),
$img->createMIMEType( "image/png", "\.png$", "png" ),
$img->createMIMEType( "image/gif", "\.gif$", "gif" ) );
$img->setMIMETypes( $mime_rules ); // Register mimetypes
$img1 = $img->convert( "image1.gif", "cache/" ); // Convert GIF and places it in cache dir
$img1 = $img->convert( "image1.png", "cache/", // Scale PNG image and place in cache dir
array( "width" => 200, "height" => 200 ), // Scale parameter
array( array( "rule-type" => "colorspace/gray" ) ) ); // Gray scale conversion

Member Function Documentation

eZImageManager::alias (   $aliasName)
Returns
the definition for the Image Alias named $aliasName.

Referenced by createImageAliasKey().

eZImageManager::aliasList ( )

Returns a list of defined image aliases in the image system. Each entry in the list is an associative array with the following keys:

  • name - The name of the alias
  • reference - The name of the alias it refers to or false if no reference
  • mime_type - Controls which MIME-Type the alias will be in, or false if not defined.
  • filters - An array with filters which applies to this alias
  • alias_key - The CRC key for this alias, it is created from the current values of the alias and will change each time the alias values changes

Referenced by alias(), convert(), createImageAlias(), and hasAlias().

eZImageManager::analyzeImage ( $mimeData,
  $parameters = array() 
)
static

Analyzes the image in the MIME structure $mimeData and fills in extra information if found.

Returns
true if the image was succesfully analyzed, false otherwise.
Note
It will return true if there is no analyzer for the image type.

Referenced by convert().

eZImageManager::appendConversionRule (   $conversionRule)

Appends a new global conversion rule.

Referenced by readConversionRuleSettingsFromINI().

eZImageManager::appendImageAlias (   $alias)

Appends the image alias $alias to the list of defined aliases.

Referenced by readImageAliasesFromINI().

eZImageManager::appendImageHandler ( $handler)

Appends the image handler $handler to the list of known handlers in the image system. Onces it is added the supported image filters for that handler is extracted.

Note
If the handler is not available (isAvailable()) it will not be added.

Referenced by readImageHandlersFromINI().

eZImageManager::appendMIMETypeSetting (   $settings)

Appends the MIME-Type setting $settings to the image system.

Referenced by readMIMETypeSettingsFromINI().

eZImageManager::appendQualityValue (   $mimeType,
  $qualityValue 
)

Binds the quality value $qualityValue to the MIME-Type $mimeType.

Referenced by readMIMETypeQualitySettingFromINI().

eZImageManager::appendSupportedFormat (   $mimeName)

Sets which MIME-Types are allowed to use for destination format, this is an array of MIME-Type names. e.g.

$manager->setOutputTypes( array( 'image/jpeg', 'image/gif' ) );

Referenced by readSupportedFormatsFromINI().

eZImageManager::conversionRules ( )
Returns
The global conversion rules.
eZImageManager::convert (   $sourceMimeData,
$destinationMimeData,
  $aliasName = false,
  $parameters = array() 
)

Converts the source image $sourceMimeData into the destination image $destinationMimeData. The source image can be supplied with the full path to the image instead of the MIME structure. The destination image can be supplied with full path or dirpath to the destination image instead of the MIME structure.

Parameters
$aliasNamedetermines the Image Alias to use for conversion, this usually adds some filters to the conversion.

Referenced by createImageAlias().

eZImageManager::createAliasFromINI (   $iniGroup)

Parses the INI group $iniGroup and creates an Image Alias from it.

Returns
the Image Alias structure.

Referenced by readImageAliasesFromINI().

eZImageManager::createFilterDataFromINI (   $filterText)

Parses the filter text $filterText which is taken from an INI file and returns a filter data structure for it.

Referenced by createAliasFromINI(), and readMIMETypeSettingFromINI().

eZImageManager::createImageAlias (   $aliasName,
$existingAliasList,
  $parameters = array() 
)

Makes sure the Image Alias $aliasName is created. It will check if referenced image aliases exists and if not create those also.

Returns
true if successful
eZImageManager::createImageAliasKey (   $alias)

Creates a unique key for the image alias and returns it.

Note
The key is an MD5 of the alias settings and is used to determine if alias settings has changed.

Referenced by aliasList(), and appendImageAlias().

eZImageManager::eZImageManager ( )

Initializes the manager by registering a application/octet-stream mimetype which is applied for all unknown files.

Referenced by instance().

& eZImageManager::factoryFor (   $factoryName,
  $iniFile = false 
)

Finds the image handler factory with the name $factoryName and returns it.

Parameters
$iniFileThe INI file to read from or if false use 'image.ini'

Referenced by readImageHandlersFromINI().

eZImageManager::hasAlias (   $aliasName)
Returns
true if the image alias $aliasName exists.

Referenced by createImageAlias().

eZImageManager::hasMIMETypeSetting (   $mimeData)
Returns
true if the MIME-Type defined in $mimeData exists in the image system.

Referenced by isFilterAllowed(), mimeTypeFilters(), and mimeTypeOverride().

& eZImageManager::instance ( )

Returns the only instance of the image manager.

Referenced by imageInit().

eZImageManager::isFilterAllowed (   $filterName,
  $mimeData 
)
Returns
true if the filtername $filtername is allowed to be used on the type defined in $mimeData.

Referenced by convert().

eZImageManager::isFilterSupported (   $filterName)
Returns
true if the filtername $filtername is supported by any of the image handlers.

Referenced by convert().

eZImageManager::isImageAliasValid (   $alias)
Returns
true if the Image Alias $alias is valid for use. This is tested by checking the key against the key for current Image Alias settings.
eZImageManager::isImageTimestampValid (   $timestamp)
Returns
true if the timestamp $timestamp is newer than the image alias expiry timestamp. The image alias expiry timestamp will be set whenever the image aliases must be recreated.
Note
Normally the expiry timestamp is not set.

Referenced by isImageAliasValid().

eZImageManager::mimeTypeFilters (   $mimeData)
Returns
An array with extra filters for the MIME-Type defined in $mimeData or false if no filters.

Referenced by convert().

eZImageManager::mimeTypeOverride (   $mimeData)
Returns
The override MIME-Type for the MIME structure $mimeData or false if no override.

Referenced by convert().

eZImageManager::mimeTypeSetting (   $mimeData)
Returns
The setting for the MIME-Type defined in $mimeData.

Referenced by isFilterAllowed(), mimeTypeFilters(), and mimeTypeOverride().

eZImageManager::qualityValue (   $mimeType)
Returns
the quality value for MIME-Type $mimeType or false if none exists.
eZImageManager::readConversionRuleSettingsFromINI (   $iniFile = false)

Reads in global conversion rules from INI file.

Referenced by readINISettings().

eZImageManager::readImageAliasesFromINI (   $iniFile = false)

Reads all image aliases from the INI file 'image.ini' and appends them to the image system.

Parameters
$iniFileThe INI file to read from or if false use 'image.ini'

Referenced by readINISettings().

eZImageManager::readImageHandlersFromINI (   $iniFile = false)

Reads all settings for image handlers from the INI file 'image.ini' and appends them to the image system.

Parameters
$iniFileThe INI file to read from or if false use 'image.ini'

Referenced by readINISettings().

eZImageManager::readINISettings ( )

Will read in all required INI settings.

eZImageManager::readMIMETypeQualitySettingFromINI (   $iniFile = false)

Reads MIME-Type quality settings and appends them.

Referenced by readINISettings().

eZImageManager::readMIMETypeSettingFromINI (   $mimeGroup,
  $iniFile = false 
)

Reads a single MIME-Type setting from the INI file 'image.ini' and appends them to the image system.

Parameters
$mimeGroupWhich INI group to read settings from.
$iniFileThe INI file to read from or if false use 'image.ini'
Returns
The settings that were read.

Referenced by readMIMETypeSettingsFromINI().

eZImageManager::readMIMETypeSettingsFromINI (   $iniFile = false)

Reads all MIME-Type settings from the INI file 'image.ini' and appends them to the image system.

Parameters
$iniFileThe INI file to read from or if false use 'image.ini'

Referenced by readINISettings().

eZImageManager::readSupportedFormatsFromINI (   $iniFile = false)

Reads all supported image formats from the INI file 'image.ini' and appends them to the image system.

Parameters
$iniFileThe INI file to read from or if false use 'image.ini'

Referenced by readINISettings().

eZImageManager::setSupportedFormats (   $mimeList)

Sets which MIME-Types are allowed to use for destination format, this is an array of MIME-Type names. e.g.

$manager->setOutputTypes( array( 'image/jpeg', 'image/gif' ) );
eZImageManager::temporaryImageDirPath ( )
Returns
the path for temporary images.
Note
The default value uses the temporary directory setting from site.ini.

Referenced by convert().

eZImageManager::wildcardToRegexp (   $wildcard,
  $separatorCharacter = false 
)

Calls eZImageHandler::wildcardToRegexp() to generate a regular expression out of the wilcard and return it.

Referenced by isFilterAllowed().

Member Data Documentation

eZImageManager::$DefaultRule
private
eZImageManager::$ImageHandlers
private

Referenced by convert().

eZImageManager::$MIMETypes
private
eZImageManager::$OutputMIME
private
eZImageManager::$OutputMIMEMap
private
eZImageManager::$RuleMap
private
eZImageManager::$Rules
private
eZImageManager::$Types = array()
private

The documentation for this class was generated from the following file: