SourceForge.net LogoPHPGallue
[ class tree: libgallue ] [ index: libgallue ] [ all elements ]
Packages:
gallue
libbase
libgallue
remotegallue
setup


Files:
blobs.inc.php
category.inc.php
comment.inc.php
defines.inc.php
film.inc.php
GALGallueTable.inc.php
gallery.inc.php
group.inc.php
help.inc.php
image.inc.php
img.php
instance.inc.php
job.inc.php
locations.inc.php
login.inc.php
node.inc.php
package.inc.php
series.inc.php
token.inc.php
translations.inc.php
user.inc.php

Classes:
GALBlob
GALCategories
GALCategory
GALCategoryIterator
GALComment
GALCommentIterator
GALComments
GALFilm
GALFilmIterator
GALFilms
GALGallery
GALGallueTable
GALGroup
GALGroupIterator
GALGroups
GALHelp
GALHelpIterator
GALHelps
GALImage
GALImageIterator
GALImages
GALInstance
GALInstanceIterator
GALInstances
GALJob
GALJobIterator
GALJobs
GALLogin
GALLoginIterator
GALLogins
GALNode
GALNodeIterator
GALNodes
GALPackage
GALSeries
GALSeriesIterator
GALSeriesT
GALToken
GALTokenIterator
GALTokens
GALUser
GALUserIterator
GALUsers
GAL_EGallery
exceptions
   GAL_EBlob
   GAL_ECategory
   GAL_EComment
   GAL_EFilm
   GAL_EGallue
   GAL_EGroup
   GAL_EHelp
   GAL_EImage
   GAL_EInstance
   GAL_EJob
   GAL_ELogin
   GAL_ENode
   GAL_EPackage
   GAL_ESeries
   GAL_EToken
   GAL_EUser

Class: GALImage

Source Location: /libgallue/image.inc.php

Class Overview

GALRow
   |
   --GALTableRow
      |
      --GALImage

Provide information about an image's content and association with other objects inside the gallery.


Author(s):

Variables

Methods

Inherited Variables

Class: GALTableRow

GALTableRow::$_key
GALTableRow::$_table

Class: GALRow

GALRow::$_data
GALRow::$_dead
GALRow::$_result

Inherited Methods

Class: GALTableRow

GALTableRow::__construct()
Initializes this object.
GALTableRow::delete()
Deletes this row from the database.
GALTableRow::getParent()
Returns the top level parent of this row.
GALTableRow::set()
Sets the specified field of this row to the specified value.
GALTableRow::__set()
Magic method to set a field of this row almost like a native PHP property.

Class: GALRow

GALRow::__construct()
Initializes a row.
GALRow::countFields()
Returns the number of fields contained in a result.
GALRow::get()
Returns the value of a field.
GALRow::getData()
Provides access to the stored data.
GALRow::getFields()
Returns all fields contained in this result.
GALRow::getFlags()
Gets the flags of the given field.
GALRow::getLength()
Gets the length of the given field.
GALRow::getParent()
Returns the top level parent of an entity.
GALRow::getTable()
Gets the name of the table the given field is contained in.
GALRow::getType()
Gets the type of the given field.
GALRow::isField()
Checks if the given field is contained in a result.
GALRow::__destruct()
Deletes the stored data and sets $_dead to TRUE.
GALRow::__get()
Magic method to access this row's fields like native PHP properties.

Class Details

[line 467]
Provide information about an image's content and association with other objects inside the gallery.

A GALImage provides access to information like title and commentary text, and informs about and creates associations with other gallery objects like membership in categories or user comments made about the image. Information about image data are kept in associated GALInstance objects, so multiple formats and resolutions are possible for one image.

