eZPublish  4.5
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())
 Converts the source image $sourceMimeData into the destination image $destinationMimeData. More...
 
 createAliasFromINI ($iniGroup)
 
 createFilterDataFromINI ($filterText)
 
 createImageAlias ($aliasName, &$existingAliasList, $parameters=array())
 Creates the image alias $aliasName if it's not already part of the existing aliases. More...
 
 createImageAliasKey ($alias)
 
 eZImageManager ()
 Singleton instance of eZImageManager used by eZImageManager::instance() Reset with eZImageManager::resetInstance(). More...
 
 factoryFor ($factoryName, $iniFile=false, $converterName=false)
 
 hasAlias ($aliasName)
 
 hasMIMETypeSetting ($mimeData)
 
 imageAliasInfo ($mimeData, $aliasName, $isAliasNew=false)
 Image information for $aliasName. More...
 
 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 ()
 

Static Public Member Functions

static analyzeImage (&$mimeData, $parameters=array())
 
static factory ()
 Returns a shared instance of the eZImageManager class and makes it ready for use. More...
 
static instance ()
 Returns a shared instance of the eZImageManager class. More...
 
static resetInstance ()
 Reset a shared instance of the eZImageManager class and factory variable. More...
 
static wildcardToRegexp ($wildcard, $separatorCharacter=false)
 

Public Attributes

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

Static Protected Attributes

static $factory = false
 
static $instance
 

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(), hasAlias(), and imageAliasInfo().

static 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(), and imageAliasInfo().

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.

Parameters
mixed$sourceMimeDataSource image, either a mimedata array or the source image path
mixed$destinationMimeDataEither a mimedata array or the target image path
mixed$aliasNameTarget alias (small, medium, large...)
array$parametersOptional parameters. Known ones so far: (basename)
Returns
bool

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() 
)

Creates the image alias $aliasName if it's not already part of the existing aliases.

Parameters
string$aliasNameName of the alias to create
array$existingAliasListReference to the current alias list. The created alias will be added to the list.
array$parametersOptional array that can be used to specify the image's basename
Returns
bool true if the alias was created, false if it wasn't

at first, destinationMimeData (mimedata for the alias we're generating) is the same as sourceMimeData. It will evolve as alias generation goes on

Concurrency protection startCacheGeneration will return true if the file is not already being generated by another process. If it is, it will return the maximum time before the generating process enters generation timeout

At this point, we consider that the image exists and destinationMimeData has been filled with the proper information

If we were locked during alias generation, we need to recreate this structure so that the image can actually be used, but ONLY if it was the same alias... sounds like a HUGE mess.

Can we reload the alias list somehow ?

we may want to fetch a unique name here, since we won't use the data for anything else

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().

null eZImageManager::eZImageManager ( )

Singleton instance of eZImageManager used by eZImageManager::instance() Reset with eZImageManager::resetInstance().

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

eZImageManager::factoryFor (   $factoryName,
  $iniFile = false,
  $converterName = 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::imageAliasInfo (   $mimeData,
  $aliasName,
  $isAliasNew = false 
)

Image information for $aliasName.

This is the information which normally would be provided during generation of aliasName. This so that requests not holding the lock will provide meaningful information.

Parameters
mixed$mimeData
string$aliasName
Returns
array
static eZImageManager::instance ( )
static

Returns a shared instance of the eZImageManager class.

Note: In most cases you'd want to use self:factory() instead.

Returns
eZImageManager
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().

static eZImageManager::resetInstance ( )
static

Reset a shared instance of the eZImageManager class and factory variable.

As used by eZImageManager::instance() and eZImageManager::factory()

Since
4.3
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().

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

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

Referenced by isFilterAllowed().

Member Data Documentation

eZImageManager::$DefaultRule
eZImageManager::$factory = false
staticprotected
eZImageManager::$ImageHandlers

Referenced by convert().

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

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