This class provides various properties accessed via the magic methods GALImage::__get() and GALImage::__set(). Some of these properties correspond to database fields, some do not. The __get() and __set() methods internally use the GALImage::get() and GALImage::set() methods which provide access control - in contrast to the parent class's GALRow::get() and GALTableRow::set() methods. After performing the access control, these are used to read and write the properties corresponding to database fields. All properties corresponding to database fields are of type string, but instead database types are given here. (r indicates readable, w writable)

  1. Properties corresponding to database fields:
  • INTEGER UNSIGNED imageID r The image's numerical ID, the image table's primary key.
  • INTEGER UNSIGNED seriesID r The ID of the GALSeries the image belongs to. Foreign key field from Series.seriesID.
  • INTEGER UNSIGNED filmID r The ID of the GALFilm the image belongs to. Foreign key field from Films.filmID.
  • INTEGER UNSIGNED ownerID r The ID of the GALUser the image belongs to. Foreign key field from Users.ownerID.
  • INTEGER changeDate rw The UNIX timestamp of the moment the image was changed the last time.
  • INTEGER createDate rw The UNIX timestamp of the moment the image was created.
  • INTEGER tag rw A value that has no fixed meaning. It might be used to organize items beyond the structure of libgallue.
  • TINYINT permission rw The image's access permission, one of GAL_PERMISSION_LOCKED, GAL_PERMISSION_PRIVATE, GAL_PERMISSION_PROTECTED, GAL_PERMISSION_PUBLIC.
  • BOOL trashFlag rw Indicates if the image is "inside the trash bin".
  • BOOL visibleFlag rw Indicates if the image is visible.
  • BOOL uploadFlag rw Indicates if the image's data are currently processed.
  • BOOL selectFlag rw Indicates if the image is "selected" by it's owner; this property isn't used by libgallery.
  • INTEGER sortHint rw Used to determine the default ordering.
  • VARCHAR(255) title rw The image's title.
  • MEDIUMTEXT comment rw The image's commentary text.
  • ENUM ('ltr', 'rtl') direction rw The text direction.
  • VARCHAR(255) oldFileName rw The image's original filename, you might use the information provided with uploaded images or whatever you like.
  • TEXT copyright rw Copyright information about the image. It's enough space (64 kB) there to store whole licenses...
  • VARCHAR(255) annotation rw Text that is inserted in the image data on converting. Changing this causes reconverting!
  • INTEGER score rw libgallery inculdes voting support, see GALImage::vote().
  • INTEGER voteCount rw libgallery inculdes voting support, see GALImage::vote().
  • TEXT additionalInfo r This will be used in a future release to provide user-defined fields, for example EXIF data or location information. Left blank in this release.
2. Properties generated using database fields
  • GALSeries series (from seriesID) rw The series the image belongs to.
  • GALFilm film (from filmID) rw The film the image belongs to.
  • GALUser owner (from ownerID) r The user the image belongs to.
3. Properties not corresponding to database fields.
  • categories r New iterator on all categories the image is member of (see GALCategory).
  • groups r New iterator on all groups the image is member of (see GALGroup).
  • instances r New iterator on this image's instances (see GALInstance).
  • jobs r New iterator on all pending or currently processed jobs associated with this image (see GALJob).
  • comments r New iterator on all user comments made about this image (see GALComment).
The properties of the third kind are all iterators, so before working with them, you have to store them in a local variable.

This is bad and doesn't work:

  1.  while ($instance = $image->instances->fetch()) {...} 
It will loop forever because it always fetches the first element of a newly created iterator!

This is correct:

  1.  $instances = $image->instances;
  2.  while ($instance = $instances->fetch()) {...}

It is to be considered if one should provide these iterators with methods like getCategoriesIterator() and so on to make this clear.

Note that all "real" properties (called object variables in the following) start with an underscore so that they do not interfere with properties accessed using __get() and __set().




Tags:

todo:  Meditate about iterators: Hand them out via property or via method?
todo:  Implement additionalInfo.


[ Top ]

Class Variables

$_categories =  false

[line 481]

Cache category membership.

The first time the categories property is accessed, this object variable is initialized with a GALCategoryIterator on all categories this image belongs to. All requests for the category property then just return a new iterator on this variable.




Tags:

access:  protected
see:  GALResultIterator::iterator()

Type:   mixed


[ Top ]

$_comments =  false

[line 521]

Cache user comments about this image.

The first time the comments property is accessed, this object variable is initialized with a GALCommentIterator on all user comments about this image. All requests for the comments property then just return a new iterator on this variable.




Tags:

access:  protected
see:  GALResultIterator::iterator()

Type:   mixed


[ Top ]

$_glb =  false

[line 471]

Link to GALGallery object



Tags:

access:  protected

Type:   mixed


[ Top ]

$_groups =  false

[line 491]

Cache group membership.

The first time the groups property is accessed, this object variable is initialized with a GALGroupIterator on all groups this image belongs to. All requests for the group property then just return a new iterator on this variable.




Tags:

access:  protected
see:  GALResultIterator::iterator()

Type:   mixed


[ Top ]

$_instances =  false

[line 501]

Cache the image's instances.

The first time the instances property is accessed, this object variable is initialized with a GALInstanceIterator on all the image's instances. All requests for the instances property then just return a new iterator on this variable.




Tags:

access:  protected
see:  GALResultIterator::iterator()

Type:   mixed


[ Top ]

$_jobs =  false

[line 511]

Cache the jobs associated to this image.

The first time the jobs property is accessed, this object variable is initialized with a GALJobIterator on all jobs associated to this image. All requests for the jobs property then just return a new iterator on this variable.




Tags:

access:  protected
see:  ResultIterator::iterator()

Type:   mixed


[ Top ]


Class Methods

constructor __construct [line 531]

GALImage __construct( GALGallery $glb, $result, &$data, $table, array $data)

Initialize This constructor is not intended to be called by library users, it is called inside GALImageIterator::fetch().



Overrides GALTableRow::__construct() (Initializes this object.)

Parameters:

GALGallery   $glb   Used to initialize the GALImage::$_glb object variable.
GALResult   $result   Used in parent constructor GALTableRow::__construct().
array   $data   Used in parent constructor GALTableRow::__construct().
GALTable   $table   Used in parent constructor GALTableRow::__construct().
   &$data  

[ Top ]

method addInstance [line 1275]

void addInstance( array $values, [bool $super = false])

Add a new Instance to this image.

This method creates a new job (see GALJob) and then starts processJobs that processes the job in the background. Therefor the new instance doesn't exist at the moment this method has finished, but when the background process has finished. When creating an image, by default an Instance with instanceID=IMG_RAW is added which contains the image's raw data. If you want to use these raw data as source file, just omit $values['path'] (recommended). This will save you a lot of hassle with files hanging around belonging to no one. The parameter $values is an associative array with the following fields:

  • $values['x'] int optional The new instance's maximum width, default: read config data.
  • $values['y'] int optional The new instance's maximum height, default: read config data.
  • $values['permission'] int optional The new instance's permission, values GAL_PERMISSION_PRIVATE, GAL_PERMISSION_PROTECTED or GAL_PERMISSION_PUBLIC. Default: The image's permission.
  • $values['mimeType'] string optional The new instance's mimeType property, default: Type is guessed using the file program after converting.
  • $values['extension'] string optional The new instance's file extension (without dot, like 'jpeg'; default: info read from config).
  • $values['annotation'] string optional A text that is inserted into the image (for example copyright information).
  • $values['rotate'] int optional Rotate the instance (possible values are 0, 90, 180, 270, direction ccw)
  • $values['options'] string optional Options passed to the conversion process. Not implemented yet.
  • $values['instanceID'] int optional The new instance's instanceID. If an instance with the specified instanceID already exists, it is overwritten. If not specified, a free instanceID bigger than IMG_USER is chosen.
  • $values['blob'] GALBlob optional Source data for creating the new instance. By default the blob of this image's raw instance is chosen.
You can only obmit the 'x' and 'y' values, if the requested instance is notified in the configuration. The handling of config data is still "ugly", I guess I will change sth here later.




Parameters:

array   $values   Array with data for image creation.
bool   $super   If TRUE, override permission checks.

[ Top ]

method addToCategory [line 1147]

void addToCategory( GALCategory $category, [bool $super = false])

Add this image to the specified category.



Parameters:

GALCategory   $category   The category the image is added to.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method addToGroup [line 1065]

void addToGroup( GALGroup $group, [int $position = 0], [bool $super = false])

Adds this image to the specified group.

Note that the $position parameter is just a raw value and not the real position inside the group.




Parameters:

GALGroup   $group   The group the image is added to.
int   $position   The imagePosition field of the ImageInGroup table.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method canEdit [line 1236]

bool canEdit( GALUser $user)

Check if the specified user has got the privilege to change the image's properties.



Tags:

return:  True if the user can change the image, false otherwise.


Parameters:

GALUser   $user   The user whose privileges are checked.

[ Top ]

method canView [line 1221]

bool canView( GALUser $user)

Check if the specified user has got the privilege to read the image's properties.



Tags:

return:  True if the user can see the image, false otherwise.


Parameters:

GALUser   $user   The user whose privileges are checked.

[ Top ]

method countCategories [line 772]

GALCategoryIterator countCategories( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Counts categories of which this image is member of.

It adds a specially crafted join, a comparison expression and ordering by categoryID to the arguments and passes them to GALTable::extendedCount().




Tags:

see:  GALTable::extendedCount()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method countComments [line 882]

GALCommentIterator countComments( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Counts user comments about this image.

It adds a comparison expression and ordering by commentID to the arguments and passes them to GALTable::extendedCount().




Tags:

see:  GALTable::extendedCount()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method countGroups [line 802]

GALGroupIterator countGroups( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Counts groups of which this image is member of.

It adds a specially crafted join, a comparison expression and ordering by categoryID to the arguments and passes them to GALTable::extendedCount().




Tags:

see:  GALTable::extendedCount()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method countInstances [line 832]

GALInstanceIterator countInstances( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Counts instances of this image.

It adds a comparison expression and ordering by instanceID to the arguments and passes them to GALTable::extendedCount().




Tags:

see:  GALTable::extendedCount()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`createDate` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method countJobs [line 857]

GALJobIterator countJobs( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Counts jobs belonging to this image.

It adds a comparison expression and ordering by jobID to the arguments and passes them to GALTable::extendedCount().




Tags:

see:  GALTable::extendedCount()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`instanceID` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method delete [line 1008]

void delete( [bool $super = false])

Delete the image.

This method deletes the image and all depending objects like user comments, instances and jobs. It removes the image from all groups and categories it belonged to and forces refreshing the cached information of the image's film, series, owner, groups and categories.




Overrides GALTableRow::delete() (Deletes this row from the database.)

Parameters:

bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method get [line 568]

void get( string $field, [bool $super = true])

Read a property via method call.

First of all access control is performed. If successful, properties not corresponding to database fields are handled by this method itself. Properties corresponding to database fields are delegated to the inherited GALRow::get() method. It might seem strange that overriding access control is the default. It is like it is because GALRow::__construct() called by GALImage::__construct reads the row's primary key using the get() method. In our case the original get() method is overridden by the current one, so it has to work in this case without second parameter.




Overrides GALRow::get() (Returns the value of a field.)

Parameters:

string   $field   The propertie's name
bool   $super   TRUE indicates privileged access overriding access control.

[ Top ]

method getGroupPosition [line 1110]

int getGroupPosition( GALGroup $group, [bool $super = false])

Returns the position inside the given GALGroup.

Note that the returned position is just the raw value read from ImageInGroup.imagePosition. If this image isn't member of the given group, this method returns FALSE.




Tags:

return:  The position of the image or false if not member of the group.


Parameters:

GALGroup   $group   The image position inside this group is returned.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method getID [line 618]

int getID( [ $super = false])

The value of the primary key field.

This method provides access to the primary key without knowing the name of the primary key field. This method is implemented by all classes whose tables have a single numerical primary key. At the moment it is only used in GALComments::add(). (Better: It was introduced for GALComments::add() ;-) )




Tags:

return:  The value of the primary key field.


Parameters:

   $super  

[ Top ]

method instance [line 990]

GALInstance instance( int $type, [bool $super = false])

Get a particular instance.



Tags:

return:  The requested instance or FALSE if the instance doesn't exist.


Parameters:

int   $type   The requested instance's instanceID.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method loadCategories [line 634]

GALCategoryIterator loadCategories( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Loads categories of which this image is member of.

It adds a specially crafted join, a comparison expression and ordering by categoryID to the arguments and passes them to GALTable::extendedLoad().




Tags:

see:  GALTable::extendedLoad()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method loadComments [line 744]

GALCommentIterator loadComments( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Loads user comments about this image.

It adds a comparison expression and ordering by commentID to the arguments and passes them to GALTable::extendedLoad().




Tags:

see:  GALTable::extendedLoad()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method loadGroups [line 664]

GALGroupIterator loadGroups( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Loads groups of which this image is member of.

It adds a specially crafted join, a comparison expression and ordering by categoryID to the arguments and passes them to GALTable::extendedLoad().




Tags:

see:  GALTable::extendedLoad()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`title` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method loadInstances [line 694]

GALInstanceIterator loadInstances( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Loads instances of this image.

It adds a comparison expression and ordering by instanceID to the arguments and passes them to GALTable::extendedLoad().




Tags:

see:  GALTable::extendedLoad()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`createDate` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method loadJobs [line 719]

GALJobIterator loadJobs( $expr, [GALOrder $order = ""], [string $limit = ""], [string $additional = ""], [bool $super = false])

Loads jobs belonging to this image.

It adds a comparison expression and ordering by jobID to the arguments and passes them to GALTable::extendedLoad().




Tags:

see:  GALTable::extendedLoad()


Parameters:

GALExpression   $expr  
GALOrder   $order   Can also be an empty string or a string containing sth. like "`instanceID` DESC".
string   $limit  
string   $additional  
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method refresh [line 976]

void refresh( )

Reload cached information.

Force reloading information about membership in categories and groups, about the image's instances and jobs and about user comments. The next time the corresponding properties are read, the information is loaded again.




[ Top ]

method removeFromCategory [line 1174]

void removeFromCategory( GALCategory $category, [bool $super = false])

Remove this image from the specified category.



Parameters:

GALCategory   $category   The category the image is removed from.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method removeFromGroup [line 1130]

void removeFromGroup( GALGroup $group, [bool $super = false])

Remove this image from the specified group.



Parameters:

GALGroup   $group   The group the image is removed from.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method rotate [line 1377]

void rotate( int $angle, [boolean $super = false])

Rotates all instances and updates the 'orientation' property.



Parameters:

int   $angle   One of 90, 180 or 270
boolean   $super   If TRUE, override permission checks.

[ Top ]

method set [line 921]

void set( string $field, mixed $value, [bool $super = false])

Set a property via method call.

First of all access control is performed. If successful, properties not corresponding to database fields are handled by this method itself. Properties corresponding to database fields are delegated to the inherited GALTableRow::set() method. It also updates the changeDate property on every call.




Overrides GALTableRow::set() (Sets the specified field of this row to the specified value.)

Parameters:

string   $field   The propertie's name.
mixed   $value   The propertie's new value.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method setGroupPosition [line 1088]

void setGroupPosition( GALGroup $group, int $position, [bool $super = false])

Sets the position inside the given GALGroup.

Note that the $position parameter is just a raw value and not the real position inside the group. If this image isn't inside the given group, nothing happens, not even an error message.




Parameters:

GALGroup   $group   The group in which the image position is set.
int   $position   The imagePosition field of the ImageInGroup table.
bool   $super   If set to TRUE, access control is overridden.

[ Top ]

method vote [line 1201]

void vote( int $value)

Update the image's score and voteCount properties.

Users with rank >= GAL_RANK_USER can vote for images with permission >= GAL_PERMISSION_PROTECTED. The voteCount property is increased by one.




Parameters:

int   $value   This value is added to the image's score property.

[ Top ]

method __get [line 549]

mixed __get( string $field)

Magic method to read properties.

It internally uses the GALImage::get() method with enforced access control. Library users should not explicitly call the __get() method - it is good for nothing. If you want to read a property with a method call, use get() instead. That method also provides overriding access control if required.




Tags:

return:  The propertie's value.


Overrides GALRow::__get() (Magic method to access this row's fields like native PHP properties.)

Parameters:

string   $field   The requested propertie's name.

[ Top ]

method __set [line 905]

void __set( string $field, mixed $value)

Magic method to set properties It internally uses GALImage::set() with enforced access control.



Overrides GALTableRow::__set() (Magic method to set a field of this row almost like a native PHP property.)

Parameters:

string   $field   The name of the property to set.
mixed   $value   The propertie's new value.

[ Top ]

Documentation generated on Wed, 16 Aug 2006 15:36:11 +0200 by phpDocumentor 1.3.0RC6